SellyCloudSDK

SellyRTC Android SDK 接入文档

本文档介绍如何在 Android 中使用 SellyRTC 快速集成一对一或多人音视频通话功能，包括：
- 基本接入
- 音视频控制
- 数据处理（如美颜）
- 事件回调
- 通话统计
- Token 生成与更新机制

---

## 目录
1. 准备工作
2. 快速开始
    - 创建引擎
    - 设置本地/远端画面
    - 配置视频参数
    - 加入频道
    - 结束通话
3. 常用功能
    - 开关本地音视频
    - 切换摄像头
    - 静音远端音视频
    - 音频输出控制（扬声器 / 听筒）
    - 发送自定义消息
    - 美颜开关
4. 视频帧处理（美颜等）
5. 事件回调 (InteractiveRtcEngineEventHandler)
6. 通话统计
7. Token 过期机制
8. 常见问题

---

# 1. 准备工作

## 1.1 集成 SellyCloudSDK

或如果目前是通过本地 AAR 集成（demo 方式）：

```gradle
dependencies {
    implementation files("libs/sellycloudsdk-release.aar")
}
```

> 注意：如果你的业务侧还依赖 WebRTC、ijkplayer、美颜等第三方库，请保持与 SDK Demo 中的依赖版本一致。

## 1.2 必要权限

在 `AndroidManifest.xml` 中声明音视频必需权限：

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

在 Android 6.0+ 设备上，运行时还需要动态申请权限，示例见后文（Demo 中的 `requiredPermissions` + `ActivityResultContracts.RequestMultiplePermissions` 已经实现）。

## 1.3 获取 AppId / Secret / Token

从 SellyCloud 控制台获取：

- `signaling_app_id`
- `signaling_secret`（用于服务端生成 Token）
- 或直接配置一个测试用的 `signaling_token`

在 Demo 中，这些值通常配置在 `res/values/strings.xml`：

```xml
<string name="signaling_app_id">your-app-id</string>
<string name="signaling_secret">your-secret</string>
<string name="signaling_token"></string> <!-- 可选：直接写死 token -->
```

> 生产环境建议：  
> 不要在 App 里写 secret，而是在你们自己的业务服务器上生成 Token，App 只向服务器请求 Token。

---

# 2. 快速开始

以下示例基于 Demo 中的 `InteractiveLiveActivity`，展示最小接入流程。

## 2.1 创建引擎 InteractiveRtcEngine

在 `Activity` 中创建并配置 RTC 引擎：

```kotlin
private var rtcEngine: InteractiveRtcEngine? = null
private var beautyRenderer: FURenderer? = null
private var fuFrameInterceptor: FuVideoFrameInterceptor? = null
@Volatile private var isFrontCamera = true
@Volatile private var beautyEnabled: Boolean = true

private fun initRtcEngine() {
    val appId = getString(R.string.signaling_app_id)
    val token = getString(R.string.signaling_token).takeIf { it.isNotBlank() }

    // 可选：初始化美颜
    beautyRenderer = FURenderer(this).also { it.setup() }
    fuFrameInterceptor = beautyRenderer?.let {
        FuVideoFrameInterceptor(it).apply {
            setFrontCamera(isFrontCamera)
            setEnabled(beautyEnabled)
        }
    }

    rtcEngine = InteractiveRtcEngine.create(
        InteractiveRtcEngineConfig(
            context = applicationContext,
            appId = appId,
            defaultToken = token
        )
    ).apply {
        // 设置回调
        setEventHandler(rtcEventHandler)

        // 角色：主播/观众，Demo 里默认主播（BROADCASTER）
        setClientRole(InteractiveRtcEngine.ClientRole.BROADCASTER)

        // 配置视频参数（可选，见下一节）
        setVideoEncoderConfiguration(
            InteractiveVideoEncoderConfig(
                width = 640,
                height = 480,
                fps = 20,
                minBitrateKbps = 150,
                maxBitrateKbps = 350
            )
        )

        // 默认走扬声器
        setDefaultAudioRoutetoSpeakerphone(true)

        // 视频采集前拦截（用于美颜等）
        setCaptureVideoFrameInterceptor { frame ->
            if (!beautyEnabled) return@setCaptureVideoFrameInterceptor frame
            fuFrameInterceptor?.process(frame) ?: frame
        }
    }
}
```

生命周期注意：  
在 `onDestroy` 中记得 `leaveChannel()` 并销毁引擎，避免内存泄漏：

```kotlin
override fun onDestroy() {
    super.onDestroy()
    rtcEngine?.setCaptureVideoFrameInterceptor(null)
    leaveChannel()
    InteractiveRtcEngine.destroy(rtcEngine)
    rtcEngine = null
    // 释放 renderer / 美颜资源...
}
```

## 2.2 设置本地 & 远端画面

SellyRTC 使用 `InteractiveVideoCanvas + SurfaceViewRenderer` 来承载视频画面。

### 初始化本地与远端渲染 View

```kotlin
private var localRenderer: SurfaceViewRenderer? = null
private val remoteRendererMap = mutableMapOf<String, SurfaceViewRenderer>()

private fun createRenderer(): SurfaceViewRenderer =
    SurfaceViewRenderer(this).apply {
        setZOrderMediaOverlay(false)
    }

private fun setupVideoSlots() {
    // 本地 slot
    if (localRenderer == null) {
        localRenderer = createRenderer()
    }
    localRenderer?.let { renderer ->
        // Demo 中使用自定义的 VideoReportLayout 来承载
        binding.flLocal.attachRenderer(renderer)
    }

    // 远端 slot 见 Demo 中的 remoteSlots / ensureRemoteRenderer
}
```

### 绑定本地视频

在加入频道前/时，设置本地视频 canvas：

```kotlin
val renderer = localRenderer ?: createRenderer().also { localRenderer = it }
rtcEngine?.setupLocalVideo(InteractiveVideoCanvas(renderer, localUserId))
```

### 绑定远端视频

在 `onUserJoined` 或业务逻辑中，为某个 `userId` 分配一个远端窗口：

```kotlin
private fun ensureRemoteRenderer(userId: String): SurfaceViewRenderer {
    return remoteRendererMap[userId] ?: createRenderer().also { renderer ->
        remoteRendererMap[userId] = renderer
        rtcEngine?.setupRemoteVideo(InteractiveVideoCanvas(renderer, userId))
    }
}
```

> 多人会议：为不同的 `userId` 分配不同的 View / slot，即可实现多路画面显示。

## 2.3 配置视频参数（可选）

视频编码参数需要在加入频道前配置：

```kotlin
rtcEngine?.setVideoEncoderConfiguration(
    InteractiveVideoEncoderConfig(
        width = 640,
        height = 480,
        fps = 20,
        minBitrateKbps = 150,
        maxBitrateKbps = 350
    )
)
// 不设置则使用 SDK 默认配置
```

## 2.4 加入频道 / 发起通话

### 1）准备 CallType 等入会参数

```kotlin
val options = InteractiveChannelMediaOptions(
    callType = if (isP2P) CallType.ONE_TO_ONE else CallType.GROUP
)
```

其中：

- `CallType.ONE_TO_ONE`：一对一视频通话
- `CallType.GROUP`：多人会议 / 互动直播

### 2）生成 Token

Demo 中的策略（简化）：

```kotlin
private val defaultTokenTtlSeconds = InteractiveCallConfig.DEFAULT_TOKEN_TTL_SECONDS

private fun buildToken(appId: String, callId: String, userId: String): TokenBundle? {
    val manualToken = getString(R.string.signaling_token).takeIf { it.isNotBlank() }
    if (manualToken != null) {
        return TokenBundle(
            token = manualToken,
            expiresAtSec = parseExprTime(manualToken),
            secret = null
        )
    }

    val secret = getString(R.string.signaling_secret)
    if (secret.isBlank()) {
        Toast.makeText(
            this,
            "请在 strings.xml 配置 signaling_secret 用于生成 token，或直接填写 signaling_token",
            Toast.LENGTH_LONG
        ).show()
        return null
    }

    return try {
        val generated = TokenGenerator.generate(
            appId = appId,
            userId = userId,
            callId = callId,
            secret = secret,
            ttlSeconds = defaultTokenTtlSeconds
        )
        TokenBundle(
            token = generated.token,
            expiresAtSec = generated.expiresAtSec,
            secret = secret
        )
    } catch (t: Throwable) {
        Toast.makeText(this, "生成 token 失败: ${t.message}", Toast.LENGTH_LONG).show()
        null
    }
}
```

> 生产环境建议：  
> 将 `TokenGenerator` 放在你的业务服务器，客户端只请求业务服务器获取 Token。

### 3）调用 joinChannel

```kotlin
rtcEngine?.joinChannel(
    token = request.token,
    callId = request.callId,
    userId = request.userId,
    options = request.options,          // CallType 等
    tokenSecret = request.tokenSecret,  // 可为空
    tokenExpiresAtSec = request.tokenExpiresAtSec,
    tokenTtlSeconds = request.tokenTtlSeconds
)
```

成功后，会回调：

```kotlin
override fun onJoinChannelSuccess(channel: String, userId: String, code: Int) {
    // 已成功加入频道，可更新 UI 状态
}
```

## 2.5 结束通话

业务结束通话时调用：

```kotlin
private fun leaveChannel() {
    rtcEngine?.leaveChannel()
    resetUiAfterLeave() // 清 UI、清理 renderer 等
}
```

SDK 会通过：

```kotlin
override fun onLeaveChannel(durationSeconds: Int) {
    // 通话结束时长（秒）
}
```

通知已经离开频道。

---

# 3. 常用功能

以下示例同样来自 Demo，可直接复用。

## 3.1 开/关本地视频

```kotlin
private var isLocalVideoEnabled = true
private var isLocalPreviewEnabled = true

binding.btnToggleCamera.setOnClickListener {
    isLocalVideoEnabled = !isLocalVideoEnabled
    rtcEngine?.enableLocalVideo(isLocalVideoEnabled)
    isLocalPreviewEnabled = isLocalVideoEnabled
    updateControlButtons()
}
```

## 3.2 开/关本地音频采集

```kotlin
private var isLocalAudioEnabled = true

binding.btnToggleMic.setOnClickListener {
    isLocalAudioEnabled = !isLocalAudioEnabled
    rtcEngine?.enableLocalAudio(isLocalAudioEnabled)
    updateControlButtons()
}
```

## 3.3 切换前后摄像头

```kotlin
binding.btnSwitchCamera.setOnClickListener {
    isFrontCamera = !isFrontCamera
    fuFrameInterceptor?.setFrontCamera(isFrontCamera)
    rtcEngine?.switchCamera()
}
```

## 3.4 静音远端音视频

按用户静音远端音频 / 视频：

```kotlin
private fun muteRemoteUserAudio(targetUserId: String, muted: Boolean) {
    rtcEngine?.muteRemoteAudioStream(targetUserId, muted)
}

private fun muteRemoteUserVideo(targetUserId: String, muted: Boolean) {
    rtcEngine?.muteRemoteVideoStream(targetUserId, muted)
}
```

## 3.5 控制音频输出（扬声器 / 听筒）

```kotlin
private var isSpeakerOn = true

binding.btnToggleAudioRoute.setOnClickListener {
    isSpeakerOn = !isSpeakerOn
    rtcEngine?.setDefaultAudioRoutetoSpeakerphone(isSpeakerOn)
    updateControlButtons()
}
```

## 3.6 发送自定义消息

```kotlin
binding.btnSendMessage.setOnClickListener {
    val text = binding.etMessage.text?.toString()?.trim().orEmpty()
    if (text.isEmpty()) {
        Toast.makeText(this, "请输入消息内容", Toast.LENGTH_SHORT).show()
    } else if (currentCallId == null) {
        Toast.makeText(this, "请先加入频道", Toast.LENGTH_SHORT).show()
    } else {
        rtcEngine?.sendMessage(text) { error ->
            runOnUiThread {
                if (error != null) {
                    Toast.makeText(this, "发送失败: ${error.message}", Toast.LENGTH_SHORT).show()
                } else {
                    Toast.makeText(this, "已发送", Toast.LENGTH_SHORT).show()
                    binding.etMessage.text?.clear()
                    binding.tvMessageLog.text = "我: $text"
                }
            }
        }
    }
}
```

收到消息的回调见后文 `onMessageReceived`。

## 3.7 美颜开关

```kotlin
binding.btnToggleBeauty.setOnClickListener {
    beautyEnabled = !beautyEnabled
    fuFrameInterceptor?.setEnabled(beautyEnabled)
    updateControlButtons()
}
```

---

# 4. 视频帧处理（美颜等）

SellyRTC 提供视频采集前拦截接口，可以在推流前做美颜、滤镜等处理。

在创建引擎后设置：

```kotlin
rtcEngine?.setCaptureVideoFrameInterceptor { frame ->
    if (!beautyEnabled) return@setCaptureVideoFrameInterceptor frame
    fuFrameInterceptor?.process(frame) ?: frame
}
```

其中 `FuVideoFrameInterceptor` 内部使用 `FURenderer` 做实际美颜处理。

> 你也可以替换为自己的处理逻辑：
> - 对 `frame` 做 GPU 或 CPU 处理
> - 返回处理后的帧给 SDK 继续编码和发送

---

# 5. 事件回调 (InteractiveRtcEngineEventHandler)

实现 `InteractiveRtcEngineEventHandler`，监听通话过程中发生的事件：

```kotlin
private val rtcEventHandler = object : InteractiveRtcEngineEventHandler {

    override fun onJoinChannelSuccess(channel: String, userId: String, code: Int) { ... }

    override fun onLeaveChannel(durationSeconds: Int) { ... }

    override fun onUserJoined(userId: String, code: Int) { ... }

    override fun onUserLeave(userId: String, code: Int) { ... }

    override fun onConnectionStateChanged(
        state: InteractiveConnectionState,
        reason: Int,
        userId: String?
    ) { ... }

    override fun onError(code: String, message: String) { ... }

    override fun onLocalVideoStats(stats: InteractiveStreamStats) { ... }

    override fun onRemoteVideoStats(stats: InteractiveStreamStats) { ... }

    override fun onMessageReceived(message: String, userId: String?) { ... }

    override fun onTokenWillExpire(token: String?, expiresAt: Long) { ... }

    override fun onTokenExpired(token: String?, expiresAt: Long) { ... }

    override fun onDuration(durationSeconds: Long) { ... }

    override fun onRemoteVideoEnabled(enabled: Boolean, userId: String?) { ... }

    override fun onRemoteAudioEnabled(enabled: Boolean, userId: String?) { ... }

    override fun onStreamStateChanged(
        peerId: String,
        state: RemoteState,
        code: Int,
        message: String?
    ) { ... }
}
```

**常见事件说明：**

- `onConnectionStateChanged`：连接状态变化（Disconnected / Connecting / Connected / Reconnecting / Failed）
- `onUserJoined` / `onUserLeave`：远端用户加入/离开频道
- `onRemoteVideoEnabled` / `onRemoteAudioEnabled`：远端用户开关音视频
- `onMessageReceived`：收到自定义消息
- `onDuration`：通话时长更新（秒）
- `onError`：错误回调（建议弹窗 + 打日志）

---

# 6. 通话统计信息

## 6.1 单路流统计：InteractiveStreamStats

在本地/远端视频统计回调中获取：

```kotlin
override fun onLocalVideoStats(stats: InteractiveStreamStats) {
    // stats.width / height / fps / videoBitrateKbps / audioBitrateKbps / rttMs 等
}

override fun onRemoteVideoStats(stats: InteractiveStreamStats) {
    // 针对某个 userId 的码率、分辨率、丢包、RTT 等
}
```

你可以将这些信息显示在 UI 上，Demo 中的 `buildStatsLabel` 已经示范了如何构造：

```kotlin
private fun buildStatsLabel(header: String, stats: InteractiveStreamStats?): String {
    // Res: WxH, FPS, Codec, Video/Audio Kbps, RTT 等
}
```

## 6.2 通话结束时长：onLeaveChannel

在 `onLeaveChannel` 中可以拿到本次通话时长（秒），无论是主动离开还是断网/失败结束，只要曾加入成功都会回调：

```kotlin
override fun onLeaveChannel(durationSeconds: Int) {
    Log.d(TAG, "onLeaveChannel duration=${durationSeconds}s")
}
```

---

# 7. Token 过期机制

SDK 在 Token 生命周期内会通过事件提醒你续期：

## 7.1 Token 即将过期

```kotlin
override fun onTokenWillExpire(token: String?, expiresAt: Long) {
    Toast.makeText(
        this@InteractiveLiveActivity,
        "Token 即将过期，请及时续期",
        Toast.LENGTH_LONG
    ).show()
    // 1. 通知业务服务器刷新 Token
    // 2. 拿到新 Token 后调用 rtcEngine?.renewToken(newToken)（具体接口以实际 SDK 为准）
}
```

## 7.2 Token 已过期

```kotlin
override fun onTokenExpired(token: String?, expiresAt: Long) {
    Toast.makeText(
        this@InteractiveLiveActivity,
        "Token 已过期，断线后将无法重连",
        Toast.LENGTH_LONG
    ).show()
}
```

> 说明：
> - Token 过期后，**当前通话不会立刻中断**，但网络异常时自动重连会失败。
> - 请务必在 `onTokenWillExpire` 阶段就完成续期。

---

# 8. 常见问题 (FAQ)

## Q1：多人远端画面如何渲染？

为每一个远端用户（`userId`）分配一个 `SurfaceViewRenderer`，并调用：

```kotlin
val canvas = InteractiveVideoCanvas(renderer, userId)
rtcEngine?.setupRemoteVideo(canvas)
```

在布局层面，你可以将多个 `renderer` 放到不同的容器中（网格布局 / 自定义九宫格等），参考 Demo 中的 `remoteSlots`。

---

## Q2：远端画面不显示怎么办？

排查方向：

1. 是否收到了 `onUserJoined` 回调？
2. 有没有为该 `userId` 调用 `setupRemoteVideo` 并绑定到一个可见的 View？
3. View 是否被其他控件覆盖？
4. 远端用户是否已开启视频（可监听 `onRemoteVideoEnabled` 回调）？

---

## Q3：如何实现画中画 / 小窗布局？

这是布局层面的工作，与 SDK 解耦：

- 将远端大画面放在父容器（如 `FrameLayout`）中
- 再将本地小窗 View 作为子 View 添加在右下角，并设置合适的 `layoutParams`
- SDK 会把视频渲染到对应的 View 上，你只需要控制 View 的大小和位置即可

---

## Q4：如何在后台保持通话？

Demo 中使用了一个前台 Service：

```kotlin
InteractiveForegroundService.start(this)
// 离开频道后记得 stop
InteractiveForegroundService.stop(this)
```