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

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

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

NS_ASSUME_NONNULL_BEGIN

/// 引擎模式（对应 TXRealtimeTTSMode）
typedef NS_ENUM(NSInteger, TXRealtimeTTSMode) {
  TXRealtimeTTSModeOnline = 0,   ///< 纯在线（WebSocket/HTTP）
  TXRealtimeTTSModeOffline = 1,  ///< 纯离线（本地引擎，无网可用）
  TXRealtimeTTSModeMix = 2,  ///< 混合：优先在线，弱网自动降级离线，恢复后回切
};

typedef NS_ENUM(NSInteger, TXRealtimeTTSError) {
  // -------- 基础错误码 [1, 100) --------
  TXRealtimeTTSErrorOk = 0,
  TXRealtimeTTSErrorInvalidState = 1,  ///< 状态不允许（如已处于 Started 状态时再次调用 Start）
  TXRealtimeTTSErrorInvalidParam = 2,  ///< 配置字段非法
  TXRealtimeTTSErrorNotImplement = 3,  ///< 功能尚未实现（如 pause/resume/setSpeed/在线模式等）

  // -------- 离线 TTS 错误码 [100, 200) --------
  TXRealtimeTTSErrorOfflineUnknownError = 100,  ///< 未识别的离线引擎状态（防御性兜底）
  TXRealtimeTTSErrorOfflineInvalidState = 101,    ///< 离线引擎内部状态非法
  TXRealtimeTTSErrorOfflineResourceError = 102,   ///< 通用/音色资源加载失败
  TXRealtimeTTSErrorOfflineModelError = 103,      ///< 模型加载或推理失败
  TXRealtimeTTSErrorOfflineLicenseInvalid = 104,  ///< 授权文件无效
  TXRealtimeTTSErrorOfflineLicenseExpired = 105,  ///< 授权文件已过期

  // -------- 在线 TTS 错误码 [200, 300) --------
  TXRealtimeTTSErrorOnlineUnknownError = 200,  ///< 未识别的在线引擎状态（防御性兜底）
  TXRealtimeTTSErrorOnlineNetworkError = 201,  ///< 网络错误
  TXRealtimeTTSErrorOnlineServerError = 202,   ///< 服务端错误
  TXRealtimeTTSErrorOnlineInvalidUserSig = 203,  ///< UserSig 无效（过期/解析失败/校验失败等）
};

/// 音频输出模式（对应 AudioOutputMode）
typedef NS_ENUM(NSInteger, TXRealtimeTTSAudioOutputMode) {
  TXRealtimeTTSAudioOutputModePlaybackOnly = 0,         ///< 仅播放音频，不回调音频帧
  TXRealtimeTTSAudioOutputModeCallbackOnly = 1,         ///< 仅回调音频帧，不播放
  TXRealtimeTTSAudioOutputModePlaybackAndCallback = 2,  ///< 既播放音频又回调音频帧
};

/// 在线/混合鉴权（online / mix 必填）
LITEAVSDK_EXPORT
@interface TXRealtimeTTSOnlineCredential : NSObject
@property(nonatomic, copy, nullable) NSString *appId;   ///< 应用 appid
@property(nonatomic, copy, nullable) NSString *userId;  ///< 用户 id
@property(nonatomic, copy, nullable)
    NSString *userSig;  ///< 用户签名（服务端下发，避免密钥打包进客户端）
@end

/// 离线/混合鉴权（offline / mix 必填）
LITEAVSDK_EXPORT
@interface TXRealtimeTTSOfflineLicense : NSObject
@property(nonatomic, copy, nullable) NSString *licenseUrl;  ///< 离线授权文件下载/校验地址
@property(nonatomic, copy, nullable) NSString *licenseKey;  ///< 离线授权 key
@end

/// 统一参数（必填项）；其余可选参数一律通过 callExperimentalAPI 设置
LITEAVSDK_EXPORT
@interface TXRealtimeTTSParams : NSObject
@property(nonatomic, assign)
    TXRealtimeTTSMode mode;  ///< 引擎模式：在线 / 离线 / 混合（默认 TXRealtimeTTSModeOnline）
@property(nonatomic, strong, nullable)
    TXRealtimeTTSOnlineCredential *online;  ///< mode=online/mix 必填
@property(nonatomic, strong, nullable)
    TXRealtimeTTSOfflineLicense *offline;  ///< mode=offline/mix 必填
@property(nonatomic, copy, nullable)
    NSString *voiceName;  ///< 音色（音色名，必填；未设置时为 nil，使用前须赋值）
@property(nonatomic, assign) TXRealtimeTTSAudioOutputMode
    audioOutputMode;  ///< 音频输出模式：仅播放 / 仅回调 / 播放并回调（默认
                      ///< TXRealtimeTTSAudioOutputModePlaybackOnly）
/// 初始化。会将 mode 默认设为 TXRealtimeTTSModeOnline、audioOutputMode 默认设为
/// TXRealtimeTTSAudioOutputModePlaybackOnly；voiceName 初始为 nil（必填，使用前须设置）。
- (instancetype)init;
@end

/// 音频输出帧（onSynthesizedAudioFrame: 回调参数）
LITEAVSDK_EXPORT
@interface TXSynthesizeAudioFrame : NSObject
@property(nonatomic, strong, nullable)
    NSData *pcmData;  ///< 本次音频 PCM 字节；对象仅在回调内有效，跨线程/异步使用须深拷贝（如 copy）
@property(nonatomic, assign) uint32_t pcmDataSize;   ///< pcmData 字节数
@property(nonatomic, assign) uint32_t sampleRate;    ///< 音频采样率（Hz），如 16000/48000
@property(nonatomic, assign) uint32_t channelCount;  ///< 音频通道数，1=单声道，2=双声道
@property(nonatomic, assign) uint32_t bitWidth;      ///< 采样位宽（bit），固定 16
@property(nonatomic, copy, nullable)
    NSString *textId;  ///< 文本标识（对应 appendText 的 textId，标示本次数据所属的文本段）
@property(nonatomic, copy, nullable) NSString *textSlice;  ///< 当前合成的数据所属的文本片段
@property(nonatomic, assign)
    double progress;  ///< textSlice 在 textId 对应文本段中的百分比 [0.0, 1.0]
@end

/// 回调监听器（所有回调在 SDK 内部线程触发，请勿在回调中执行耗时操作）
@protocol TXRealtimeTTSListener <NSObject>
@optional
/// 合成开始（鉴权通过 / 会话已建立），可在此切换 UI 状态
/// @return 无返回值
- (void)onStarted;

/// 文本播放进度回调：逐片回调（流式）
/// @param textId 当前文本段标识
/// @param textSlice 正在播放的文本切片
/// @return 无返回值
- (void)onPlaybackProgress:(NSString *)textId textSlice:(NSString *)textSlice;

/// 合成进度回调。仅当 audioOutputMode 为 TXRealtimeTTSAudioOutputModeCallbackOnly 或
/// TXRealtimeTTSAudioOutputModePlaybackAndCallback 时触发
/// @param audioFrame 本次合成的音频帧（TXSynthesizeAudioFrame）
/// @return 无返回值
- (void)onSynthesizedAudioFrame:(TXSynthesizeAudioFrame *)audioFrame;

/// 合成结束（成功或失败）
/// @param code 错误码，== TXRealtimeTTSErrorOk 表示成功完成；否则表示任意阶段失败
/// @param msg 错误信息（仅回调期间有效，可为 nil）
/// @return 无返回值
- (void)onCompleted:(int32_t)code msg:(nullable NSString *)msg;
@end

/// 实时语音合成引擎接口。直接 alloc/init 创建实例即可。
LITEAVSDK_EXPORT
@interface TXRealtimeTTS : NSObject

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

/// 设置回调监听器（对应 setListener）。传 nil 可取消监听。
/// 所有回调在 SDK 内部线程触发，请勿在回调中执行耗时操作。
/// @param listener 事件回调监听器（TXRealtimeTTSListener 实现；传 nil 可取消监听）
/// @return 返回 TXRealtimeTTSError 中的值
- (int)setListener:(nullable id<TXRealtimeTTSListener>)listener;

/// 开始合成（对应 start）
/// @param param 配置参数（TXRealtimeTTSParams）
/// @return 返回 TXRealtimeTTSError 中的值
- (int)start:(TXRealtimeTTSParams *)param;

/// 停止合成（对应 stop）
/// @return 返回 TXRealtimeTTSError 中的值
- (int)stop;

/// 暂停合成与播放（对应 pause）
/// @return 返回 TXRealtimeTTSError 中的值
- (int)pause;

/// 恢复合成与播放（对应 resume）
/// @return 返回 TXRealtimeTTSError 中的值
- (int)resume;

/// 清空当前待播放与待合成的文本数据。
/// 调用 clear 之后，SDK 内部会立即丢弃所有排队文本，且保证不会再触发任何属于 clear 前 textId
/// 的进度回调
/// @return 返回 TXRealtimeTTSError 中的值
- (int)clear;

/// 追加待合成文本（流式输入，对应 appendText）。
/// @param textId 文本标识（UTF-8，用于标识本次追加的文本）
/// @param text 文本内容（UTF-8，必填）
/// @param isEnd 是否为本段文本的最后一片，true 表示文本输入结束
/// @return 返回 TXRealtimeTTSError 中的值
- (int)appendText:(NSString *)textId text:(NSString *)text isEnd:(BOOL)isEnd;

/// 设置音量
/// @param volume 音量值，取值范围 [0, 200]，默认 100 = 正常
/// @return 返回 TXRealtimeTTSError 中的值
- (int)setVolume:(float)volume;

/// 设置语速
/// @param speed 语速值，取值范围 [1, 3]，默认 1 = 正常
/// @return 返回 TXRealtimeTTSError 中的值
- (int)setSpeed:(float)speed;

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

@end

NS_ASSUME_NONNULL_END
