sdk更新，文档更新，统一渲染后端配置，优化美颜帧处理逻辑，补充推流状态能力Auto-Framing，webrtc支持xor加解密

2026-03-30 15:18:11 +08:00
parent 84050ab7ff
commit ae8a341fb4
35 changed files with 2289 additions and 1140 deletions
--- a/docs/SellySDK_音视频通话接入文档_Android.md
+++ b/docs/SellySDK_音视频通话接入文档_Android.md
@@ -4,6 +4,12 @@

 SDK 核心以 `InteractiveRtcEngine` 为中心，通过 `InteractiveRtcEngineEventHandler` 回调通话状态、用户事件、音视频状态及异常。

+当前版本的互动渲染模型已经从“仅 `SurfaceViewRenderer`”扩展为“`RtcRenderTarget` 抽象 + 多种后端实现”：
+
+- `SurfaceViewRenderer` 旧路径仍可用
+- `TextureView` 已可用于本地/远端视频渲染
+- 推荐在 **加入频道前** 选定本地渲染后端
+
 ---

 ## 目录
@@ -105,16 +111,60 @@ val rtcEngine = InteractiveRtcEngine.create(

 ### 4. 设置本地/远端画布

+推荐使用 `InteractiveVideoCanvas(renderTarget, userId)` 新接口。
+
+#### 4.1 SurfaceViewRenderer 旧路径
+
 ```kotlin
 val localRenderer = SurfaceViewRenderer(this)
-rtcEngine.setupLocalVideo(InteractiveVideoCanvas(localRenderer, userId))
+val localCanvas = InteractiveVideoCanvas(
+    com.sellycloud.sellycloudsdk.render.SurfaceViewRtcTarget(localRenderer),
+    userId
+)
+rtcEngine.setupLocalVideo(localCanvas)
 ```

 ```kotlin
 val remoteRenderer = SurfaceViewRenderer(this)
-rtcEngine.setupRemoteVideo(InteractiveVideoCanvas(remoteRenderer, remoteUserId))
+val remoteCanvas = InteractiveVideoCanvas(
+    com.sellycloud.sellycloudsdk.render.SurfaceViewRtcTarget(remoteRenderer),
+    remoteUserId
+)
+rtcEngine.setupRemoteVideo(remoteCanvas)
 ```

+#### 4.2 TextureView 路径
+
+```kotlin
+val localTextureView = com.sellycloud.sellycloudsdk.widget.AspectRatioTextureView(this)
+val localCanvas = InteractiveVideoCanvas(
+    com.sellycloud.sellycloudsdk.render.TextureViewRtcTarget(localTextureView),
+    userId
+)
+rtcEngine.setupLocalVideo(localCanvas)
+```
+
+```kotlin
+val remoteTextureView = com.sellycloud.sellycloudsdk.widget.AspectRatioTextureView(this)
+val remoteCanvas = InteractiveVideoCanvas(
+    com.sellycloud.sellycloudsdk.render.TextureViewRtcTarget(remoteTextureView),
+    remoteUserId
+)
+rtcEngine.setupRemoteVideo(remoteCanvas)
+```
+
+兼容说明：
+
+- `InteractiveVideoCanvas(view: SurfaceViewRenderer, userId)` 旧构造仍可用（deprecated）
+- 推荐新接入统一走 `RtcRenderTarget`
+- 当前高层互动 API 还没有直接暴露 `SurfaceTexture` 入口；Android 场景推荐 `SurfaceViewRenderer` 或 `TextureView`
+
+所有权说明：
+
+- 调用方自己创建的 `SurfaceViewRenderer` / `TextureView`，由调用方负责释放
+- SDK 只在 `setupLocalVideo` / `setupRemoteVideo` 中绑定 target，在 `leaveChannel` 时解绑
+- 调用方应在 `leaveChannel` 之后、Activity 销毁前释放自己创建的 View
+
 ### 5. 加入通话

 ```kotlin
@@ -174,9 +224,9 @@ val options = InteractiveChannelMediaOptions(
 3. 创建 `InteractiveRtcEngine`
 4. 设置 `EventHandler`
 5. 配置 `InteractiveVideoEncoderConfig`
-6. 设置本地画布 `setupLocalVideo`
+6. 设置本地画布 `setupLocalVideo`（建议在 `joinChannel` 前完成，并在此阶段确定 backend）
 7. `joinChannel` 加入频道
-8. `onUserJoined` 后设置远端画布
+8. `onUserJoined` 后设置远端画布；也可以提前为某个 `userId` 调用 `setupRemoteVideo`，SDK 会在用户真正上线后自动 attach
 9. 通话中进行音视频控制
 10. `leaveChannel` 并释放资源

@@ -268,21 +318,45 @@ val isSharing = rtcEngine.isScreenSharing()
 ## 视频帧前后处理

 ```kotlin
-rtcEngine.setCaptureVideoFrameInterceptor { frame ->
-    // 在此处理美颜/滤镜，返回新的 frame
-    frame
-}
+rtcEngine.setCaptureVideoProcessor(object : VideoProcessor {
+    override val config = VideoProcessorConfig(
+        preferredFormat = VideoProcessFormat.TEXTURE_2D,
+        mode = VideoProcessMode.READ_WRITE,
+        fullRewrite = true
+    )
+
+    override fun processTexture(input: VideoTextureFrame, outputTextureId: Int) {
+        // 推荐在 GPU texture 上处理采集前帧，美颜/滤镜直接写入 outputTextureId
+    }
+})
 ```

 ```kotlin
-rtcEngine.setRenderVideoFrameInterceptor { frame, userId ->
-    // 远端渲染前处理，返回 true 表示继续渲染
-    true
-}
+val renderObserver = rtcEngine.addRenderVideoFrameObserver(object : VideoFrameObserver {
+    override val config = VideoFrameObserverConfig(
+        preferredFormat = VideoProcessFormat.TEXTURE_2D,
+        stage = VideoStage.RENDER_PRE_DISPLAY
+    )
+
+    override fun onTextureFrame(frame: VideoTextureFrame) {
+        // 远端渲染前只读观测
+        val userId = frame.sourceId
+    }
+})
 ```

-> Demo 中的美颜示例见：
-> `example/src/main/java/com/demo/SellyCloudSDK/beauty/FuVideoFrameInterceptor.kt`
+> 推荐优先使用 `TEXTURE_2D`：
+> - `TEXTURE_2D` 适合美颜、滤镜、AR、水印等 GPU 处理链路。
+> - `I420` / `RGBA` 仅在算法必须访问 CPU 像素时再使用。
+> - 对 RTC / WHIP 的 texture-backed 帧，走 CPU observer / processor 会触发额外的 texture-to-CPU 转换。
+> - `VideoFrameObserverConfig` 默认仍为 `I420` 以兼容旧接入；新 RTC / WHIP 接入建议显式写 `preferredFormat = TEXTURE_2D`。
+> - 完整重写输出的处理器建议设置 `fullRewrite = true`；水印/叠加类处理保留默认值即可。
+>
+> Demo 中的采集前美颜示例见：
+> `example/src/main/java/com/demo/SellyCloudSDK/beauty/FaceUnityBeautyEngine.kt`
+>
+> 当前 Demo 的互动页接入见：
+> `example/src/main/java/com/demo/SellyCloudSDK/interactive/InteractiveLiveActivity.kt`

 ---

@@ -421,6 +495,7 @@ SDK 初始化与代理：
 本地与远端控制：

 - `setupLocalVideo(canvas)` / `setupRemoteVideo(canvas)`：设置画布
+- `InteractiveVideoCanvas(renderTarget, userId, renderMode)`：推荐画布模型
 - `clearRemoteVideo(userId)`：清理远端画面
 - `enableLocalVideo(true/false)` / `enableLocalAudio(true/false)`：开关本地音视频
 - `muteRemoteAudioStream(userId, true/false)` / `muteRemoteVideoStream(userId, true/false)`：按用户静音
@@ -429,8 +504,9 @@ SDK 初始化与代理：

 帧处理与屏幕共享：

- `setCaptureVideoFrameInterceptor(...)`：采集前帧处理
- `setRenderVideoFrameInterceptor(...)`：渲染前帧处理
+- `setCaptureVideoProcessor(...)`：采集前可写处理
+- `addCaptureVideoFrameObserver(...)`：采集前只读观测
+- `addRenderVideoFrameObserver(...)`：远端渲染前只读观测
 - `startScreenShare(...)` / `stopScreenShare()` / `isScreenSharing()`：屏幕共享

 消息与 Token：
@@ -447,6 +523,20 @@ SDK 初始化与代理：
 2. 是否在 `onUserJoined` 后调用 `setupRemoteVideo`
 3. 远端是否关闭了视频

+### Q：互动直播可以用 `TextureView` 吗？
+可以。
+
+推荐用法是：
+
+- 本地：`InteractiveVideoCanvas(TextureViewRtcTarget(textureView), userId)`
+- 远端：`InteractiveVideoCanvas(TextureViewRtcTarget(textureView), remoteUserId)`
+
+注意：
+
+- 建议在 `joinChannel` 前确定本地 backend
+- 当前 Demo 在首页设置中统一选择本地 backend，进入互动页面后不再暴露切换入口
+- 高层互动 API 当前未直接暴露 `SurfaceTexture` 入口
+
 ### Q：加入频道失败？
 1. 检查 `signaling_app_id` 是否正确
 2. Token 是否为空或已过期
@@ -457,5 +547,11 @@ SDK 初始化与代理：
 1. 是否已获取 `MediaProjection` 授权
 2. Android 14+ 是否启动前台服务

+### Q：互动通话支持 XOR 吗？
+当前高层互动 API 还没有暴露 `xorKeyHex` 一类的配置入口。
+
+- 目前已支持 XOR 的 WebRTC 路径，是直播 RTC 的 `WHIP / WHEP` 推拉流
+- 互动通话如需接入 XOR，需要后续在互动链路单独暴露配置并挂载 FrameCrypto
+
 ### Q：如何接入代理/加速服务？
 SDK 本身不集成任何第三方代理 SDK。业务方需在外部完成代理初始化，获取本地代理地址后，通过 `SellyCloudManager.setProxyAddress()` 注入。详见「代理地址配置」章节。