DEMO/SellyCloudSDK_Android_demo
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

添加游戏盾代理支持

Browse Source
This commit is contained in:
shou
2026-03-03 18:11:09 +08:00
parent ae4a045451
commit 8e9b816a4e
13 changed files with 517 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/SellySDK_直播推拉流接入文档_Android.md
View File

@@ -1,6 +1,6 @@
# Selly Live SDK 推拉流接入文档（Android）
> 统一 SDK 名称：**SellyCloudSDK**
> 统一 SDK 名称：**SellyCloudSDK**
> 本文档适用于 Android 客户端，面向对外集成方与内部使用。
---
@@ -19,6 +19,7 @@ Selly Live SDK 提供完整的音视频直播能力，支持 **推流（直播
- 支持视频帧处理（美颜 / 滤镜 / 水印）
- 基于 **Token 的安全鉴权机制**
- 支持 **RTMP H264 + AAC payload XOR 保护（可选）**
- 支持 **外部代理地址注入**（如洋葱盾等第三方安全代理）
---
@@ -34,8 +35,8 @@ Selly Live SDK 提供完整的音视频直播能力，支持 **推流（直播
### 3.1 项目结构参考
- `example/`：Android Demo 工程
- 推流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePushActivity.kt`
- `example/`：Android Demo 工程
- 推流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePushActivity.kt`
- 拉流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePlayActivity.kt`
- `example/libs/`：本地 AAR 依赖存放目录
@@ -60,9 +61,81 @@ dependencies {
---
## 4. Token 鉴权机制（重点）
## 4. SDK 初始化与代理配置
### 4.1 Token 注入方式
### 4.1 SDK 初始化
在使用任何推流 / 拉流功能前，必须先初始化 SDK：
```kotlin
SellyCloudManager.initialize(
context = applicationContext,
appId = "your-app-id",
config = SellyCloudConfig(
vhost = "your-vhost",
vhostKey = "your-vhost-key",
defaultStreamId = "default-stream",
defaultLiveMode = SellyLiveMode.RTMP
)
)
```
`initialize` 参数说明：
| 参数 | 类型 | 说明 |
| ---- | ---- | ---- |
| `context` | Context | 应用上下文 |
| `appId` | String | 应用 ID（权威值，会覆盖 config 中的 appId） |
| `config` | SellyCloudConfig? | 可选配置，不传则使用默认值 |
`SellyCloudConfig` 字段说明：
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| `vhost` | String | 虚拟主机 |
| `vhostKey` | String | vhost 密钥（用于鉴权签名） |
| `defaultStreamId` | String | 默认流 ID |
| `logEnabled` | Boolean | 是否启用日志，默认 true |
| `defaultLiveMode` | SellyLiveMode | 默认推拉流模式（RTMP / RTC） |
| `appName` | String | 应用名称，为空时自动使用 appId，一般无需设置 |
> `config.appId` 无需设置，SDK 内部会用 `initialize(appId=)` 参数覆盖。
### 4.2 代理地址配置（可选）
SDK 支持通过外部代理（如洋葱盾等安全加速服务）进行流媒体连接。代理地址由业务方在 SDK 外部获取，然后通过以下接口注入：
```kotlin
// 设置代理地址
SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")
// 清除代理（恢复直连）
SellyCloudManager.setProxyAddress(null)
// 查询当前代理地址
val proxy = SellyCloudManager.getProxyAddress() // null 表示未设置
```
**格式要求：**
- 必须以 `http://` 或 `https://` 开头
- 传 `null` 或空字符串表示清除代理
- 格式不合法时抛出 `IllegalArgumentException`
**生效范围：**
- 设置后对 RTMP 推拉流、RTC（WHEP/WHIP）播放推流、Signaling 信令连接均生效
- SDK 内部通过代理地址解析真实服务器 IP，对上层透明
**时机要求：**
- 必须在推流 / 拉流 **开始之前** 设置
- 推流 / 拉流过程中修改代理地址，需停止后重新开始才能生效
> Demo 中使用 `KiwiHelper` 封装了洋葱盾 SDK 的初始化与代理地址获取流程，通过 `SellyCloudManager.setProxyAddress()` 将结果传给 SDK。详见 `example/src/main/java/com/demo/SellyCloudSDK/KiwiHelper.kt`。
---
## 5. Token 鉴权机制（重点）
### 5.1 Token 注入方式
| 场景 | 设置位置 |
| ---- | ---- |
@@ -76,7 +149,7 @@ dependencies {
- SDK 内部在建立连接时自动携带当前 Token
- 直接使用 RTMP 地址推/拉流不需要 Token，可不设置
### 4.2 Token 设置时机（强约束）
### 5.2 Token 设置时机（强约束）
#### 推流
@@ -91,9 +164,9 @@ dependencies {
- `prepareToPlay()`
- `play()`
> ⚠️ 在连接建立后修改 Token，不会影响当前连接。
> 在连接建立后修改 Token，不会影响当前连接。
### 4.3 Token 刷新机制说明
### 5.3 Token 刷新机制说明
- SDK **不提供自动刷新**
- 业务层可在任意时刻 **重新设置 token 属性**
@@ -104,7 +177,7 @@ dependencies {
2. 调用 `pusher.token = newToken` / `player.token = newToken`
3. 停止并重新开始推流 / 拉流流程
### 4.4 RTMP Payload XOR 保护（可选）
### 5.4 RTMP Payload XOR 保护（可选）
用途：
@@ -131,9 +204,9 @@ Key 格式：
---
## 5. 推流接入详解
## 6. 推流接入详解
### 5.1 创建推流实例
### 6.1 创建推流实例
```kotlin
val pusher = SellyLiveVideoPusher.initWithLiveMode(
@@ -147,7 +220,7 @@ pusher.delegate = object : SellyLiveVideoPusherDelegate {
}
```
### 5.2 视频参数配置与预览
### 6.2 视频参数配置与预览
```kotlin
val config = SellyLiveVideoConfiguration.defaultConfiguration().apply {
@@ -166,7 +239,7 @@ pusher.startRunning(
)
```
### 5.3 设置推流 Token（使用 streamId 时）
### 6.3 设置推流 Token（使用 streamId 时）
```kotlin
pusher.token = pushToken
@@ -183,7 +256,7 @@ pusher.setXorKey(xorKeyHex)
> 若在推流中修改 key，需停止并重新开始推流后才会使用新 key。
### 5.4 开始/停止推流
### 6.4 开始/停止推流
```kotlin
pusher.startLiveWithStreamId(streamId)
@@ -212,7 +285,7 @@ pusher.stopLive { error ->
}
```
### 5.5 常用控制接口
### 6.5 常用控制接口
- `setMuted(true/false)`：静音
- `switchCameraPosition(...)`：切换摄像头
@@ -226,7 +299,7 @@ pusher.stopLive { error ->
- `setBeautyLevel(level)`：设置美颜强度
- `setBitmapAsVideoSource(...)` / `restoreCameraVideoSource()`：背景图推流
### 5.6 生命周期建议
### 6.6 生命周期建议
在宿主 Activity 中对齐生命周期：
@@ -234,7 +307,7 @@ pusher.stopLive { error ->
- `onPause()` → `pusher.onPause()`
- `onDestroy()` → `pusher.release()`
### 5.7 状态与统计回调
### 6.7 状态与统计回调
**状态枚举：**
@@ -252,7 +325,7 @@ pusher.stopLive { error ->
- rttMs
- cpu 使用率（Demo 通过 `CpuUsage` 读取）
### 5.8 推流 API 速览（含 Demo 未覆盖）
### 6.8 推流 API 速览（含 Demo 未覆盖）
初始化与预览：
@@ -293,9 +366,9 @@ pusher.stopLive { error ->
---
## 6. 拉流接入详解
## 7. 拉流接入详解
### 6.1 创建播放器
### 7.1 创建播放器
```kotlin
val player = SellyLiveVideoPlayer.initWithStreamId(
@@ -323,14 +396,14 @@ val player = SellyLiveVideoPlayer.initWithStreamId(
> 使用 RTMP 加密流时，请在创建播放器时传入 `xorKeyHex`；后续如需换 key，请重建播放器实例。
### 6.2 设置拉流 Token（使用 streamId 时）
### 7.2 设置拉流 Token（使用 streamId 时）
```kotlin
player.token = playToken
```
> 直接使用 RTMP 地址拉流不需要 Token，可不设置。
### 6.3 播放流程
### 7.3 播放流程
```kotlin
player.attachRenderView(renderContainer)
@@ -351,7 +424,7 @@ player.play()
- `setRenderView(view)`：手动指定渲染 View
- `seekBy(deltaMs)`：播放进度跳转（仅在流支持快进/回放时有效）
### 6.4 播放回调
### 7.4 播放回调
```kotlin
player.delegate = object : SellyLiveVideoPlayerDelegate {
@@ -374,7 +447,7 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {
- `Reconnecting`
- `Failed`
### 6.5 播放 API 速览（含 Demo 未覆盖）
### 7.5 播放 API 速览（含 Demo 未覆盖）
创建与渲染：
@@ -397,7 +470,7 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {
---
## 7. 错误处理与重试建议
## 8. 错误处理与重试建议
### Token 错误
@@ -414,24 +487,25 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {
---
## 8. 最佳实践
## 9. 最佳实践
- 推流前先完成采集预览
- Token 即将过期前提前刷新
- 使用统计回调做质量监控
- 拉流失败避免无限重试
- 使用代理时，确保在推拉流开始前代理地址已设置完毕
---
## 9. 常见问题（FAQ）
## 10. 常见问题（FAQ）
### Q1：Token 可以拼接到 URL 吗？
**A：** 不可以。
**A：** 不可以。
SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 `token` 属性完成。
### Q2：运行中修改 Token 是否生效？
**A：**
运行中修改 Token **不会影响当前已建立的连接**。
运行中修改 Token **不会影响当前已建立的连接**。
**下次重连或重新启动推流 / 拉流时会使用新的 Token**。
### Q3：播放器出现黑屏怎么办？
@@ -449,3 +523,15 @@ SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 `token` 属性完
- key 格式是否为合法 hex（偶数长度，支持 `0x` 前缀）
- 当前是否为 RTMP + H264 + AAC
- 变更 key 后是否已重启推流 / 重建播放器
### Q5：如何接入代理/加速服务（如洋葱盾）？
**A：**
SDK 本身不集成任何第三方代理 SDK。业务方需在 SDK 外部完成代理初始化与地址获取，然后通过 `SellyCloudManager.setProxyAddress(proxyUrl)` 注入。SDK 内部会自动通过代理地址解析真实服务器 IP。
示例流程：
1. 在 Application 或 Activity 中初始化代理 SDK
2. 获取本地代理地址（如 `http://127.0.0.1:12345`）
3. 调用 `SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")`
4. 正常进行推流 / 拉流
> Demo 中的 `KiwiHelper` 展示了洋葱盾的完整接入流程，可作为参考。