DEMO/SellyCloudSDK_Android_demo

Fork 0

Files

shou 8e9b816a4e 添加游戏盾代理支持

2026-03-03 18:11:09 +08:00

15 KiB

Raw Blame History

Selly Live SDK 推拉流接入文档（Android）

统一 SDK 名称：SellyCloudSDK 本文档适用于 Android 客户端，面向对外集成方与内部使用。

1. 概述

Selly Live SDK 提供完整的音视频直播能力，支持 推流（直播发布） 与 拉流（直播播放） 两大核心场景，适用于泛直播、互动直播、实时音视频等业务。

主要能力

支持 RTMP / RTC 推流与播放模式
高性能音视频采集与编码
灵活的视频参数配置（分辨率 / 帧率 / 码率）
推流状态与统计回调
拉流播放状态与错误回调
支持视频帧处理（美颜 / 滤镜 / 水印）
基于 Token 的安全鉴权机制
支持 RTMP H264 + AAC payload XOR 保护（可选）
支持 外部代理地址注入（如洋葱盾等第三方安全代理）

2. 系统要求

Android 8.0+（Demo minSdk 为 26）
需真机运行（音视频采集限制）
需要摄像头 / 麦克风权限

3. SDK 集成

3.1 项目结构参考

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 依赖存放目录

3.2 Gradle 依赖方式（仅 AAR）

dependencies {
    implementation files("libs/sellycloudsdk-1.0.0.aar")
}

若接入美颜等能力，请按业务侧 SDK 要求额外引入第三方美颜库（Demo 使用 FaceUnity AAR）。

3.3 权限配置（AndroidManifest.xml）

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

如需截图保存且兼容 Android 9 及以下，可额外申请 WRITE_EXTERNAL_STORAGE。

4. SDK 初始化与代理配置

4.1 SDK 初始化

在使用任何推流 / 拉流功能前，必须先初始化 SDK：

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 外部获取，然后通过以下接口注入：

// 设置代理地址
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 注入方式

场景	设置位置
推流	`SellyLiveVideoPusher.token`
拉流	`SellyLiveVideoPlayer.token`

说明：

Token 不拼接到 URL
Token 不绑定 streamId
SDK 内部在建立连接时自动携带当前 Token
直接使用 RTMP 地址推/拉流不需要 Token，可不设置

5.2 Token 设置时机（强约束）

推流

必须在以下接口调用之前设置：

startLiveWithStreamId(...)

拉流

必须在以下接口调用之前设置：

prepareToPlay()
play()

在连接建立后修改 Token，不会影响当前连接。

5.3 Token 刷新机制说明

SDK 不提供自动刷新
业务层可在任意时刻 重新设置 token 属性

推荐流程：

业务侧向服务端获取新 Token
调用 pusher.token = newToken / player.token = newToken
停止并重新开始推流 / 拉流流程

5.4 RTMP Payload XOR 保护（可选）

用途：

防止他人拿到 RTMP 地址后直接播放、转码或截图

生效范围与约束：

仅对 RTMP 生效
仅支持 H264 + AAC（当前版本）
只处理 payload，配置帧（SPS/PPS、AAC Sequence Header）保持不变
推流端与播放端必须使用同一个 key

Key 格式：

hex 字符串，建议 16 或 32 字节（即 32/64 个 hex 字符）
支持 0x 前缀
长度必须为偶数
非法 key 会被忽略并关闭 XOR（会输出 warning 日志）

时机要求：

推流：请在 startLiveWithStreamId(...) / startLiveWithUrl(...) 之前设置 key
拉流：请在 initWithStreamId(...) / initWithUrl(...) 创建播放器时传入 xorKeyHex

6. 推流接入详解

6.1 创建推流实例

val pusher = SellyLiveVideoPusher.initWithLiveMode(
    context = this,
    liveMode = SellyLiveMode.RTMP
)
pusher.delegate = object : SellyLiveVideoPusherDelegate {
    override fun liveStatusDidChanged(status: SellyLiveStatus) {}
    override fun onStatisticsUpdate(stats: SellyLivePusherStats) {}
    override fun onError(error: SellyLiveError) {}
}

6.2 视频参数配置与预览

val config = SellyLiveVideoConfiguration.defaultConfiguration().apply {
    videoSize = SellyLiveVideoResolution.RES_1280x720
    videoFrameRate = 25
    videoBitRate = 1000 * 1000
    videoMinBitRate = 500 * 1000
    outputImageOrientation = SellyLiveOrientation.PORTRAIT
}

pusher.attachPreview(previewContainer)
pusher.startRunning(
    cameraPosition = SellyLiveCameraPosition.FRONT,
    videoConfig = config,
    audioConfig = null
)

6.3 设置推流 Token（使用 streamId 时）

pusher.token = pushToken

RTMP Payload XOR（可选）

val xorKeyHex = "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"

// 建议在 startLiveWith... 之前设置
pusher.setXorKey(xorKeyHex)

若在推流中修改 key，需停止并重新开始推流后才会使用新 key。

6.4 开始/停止推流

pusher.startLiveWithStreamId(streamId)

pusher.stopLive()

直接使用 RTMP 地址推流（Demo 未覆盖）

val rtmpUrl = "rtmp://your.host/live/streamKey"
pusher.startLiveWithUrl(rtmpUrl)

直接使用 RTMP 地址推流不需要 Token，可不设置。

停止推流（带回调）

pusher.stopLive { error ->
    if (error != null) {
        // 处理停止失败
    }
}

6.5 常用控制接口

setMuted(true/false)：静音
switchCameraPosition(...)：切换摄像头
switchCamera()：前后摄像头切换（自动切换）
startCamera() / stopCamera()：控制摄像头
startMicrophone() / stopMicrophone()：控制麦克风
setCameraEnabled(true/false)：关闭/开启摄像头
setStreamOrientation(...)：切换推流方向
setVideoConfiguration(...) + changeResolution(...)：动态调整分辨率
setBeautyEngine(...) + setBeautyEnabled(...)：接入美颜
setBeautyLevel(level)：设置美颜强度
setBitmapAsVideoSource(...) / restoreCameraVideoSource()：背景图推流

6.6 生命周期建议

在宿主 Activity 中对齐生命周期：

onResume() → pusher.onResume()
onPause() → pusher.onPause()
onDestroy() → pusher.release()

6.7 状态与统计回调

状态枚举：

Idle
Connecting
Publishing
Reconnecting
Stopped
Failed

统计字段：

fps
videoBitrateKbps / audioBitrateKbps
rttMs
cpu 使用率（Demo 通过 CpuUsage 读取）

6.8 推流 API 速览（含 Demo 未覆盖）

初始化与预览：

initWithLiveMode(context, liveMode)：创建推流实例
setPreviewView(view)：设置预览 View
attachPreview(container)：将预览 View 添加到容器
getPreviewView()：获取当前预览 View

采集与推流：

startRunning(cameraPosition, videoConfig, audioConfig)：开始采集预览
setVideoConfiguration(config)：更新视频参数
setXorKey(hexKey)：设置 RTMP payload XOR key（可选）
startLiveWithStreamId(streamId)：使用 streamId 推流
startLiveWithUrl(url)：使用完整 URL 推流
stopLive() / stopLive(callback)：停止推流

设备与音视频控制：

switchCameraPosition(position) / switchCamera()：切换摄像头
startCamera() / stopCamera()：启动 / 停止摄像头
startMicrophone() / stopMicrophone()：启动 / 停止麦克风
setMuted(true/false)：静音推流音频
setCameraEnabled(true/false)：开启 / 关闭摄像头

美颜与画面：

setBeautyEngine(engine)：设置美颜引擎
setBeautyEnabled(true/false)：启用 / 关闭美颜
setBeautyLevel(level)：设置美颜强度
setStreamOrientation(orientation)：设置推流方向
changeResolution(width, height)：动态调整分辨率
setBitmapAsVideoSource(bitmap) / restoreCameraVideoSource()：背景图推流

生命周期：

onPause() / onResume() / release()：与 Activity 生命周期对齐

7. 拉流接入详解

7.1 创建播放器

val player = SellyLiveVideoPlayer.initWithStreamId(
    context = this,
    streamId = streamId,
    liveMode = SellyLiveMode.RTC,
    xorKeyHex = "" // RTC 场景可留空
)
// 或直接使用完整 URL
// val player = SellyLiveVideoPlayer.initWithUrl(this, playUrl, xorKeyHex = "A1B2...")

若需要指定 vhost / appName：

val player = SellyLiveVideoPlayer.initWithStreamId(
    context = this,
    streamId = streamId,
    liveMode = SellyLiveMode.RTMP,
    vhost = "your-vhost",
    appName = "live",
    xorKeyHex = "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
)

使用 RTMP 加密流时，请在创建播放器时传入 xorKeyHex；后续如需换 key，请重建播放器实例。

7.2 设置拉流 Token（使用 streamId 时）

player.token = playToken

直接使用 RTMP 地址拉流不需要 Token，可不设置。

7.3 播放流程

player.attachRenderView(renderContainer)
player.prepareToPlay()
player.play()

控制接口：

pause()
stop()
play()
setMuted(true/false)
release()

补充接口（Demo 未覆盖）：

setRenderView(view)：手动指定渲染 View
seekBy(deltaMs)：播放进度跳转（仅在流支持快进/回放时有效）

7.4 播放回调

player.delegate = object : SellyLiveVideoPlayerDelegate {
    override fun playbackStateChanged(state: SellyPlayerState) {}
    override fun onFirstVideoFrameRendered() {}
    override fun onFirstAudioFrameRendered() {}
    override fun onLatencyChasingUpdate(update: SellyLatencyChasingUpdate) {}
    override fun onLatencyChasingReloadRequired(latencyMs: Long) {}
    override fun onError(error: SellyLiveError) {}
}

状态枚举：

Idle
Connecting
Playing
Paused
Stopped
Reconnecting
Failed

7.5 播放 API 速览（含 Demo 未覆盖）

创建与渲染：

initWithStreamId(context, streamId, liveMode, vhost, appName, xorKeyHex)：使用 streamId 创建播放器
initWithUrl(context, url, xorKeyHex)：使用完整 URL 创建播放器
attachRenderView(container) / setRenderView(view)：设置渲染 View
getRenderView()：获取当前渲染 View

播放控制：

prepareToPlay() / play() / pause() / stop()：播放流程控制
seekBy(deltaMs)：播放进度跳转（流支持回放时有效）
isPlaying()：查询播放状态
setMuted(true/false)：静音播放

统计与释放：

setStatsListener { snapshot -> }：播放统计回调
release()：释放播放器资源

8. 错误处理与重试建议

Token 错误

停止当前推 / 拉
获取新 Token
重新设置 Token
重新开始推流 / 拉流流程

网络错误

监听 onStatisticsUpdate 或播放器状态
弱网时适当降低分辨率 / 码率
必要时重启连接

9. 最佳实践

推流前先完成采集预览
Token 即将过期前提前刷新
使用统计回调做质量监控
拉流失败避免无限重试
使用代理时，确保在推拉流开始前代理地址已设置完毕

10. 常见问题（FAQ）

Q1：Token 可以拼接到 URL 吗？

A：不可以。 SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 token 属性完成。

Q2：运行中修改 Token 是否生效？

A：运行中修改 Token 不会影响当前已建立的连接。 下次重连或重新启动推流 / 拉流时会使用新的 Token。

Q3：播放器出现黑屏怎么办？

A：可按以下步骤排查：

检查播放地址是否正确
确认当前网络连接正常
查看播放器回调中的错误信息
确认视频流格式是否被 SDK 支持

Q4：加密流播放花屏/噪音怎么办？

A：重点检查以下项：

推流端与播放端 xorKeyHex 是否完全一致
key 格式是否为合法 hex（偶数长度，支持 0x 前缀）
当前是否为 RTMP + H264 + AAC
变更 key 后是否已重启推流 / 重建播放器

Q5：如何接入代理/加速服务（如洋葱盾）？

A： SDK 本身不集成任何第三方代理 SDK。业务方需在 SDK 外部完成代理初始化与地址获取，然后通过 SellyCloudManager.setProxyAddress(proxyUrl) 注入。SDK 内部会自动通过代理地址解析真实服务器 IP。

示例流程：

在 Application 或 Activity 中初始化代理 SDK
获取本地代理地址（如 http://127.0.0.1:12345）
调用 SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")
正常进行推流 / 拉流

Demo 中的 KiwiHelper 展示了洋葱盾的完整接入流程，可作为参考。

15 KiB Raw Blame History Unescape Escape