/**
 * Copyright (c) 2026 Tencent. All rights reserved.
 * Module:   TXAudioDenoisePlayer @ TXLiteAVSDK
 */

#import <Foundation/Foundation.h>
#import <stdint.h>

#ifndef LITEAVSDK_EXPORT
#define LITEAVSDK_EXPORT __attribute__((visibility("default")))
#endif

NS_ASSUME_NONNULL_BEGIN

/// 错误码
typedef NS_ENUM(NSInteger, TXAudioDenoisePlayerError) {
  TXAudioDenoisePlayerErrorOk = 0,             ///< 操作成功 / 正常播放完成
  TXAudioDenoisePlayerErrorStopped = 1,        ///< 用户主动停止播放
  TXAudioDenoisePlayerErrorInvalidParams = 2,  ///< 参数无效
  TXAudioDenoisePlayerErrorInvalidState = 3,   ///< 当前状态不允许该操作
  TXAudioDenoisePlayerErrorInvalidSource = 4,  ///< 音频数据源无效
  TXAudioDenoisePlayerErrorNetworkError = 5,   ///< 网络错误
  TXAudioDenoisePlayerErrorDecoderError = 6,   ///< 解码错误
  TXAudioDenoisePlayerErrorDenoiserError = 7,  ///< 降噪错误
};

/// 降噪类型
typedef NS_ENUM(NSInteger, TXAudioDenoisePlayerDenoiserType) {
  TXAudioDenoisePlayerDenoiserTypeNone = 0,             ///< 关闭降噪
  TXAudioDenoisePlayerDenoiserTypeHearingFriendly = 1,  ///< 听感友好模式：在降噪的同时尽量保留自然听感
};

/// 播放参数
LITEAVSDK_EXPORT
@interface TXAudioDenoisePlayerParams : NSObject
/// 音频数据源，支持本地路径 file://、http://、https://
@property(nonatomic, copy, nullable) NSString *source;
/// 降噪类型，默认 TXAudioDenoisePlayerDenoiserTypeHearingFriendly
@property(nonatomic, assign) TXAudioDenoisePlayerDenoiserType denoiserType;
/// 初始化，denoiserType 默认设为 TXAudioDenoisePlayerDenoiserTypeHearingFriendly
- (instancetype)init NS_SWIFT_NAME(init());
@end

/// 播放器回调监听器（所有回调均已切换到 UI 线程，调用方无需关心线程安全）
@protocol TXAudioDenoisePlayerListener <NSObject>
@optional
/// 音频真正开始输出时触发；start 失败或开始前被取消不会触发
- (void)onStarted NS_SWIFT_NAME(onStarted());

/// 播放进度
/// @param position 当前位置（毫秒）
/// @param duration 总时长（毫秒），-1 表示未知
- (void)onProgress:(int64_t)position duration:(int64_t)duration NS_SWIFT_NAME(onProgress(_:duration:));

/// 播放任务结束（正常完成 / 主动 stop / 出错）
/// 注意：被新的 start 替换的旧任务不会触发本回调。
/// @param errorCode TXAudioDenoisePlayerError 中的值
/// @param message   错误信息，正常完成或主动停止时为空字符串，SDK 保证不返回 nil
- (void)onCompleted:(int32_t)errorCode message:(NSString *)message NS_SWIFT_NAME(onCompleted(_:message:));
@end

/// 音频降噪播放器
///
/// 播放链路：Audio Source → Decoder → AI Denoiser → Audio Renderer
LITEAVSDK_EXPORT
@interface TXAudioDenoisePlayer : NSObject

/// 创建新实例，调用方通过 ARC 管理生命周期
- (instancetype)init NS_SWIFT_NAME(init());

/// 设置回调监听器，listener 生命周期由调用方管理，传 nil 取消监听
- (void)setListener:(nullable id<TXAudioDenoisePlayerListener>)listener NS_SWIFT_NAME(setListener(_:));

/// 开始播放（异步）。
/// 若已有播放任务，旧任务被静默取消（不触发 onCompleted），新任务开始。
/// source 无效（含为空）时新任务启动失败，经 onCompleted(TXAudioDenoisePlayerErrorInvalidSource, msg) 异步通知。
/// @param params 播放参数
- (void)start:(TXAudioDenoisePlayerParams *)params NS_SWIFT_NAME(start(_:));

/// 停止播放（异步提交），真正停止后触发 onCompleted(TXAudioDenoisePlayerErrorStopped, "")。
/// Idle 状态下调用为空操作，不触发回调。
- (void)stop NS_SWIFT_NAME(stop());

/// 暂停播放（异步提交）
/// 非 Playing 状态下调用为空操作，不触发回调。
- (void)pause NS_SWIFT_NAME(pause());

/// 恢复播放（异步提交）
/// 非 Paused 状态下调用为空操作，不触发回调。
- (void)resume NS_SWIFT_NAME(resume());

/// 设置音量
/// @param volume 范围 [0, 200]，100 为原始音量
- (void)setVolume:(int32_t)volume NS_SWIFT_NAME(setVolume(_:));

/// 跳转到指定位置（异步提交）
/// position < 0 或非 Playing/Paused 状态下调用为空操作，不触发回调。
/// @param position 播放位置（毫秒）
- (void)seekTo:(int64_t)position NS_SWIFT_NAME(seekTo(_:));

/// 获取音频总时长
/// @return 音频总时长（毫秒）；未知或无有效播放任务时返回 -1
- (int64_t)getDuration NS_SWIFT_NAME(getDuration());

/// 实验性 API
/// @param jsonParams JSON 格式的参数字符串
/// @return JSON 格式的返回结果
- (NSString *)callExperimentalAPI:(NSString *)jsonParams NS_SWIFT_NAME(callExperimentalAPI(_:));

@end

NS_ASSUME_NONNULL_END
