实时语音识别 V2

   <key>NSMicrophoneUsageDescription</key>
   <string>需要使用您的麦克风采集音频</string>

/**
 * 初始化方法，调用者使用内置录音器采集音频
 * @param config 配置参数，详见QCloudConfig定义
 */
- (instancetype)initWithConfig:(QCloudConfig *)config;

/**
 * 初始化方法，调用者传递语音数据调用此初始化方法
 * @param config 配置参数，详见QCloudConfig定义
 * @param dataSource 语音数据数据源，必须实现QCloudAudioDataSource协议
 */
- (instancetype)initWithConfig:(QCloudConfig *)config dataSource:(id<QCloudAudioDataSource>)dataSource;

/**
 * 初始化方法-直接鉴权
 * @param appid     腾讯云 appId 
 * @param secretId  腾讯云 secretId
 * @param secretKey 腾讯云 secretKey
 * @param projectId 腾讯云 projectId
 */
- (instancetype)initWithAppId:(NSString *)appid
                     secretId:(NSString *)secretId
                    secretKey:(NSString *)secretKey
                    projectId:(NSInteger)projectId;

/**
 * 初始化方法-通过STS临时证书鉴权，详见https://cloud.tencent.com/document/product/598/33416
 * @param appid     腾讯云appId 
 * @param secretId  腾讯云临时secretId  
 * @param secretKey 腾讯云临时secretKey
 * @param token     对应的token
 */
- (instancetype)initWithAppId:(NSString *)appid
                        secretId:(NSString *)secretId
                           secretKey:(NSString *)secretKey
                        token:(NSString *)token;

/**
 * 获取SDK版本号
 */
+ (NSString*) getVersion;

{
  "code": 0,
  "message": "",
  "sentences": {
    "voice_text_str": "完整识别文本",
    "sentence_list": [
      {
        "sentence_id": 0,
        "sentence_type": 1,
        "speaker_id": 0,
        "sentence": "今天天气真好"
      },
      {
        "sentence_id": 1,
        "sentence_type": 0,
        "speaker_id": -1,
        "sentence": "是的啊"
      }
    ]
  },
  "speaker_context_id": "a1b2c3d4e5f6..."
}

@protocol QCloudRealTimeRecognizerDelegate <NSObject>

@required
/**
 * 原始 JSON 数据回调
 * SDK V2 通过此回调透传服务端返回的原始 JSON，开发者自行解析语音识别结果
 * @param recognizer 实时语音识别实例
 * @param jsonData 服务端返回的 JSON 字符串
 */
- (void)realTimeRecognizerOnRawResult:(QCloudRealTimeRecognizer *)recognizer jsonData:(NSString *)jsonData;


@optional
/**
 * 一次识别成功回调
 @param recognizer 实时语音识别实例
 @param result 一次识别出的总文本, 实际是由SDK本地处理，将本次识别的realTimeRecognizerOnSegmentSuccessRecognize 识别结果拼接后一次性返回
 */
- (void)realTimeRecognizerDidFinish:(QCloudRealTimeRecognizer *)recognizer result:(NSString *)result;
/**
 * 一次识别失败回调
 * @param recognizer 实时语音识别实例
 * @param result 识别结果信息，错误信息详情看QCloudRealTimeResponse内错误码
 */
- (void)realTimeRecognizerDidError:(QCloudRealTimeRecognizer *)recognizer result:(QCloudRealTimeResult *)result;


/**
 * 开始录音回调
 * @param recognizer 实时语音识别实例
 * @param error 开启录音失败，错误信息
 */
- (void)realTimeRecognizerDidStartRecord:(QCloudRealTimeRecognizer *)recognizer error:(NSError *)error;
/**
 * 结束录音回调
 * @param recognizer 实时语音识别实例
 */
- (void)realTimeRecognizerDidStopRecord:(QCloudRealTimeRecognizer *)recognizer;
/**
 * 录音音量实时回调用
 * @param recognizer 实时语音识别实例
 * @param volume 声音音量，取值范围（-40-0)
 */
- (void)realTimeRecognizerDidUpdateVolume:(QCloudRealTimeRecognizer *)recognizer volume:(float)volume;
/**
 * 录音音量实时回调用
 * @param recognizer 实时语音识别实例
 * @param volume 声音音量，计算方式如下$A_{i}$为采集音频振幅值
 * $$A_{mean} = \\frac{1}{n} \\sum_{i=1}^{n} A_{i}^{2}$$
 * $$volume=\\max (10*\\log_{10}(A_{mean}), 0)$$
 */
- (void)realTimeRecognizerDidUpdateVolumeDB:(QCloudRealTimeRecognizer *)recognizer volume:(float)volume;



/**
 * 语音流的开始识别
 * @param recognizer 实时语音识别实例
 * @param voiceId 语音流对应的voiceId，唯一标识
 * @param seq flow的序列号
 */
- (void)realTimeRecognizerOnFlowRecognizeStart:(QCloudRealTimeRecognizer *)recognizer voiceId:(NSString *)voiceId seq:(NSInteger)seq;
/**
 * 语音流的结束识别
 * @param recognizer 实时语音识别实例
 * @param voiceId 语音流对应的voiceId，唯一标识
 * @param seq flow的序列号
 */
- (void)realTimeRecognizerOnFlowRecognizeEnd:(QCloudRealTimeRecognizer *)recognizer voiceId:(NSString *)voiceId seq:(NSInteger)seq;

/**
 * 触发静音事件时回调
 */
-(void)realTimeRecognizerOnSliceDetectTimeOut;

/**
 * 录音停止后回调一次，再次开始录音会清空上一次保存的文件
 * @param recognizer 实时语音识别实例
 * @param audioFilePath 音频文件路径
 */
- (void)realTimeRecognizerDidSaveAudioDataAsFile:(QCloudRealTimeRecognizer *)recognizer
                                   audioFilePath:(NSString *)audioFilePath;

@end

/**
 * 语音数据数据源，如果调用者需要自己提供语音数据需要, 调用者实现此协议中所有方法
 * 提供符合以下要求的语音数据:
 * 采样率：16k
 * 音频格式：pcm
 * 编码：16bit位深的单声道
 */
@protocol QCloudAudioDataSource <NSObject>

@required

/**
 * 标识data source是否开始工作，执行完start后需要设置成YES， 执行完stop后需要设置成NO
 */
@property (nonatomic, assign) BOOL running;

@property (nonatomic, copy, readonly) NSString *audioFilePath;

/**
 * 标识QCloudAudioRecorder是否正在录音
 */
@property (nonatomic, assign, readonly) BOOL recording;

/**
 * SDK会调用start方法，实现此协议的类需要初始化数据源。didStart 是否开始  YES 往下执行，NO不会往下执行
 */
- (void)start:(void(^)(BOOL didStart, NSError *error))completion;
/**
 * SDK会调用stop方法，实现此协议的类需要停止提供数据
 */
- (void)stop;
/**
 * SDK会调用实现此协议的对象的此方法读取语音数据, 如果语音数据不足expectLength，read线程进入休眠。
 * @param expectLength 期望读取的字节数，如果返回的NSData不足expectLength个字节，SDK会抛出异常。
 */
- (nullable NSData *)readData:(NSInteger)expectLength;

@end

// 设置log等级为DEBUG级，上生产环境可选择VOICE_SDK_ERROR_LEVEL级别的log
[QCloudVoiceLogger setLoggerLevel:VOICE_SDK_DEBUG_LEVEL];
// 将log写入本地磁盘，demo工程默认打开，宿主层接入上生产环境需要关闭。
[QCloudVoiceLogger needLogFile:YES];
// (可选)注册log回调
[QCloudVoiceLogger registerLoggerListener:^(VoiceLoggerLevel loggerLevel, NSString * _Nonnull logInfo) {
        NSLog(@"[ASR]-%@",logInfo);
} withNativeLog:NO];

/**
 * 实时语音识别 SDK 内部状态。
 *
 *  - None        ：空闲，无识别任务。此时可以安全地调用 -start 启动新的会话。
 *  - Start       ：已调用 -start，正在建立 WebSocket 连接，但尚未连接成功。
 *  - Stop        ：已调用 -stop，录音已结束，正在等待服务端返回 final 结果。
 *  - Recognizing ：WebSocket 已连接成功，录音线程正在运行并持续发送音频。
 *
 */
typedef NS_ENUM(NSInteger, QCloudASRRealTimeRecognizeState) {
    QCloudASRRealTimeRecognizeStateNone = 0,
    QCloudASRRealTimeRecognizeStateStart,
    QCloudASRRealTimeRecognizeStateStop,
    QCloudASRRealTimeRecognizeStateRecognizing
};

/**
 * 获取当前 SDK 内部录音识别状态。与直接读取 -state 属性等价，该方法线程安全，可在任意线程调用。
 * @return 当前状态，详见 QCloudASRRealTimeRecognizeState 注释
 */
- (QCloudASRRealTimeRecognizeState)getAudioRecognizeState;

/**
 * 判断当前是否可以发起一次新的录音识别。
 *
 * 推荐在调用 -start 前先用此方法判断，避免在 SDK 还在 "建立连接 / 识别中 / 等待 final"
 * 的中间态时重复调用 -start 导致行为未定义。
 *
 * @return YES：当前为 None 状态，可以安全调用 -start；
 *         NO ：当前处于其它状态，请勿直接调 -start；若要强行重置，请调用 -cancel。
 */
- (BOOL)canStartAudioRecognize;

/**
 * 判断当前 SDK 状态是否需要外部调用 -cancel 来重置内部状态。
 *
 * 在某些异常路径下（如 WebSocket 建连过程中网络抖动、stop 后服务端长时间不返回 final），
 * SDK 会停留在 Start / Recognizing / Stop 中间态。此时如果业务侧需要立即开启下一次识别，
 * 应先调用 -cancel 把状态强制重置回 None。
 *
 * @return YES：当前停留在 Start / Recognizing / Stop 中间态，建议调用 -cancel 重置；
 *         NO ：当前为 None，无需 cancel。
 */
- (BOOL)needCancelToResetState;

// 开始新一轮识别前的标准 SOP
if ([recognizer canStartAudioRecognize]) {
    [recognizer start];
} else if ([recognizer needCancelToResetState]) {
    // SDK 停留在 Start/Stop 中间态，强制重置后再启动
    [recognizer cancel];
    [recognizer start];
} else {
    // 当前已在 Recognizing，按业务需要决定是否 stop 后再 start
}

// 任意时刻查询状态
QCloudASRRealTimeRecognizeState state = [recognizer getAudioRecognizeState];