# Online Speech SDK 接入说明

本文档面向三方开发者，说明 `online-speech` SDK 的接入依赖、初始化与调用方式。

## 1. 模块说明

- `sdk`：纯 Kotlin/JVM 在线 ASR/TTS SDK
- `sdk-android-open`：Android 适配层（接入 `open-sdk` 录音、默认流式播放）
- `demo-android`：示例应用（仅用于功能验证）

## 2. 环境依赖

### 2.1 构建环境

- JDK 17
- Android Gradle Plugin 8.2.2（Android 模块）
- Kotlin 2.2.0

### 2.2 运行环境（Android）

- `minSdk = 26`
- 需要权限：
  - `android.permission.INTERNET`
  - `android.permission.RECORD_AUDIO`（ASR 麦克风模式）

## 3. 依赖接入

先在工程仓库配置里加入 Rokid Maven（外部地址）：

- `https://maven.rokid.com/repository/maven-public/`

`settings.gradle(.kts)` 示例：

```kotlin
dependencyResolutionManagement {
    repositories {
        maven(url = "https://maven.rokid.com/repository/maven-public/")
        google()
        mavenCentral()
    }
}
```

或老版本 Gradle 在根 `build.gradle(.kts)` 的 `allprojects.repositories` 中添加同样地址。

必须依赖以下坐标：

- `com.rokid.security.sdk:online-speech:0.1.0`
- `com.rokid.security:glass3.open.sdk:2.1.6-E`

应用工程示例：

```kotlin
dependencies {
    implementation("com.rokid.security.sdk:online-speech:0.1.0")
    implementation("com.rokid.security:glass3.open.sdk:2.1.6-E")
}
```

## 4. SDK 初始化与调用

### 4.1 初始化

```kotlin
val cfg = OnlineSpeechSdkConfig(
    domain = "api-test.rokid.com",
    ak = "<AK>",
    sk = "<SK>",
    uid = "<UID>",
    deviceId = "<DEVICE_ID>",
    asrPath = "/ar/audio/api/ws/asr/streaming",
    ttsPath = "/ar/audio/api/ws/tts",
    trustAllCerts = true, // 调试可开，生产建议关闭
    staticHttpHeaders = mapOf(
        "appCredential" to "userInfo",
        "messageId" to "msg-${System.currentTimeMillis()}",
    ),
    staticMessageHeaders = mapOf(
        "appCredential" to "userInfo",
        "messageId" to "msg-${System.currentTimeMillis()}",
    ),
)
val sdk = OnlineSpeechSdk(cfg)
```

### 4.2 ASR（推荐高层一键）

```kotlin
val asr = sdk.createAsrClient()
    .attachAudioSource(OpenSdkAudioSource())

asr.connect()
asr.startAsrWithMic()
// ...
asr.stopAsrWithMic()
```


### 4.3 TTS

```kotlin
val tts = sdk.createTtsClient()
    .attachStreamPlayer(AndroidPcmTtsStreamPlayer())

tts.connect()
tts.speak("你好，欢迎使用在线语音 SDK。")
tts.stop()
```

可监听播放状态：

- `IDLE`
- `BUFFERING`
- `PLAYING`
- `COMPLETED`
- `STOPPED`
- `FAILED`

## 5. 生命周期建议

- 页面 `onStart/onResume`：按需 `connect()`
- 页面 `onStop/onDestroy`：调用 `close()` 释放 WebSocket
- 应用退出：`sdk.close()`

## 6. 常见问题

- WebSocket 超时：优先核对 `domain/asrPath/ttsPath` 与证书策略
- ASR 无结果：确认先 `asr.connect()`，再 `asr.startAsrWithMic()`
- TTS 无声音：确认先 `tts.connect()`，检查设备音量和音频路由
