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

#pragma once

#include <stddef.h>
#include <stdint.h>

#ifndef LITEAVSDK_API
#if defined(_WIN32)
#ifdef LITEAV_EXPORTS
#define LITEAVSDK_API __declspec(dllexport)
#else
#define LITEAVSDK_API __declspec(dllimport)
#endif
#else
#define LITEAVSDK_API __attribute__((visibility("default")))
#endif
#endif  // LITEAVSDK_API


namespace liteav {
  class ITXRealtimeASR;
}
/// 创建和销毁实例
extern "C" LITEAVSDK_API liteav::ITXRealtimeASR* TXRealtimeASRCreate();
extern "C" LITEAVSDK_API void TXRealtimeASRDestroy(liteav::ITXRealtimeASR* instance);

namespace liteav {

/// 单个转录消息（句子级/段级）
struct TXRealtimeASRMessage {
  const char* segmentId = nullptr;     ///< 消息段的唯一标识 ID
  const char* sourceText = nullptr;    ///< 识别出的源语言文本（对应协议 voice_text_str）
  bool isCompleted = false;            ///< 转录是否结束：false=进行中（中间结果），true=已说完（稳态结果）
  int speakerId = -1;                  ///< 说话人ID，-1=未知
  int startTime = -1;                  ///< 本消息在整个音频流中的起始时间（毫秒），-1=未知
  int endTime = -1;                    ///< 本消息在整个音频流中的结束时间（毫秒），-1=未知
};

/// 启动转录参数
struct TXRealtimeASRParams {
  const char* sdkAppId = nullptr;       ///< TRTC 应用 ID
  const char* userSig = nullptr;        ///< TRTC 用户签名
  const char* voiceId = nullptr;        ///< 识别会话 ID，建议客户每次调用时重新生成UUID传入

  const char* sourceLanguage = nullptr; ///< 识别语言，如 "zh"、"en"，留空即为自动识别
  bool enableCustomCapture = false;     ///< 是否启用自定义音频采集
};

/// 实时语音转录回调接口
/// @note 所有回调均已切换到 UI 线程，调用方无需关心线程安全
class TXRealtimeASRListener {
 public:
  virtual ~TXRealtimeASRListener() {}

  /// 实时转录开启成功的回调
  /// @param voiceId 识别会话 ID
  virtual void onRealtimeASRStarted(const char* voiceId) {}

  /// 收到实时转录消息的回调
  /// @param message 转录消息，包含转录文本和完成状态
  virtual void onReceiveRealtimeASRMessage(const TXRealtimeASRMessage& message) {}

  /// 实时转录停止的回调（正常停止）
  virtual void onRealtimeASRStopped() {}

  /// 实时转录出错的回调
  /// @param errorCode 错误码（非 0 表示异常）
  /// @param errorMsg 错误信息
  virtual void onRealtimeASRError(int errorCode, const char* errorMsg) {}

  /// 实时音量回调
  /// @param volume 音量等级 [0, 100]
  virtual void onRealtimeASRVolume(int volume) {}
};

class ITXRealtimeASR {
 public:
  virtual void addListener(TXRealtimeASRListener* listener) = 0;
  virtual void removeListener(TXRealtimeASRListener* listener) = 0;
  virtual void startRealtimeASR(const TXRealtimeASRParams& params) = 0;
  virtual void stopRealtimeASR() = 0;

  /// 自定义采集时，送入 PCM 音频数据
  virtual void feedPcmData(const int16_t* data, size_t length, uint32_t sampleRate, uint32_t channels) = 0;

  /// 实验性 API 调用接口
  virtual const char* callExperimentalAPI(const char* jsonStr) = 0;

  virtual ~ITXRealtimeASR() = default;
};

}  // namespace liteav
