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

#import <Foundation/Foundation.h>

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

NS_ASSUME_NONNULL_BEGIN

#pragma mark - 转录消息模型

LITEAVSDK_EXPORT
@interface TXRealtimeASRMessage : NSObject

@property (nonatomic, readonly) NSString *segmentId;       ///< 消息段的唯一标识 ID
@property (nonatomic, readonly) NSString *sourceText;      ///< 识别出的源语言文本（对应协议 voice_text_str）
@property (nonatomic, readonly) BOOL isCompleted;          ///< 转录是否结束：NO=进行中（中间结果），YES=已说完（稳态结果）
@property (nonatomic, readonly) int speakerId;             ///< 说话人ID，-1=未知
@property (nonatomic, readonly) int startTime;             ///< 本消息在整个音频流中的起始时间（毫秒），-1=未知
@property (nonatomic, readonly) int endTime;               ///< 本消息在整个音频流中的结束时间（毫秒），-1=未知

/// 初始化转录消息
- (instancetype)initWithSegmentId:(NSString *)segmentId
                       sourceText:(NSString *)sourceText
                      isCompleted:(BOOL)isCompleted
                        speakerId:(int)speakerId
                        startTime:(int)startTime
                          endTime:(int)endTime;

@end

#pragma mark - 启动参数模型

LITEAVSDK_EXPORT
@interface TXRealtimeASRParams : NSObject

@property (nonatomic, copy) NSString *sdkAppId;          ///< TRTC 应用 ID
@property (nonatomic, copy) NSString *userSig;           ///< TRTC 用户签名
@property (nonatomic, copy) NSString *voiceId;           ///< 识别会话 ID，建议客户每次调用时重新生成UUID传入

@property (nonatomic, copy) NSString *sourceLanguage;    ///< 识别语言，如 "zh"、"en"，留空即为自动识别
@property (nonatomic, assign) BOOL enableCustomCapture;  ///< 是否启用自定义音频采集

@end

#pragma mark - 实时转录回调协议

@protocol TXRealtimeASRListener <NSObject>

@optional

/// 实时转录开启成功的回调
/// @param voiceId 识别会话 ID
/// @note 已切到主线程
- (void)onRealtimeASRStarted:(NSString *)voiceId NS_SWIFT_NAME(onRealtimeASRStarted(_:));

/// 收到实时转录消息的回调
/// @param message 转录消息，包含转录文本和完成状态
/// @note 已切到主线程
- (void)onReceiveRealtimeASRMessage:(TXRealtimeASRMessage *)message NS_SWIFT_NAME(onReceiveRealtimeASRMessage(_:));

/// 实时转录停止的回调（正常停止）
/// @note 已切到主线程
- (void)onRealtimeASRStopped NS_SWIFT_NAME(onRealtimeASRStopped());

/// 实时转录出错的回调
/// @param errorCode 错误码（非 0 表示异常）
/// @param errorMsg 错误信息
/// @note 已切到主线程
- (void)onRealtimeASRError:(int)errorCode errorMsg:(NSString *)errorMsg NS_SWIFT_NAME(onRealtimeASRError(_:errorMsg:));

/// 实时音量回调
/// @param volume 音量等级 [0, 100]
/// @note 已切到主线程
- (void)onRealtimeASRVolume:(int)volume NS_SWIFT_NAME(onRealtimeASRVolume(_:));

@end

#pragma mark - 实时转录引擎接口

LITEAVSDK_EXPORT
@interface TXRealtimeASR : NSObject

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

- (void)addListener:(id<TXRealtimeASRListener>)listener NS_SWIFT_NAME(addListener(_:));
- (void)removeListener:(id<TXRealtimeASRListener>)listener NS_SWIFT_NAME(removeListener(_:));

/// 开始实时语音转录会话
- (void)startRealtimeASR:(TXRealtimeASRParams *)params NS_SWIFT_NAME(startRealtimeASR(_:));

/// 停止实时转录，等后端算完后回调 onRealtimeASRStopped 或 onRealtimeASRError
- (void)stopRealtimeASR NS_SWIFT_NAME(stopRealtimeASR());

/// 自定义采集时，送入 PCM 音频数据
- (void)feedPcmData:(NSData *)data sampleRate:(uint32_t)sampleRate channels:(uint32_t)channels NS_SWIFT_NAME(feedPcmData(_:sampleRate:channels:));

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

@end

NS_ASSUME_NONNULL_END
