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

#pragma once

#include <cstdint>

#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 ITXAudioDenoisePlayer;
}

/// 创建和销毁实例
extern "C" LITEAVSDK_API liteav::ITXAudioDenoisePlayer* TXAudioDenoisePlayerCreate();
extern "C" LITEAVSDK_API void TXAudioDenoisePlayerDestroy(liteav::ITXAudioDenoisePlayer* instance);

namespace liteav {

/// 错误码
enum class TXAudioDenoisePlayerError {
  kOk = 0,             /// 操作成功 / 正常播放完成
  kStopped = 1,        /// 用户主动停止播放
  kInvalidParams = 2,  /// 参数无效
  kInvalidState = 3,   /// 当前状态不允许该操作
  kInvalidSource = 4,  /// 音频数据源无效
  kNetworkError = 5,   /// 网络错误
  kDecoderError = 6,   /// 解码错误
  kDenoiserError = 7,  /// 降噪错误
};

/// 降噪类型
enum class TXAudioDenoisePlayerDenoiserType {
  kNone = 0,             /// 关闭降噪
  kHearingFriendly = 1,  /// 听感友好模式：在降噪的同时尽量保留自然听感
};

/// 播放参数
struct TXAudioDenoisePlayerParams {
  /// 音频数据源，支持本地路径 file://、http://、https://
  /// start() 内部会立即复制，调用方无需保证生命周期
  const char* source = nullptr;

  /// 降噪类型，默认听感友好模式
  TXAudioDenoisePlayerDenoiserType denoiserType =
      TXAudioDenoisePlayerDenoiserType::kHearingFriendly;
};

/// 播放器回调
/// @note 所有回调均已切换到 UI 线程，调用方无需关心线程安全
class ITXAudioDenoisePlayerListener {
 public:
  virtual ~ITXAudioDenoisePlayerListener() = default;

  /// 音频真正开始输出时触发；start() 失败或开始前被取消不会触发
  virtual void onStarted() {}

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

  /// 播放任务结束（正常完成 / 主动 stop / 出错）
  /// @note 被新的 start() 替换的旧任务不会触发本回调
  /// @param errorCode TXAudioDenoisePlayerError 中的值
  /// @param message   错误信息，正常完成或主动停止时为空字符串 ""，SDK 保证不返回 nullptr
  virtual void onCompleted(int32_t errorCode, const char* message) {}
};

/// 音频降噪播放器
///
/// 播放链路：Audio Source → Decoder → AI Denoiser → Audio Renderer
class ITXAudioDenoisePlayer {
 public:
  virtual ~ITXAudioDenoisePlayer() = default;

  /// 设置事件回调，listener 生命周期由调用方管理，传 nullptr 取消监听
  virtual void setListener(ITXAudioDenoisePlayerListener* listener) = 0;

  /// 开始播放（异步）
  /// 若已有播放任务，旧任务被静默取消（不触发 onCompleted），新任务开始
  /// source 无效（含为空）时新任务启动失败，经 onCompleted(kInvalidSource, msg) 异步通知
  virtual void start(const TXAudioDenoisePlayerParams& params) = 0;

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

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

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

  /// 设置音量，范围 [0, 200]，100 为原始音量
  virtual void setVolume(int32_t volume) = 0;

  /// 跳转到指定位置（毫秒，异步提交）
  /// position < 0 或非 Playing/Paused 状态下调用为空操作，不触发回调
  virtual void seekTo(int64_t position) = 0;

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

  /// 实验性 API
  /// 返回字符串由 SDK 管理，至少在下次调用或销毁前有效
  virtual const char* callExperimentalAPI(const char* jsonParams) = 0;
};

}  // namespace liteav
