声网 sdk 自定义视频滤镜开发接口说明

如果你正在阅读这篇文章，多半是因为你想在实时音视频场景中加入一些「不一样的东西」。也许是想要让用户的画面带点复古胶片感，也许是想要加一层可爱的动态贴纸，又或者你需要实现某种特定的美颜算法。声网 SDK 提供的自定义视频滤镜接口，正是为了满足这类需求而设计的。

在正式开始之前，我想先帮你建立一个整体认知。视频滤镜本质上是对每一帧图像进行处理，然后把处理后的结果渲染到屏幕上。声网的架构把这件事拆成了几个清晰的步骤：采集 → 处理 → 编码 → 传输 → 解码 → 渲染。自定义滤镜介入的正是「处理」这个环节，你可以在画面被编码之前拿到原始图像数据，做完你想做的任何操作，再把处理后的数据交还给管线。

这篇文章会从接口设计、核心流程、代码示例到常见问题，帮你一步步掌握这项能力的使用方法。

整体架构与工作原理

声网的视频滤镜系统采用了插拔式的设计思路，你可以把自定义滤镜理解成一段「插入」到视频管线中的处理逻辑。系统会在每一帧图像准备好之后、编码之前，调用你注册的滤镜函数，把数据和控制权交到你手里。

这里有几个关键概念需要先弄清楚：

• 视频帧（Video Frame）：这是滤镜处理的基本单位，包含图像数据、时间戳、图像尺寸等信息。
• 滤镜回调（Filter Callback）：声网会在特定时机触发你实现的回调函数，你在这个函数里拿到帧数据，做处理，然后返回。



• 数据格式：声网主要使用 I420 和 Texture 两种格式与滤镜交互，前者是原始的 YUV 数据，后者是 OpenGL 的纹理。

了解这些概念之后，你会发现整个流程其实相当直接。注册滤镜 → 系统按帧回调 → 你处理数据 → 返回结果。仅此而已。

核心接口说明

自定义滤镜的实现主要围绕以下几个接口展开。为了让你看得更清楚，我用表格把它们整理了出来：

接口名称	功能描述	调用时机
registerVideoFilter	注册自定义滤镜到 SDK	初始化阶段或滤镜切换时
unregisterVideoFilter	注销已注册的滤镜	退出滤镜功能时
onVideoFrame	接收原始视频帧数据	每一帧图像处理前
getVideoFormat	获取期望的输入数据格式	滤镜初始化时

其中 onVideoFrame 是最核心的回调函数。每次有新的视频帧需要处理时，声网都会把帧数据封装好传递给你。函数的原型大致是这样的：你会在参数里拿到一个 VideoFrame 对象，这个对象包含了像素数据的指针、图像宽高、旋转角度、时间戳等关键信息。你需要读取这个结构，处理好图像，然后把结果写回原结构或者通过输出参数传回去。

这里有个细节值得注意：声网支持两种滤镜处理模式。第一种是同步模式，你在回调函数里完成所有处理，直接把处理好的帧数据返回给 SDK。这种模式实现简单，但要注意处理时间不能太长，否则会阻塞整个视频管线，导致帧率下降。第二种是异步模式，你在回调里把帧数据拷贝一份，自己去异步处理，处理完再通过单独的接口把结果「送」回去。这种方式对主流程的影响更小，但实现起来稍微复杂一些，需要管理额外的内存和线程同步。

选择哪种模式，取决于你的滤镜有多「重」。如果是简单的颜色调整、亮度对比度调节之类的，同步模式完全够用。如果是复杂的美颜算法、深度学习推理之类的，那异步模式会是更稳妥的选择。

数据格式与像素处理

前面提到 I420 和 Texture 两种格式，这里展开说一下。I420 是最基础的 YUV planar 格式，数据分成 Y、U、V 三个平面存储。拿到这种格式的帧之后，你可以直接用指针访问像素数据，逐像素或者逐行进行处理。这种方式的好处是兼容性好，不需要依赖 OpenGL，缺点是处理速度相对慢一些，尤其是涉及大量像素遍历的算法。

Texture 格式则是通过 OpenGL 纹理传递数据。你会拿到一个纹理 ID，然后在你的 GL 上下文中绑定这个纹理，做各种 GPU 加速的处理。这种方式性能更好，适合实时性要求高的场景。代价是你需要自己处理 OpenGL 的上下文环境、Shader 编写、纹理绑定这些图形学相关的工作。

举个实际的例子。假设你要实现一个简单的「黑白滤镜」，把彩色画面转成灰度。用 I420 格式的话，你需要遍历 Y 平面（因为 Y 就是亮度分量），根据某种公式（常用的有平均值法、 luminosity 法等）计算每个像素的灰度值，然后写回 Y 平面。U 和 V 分量可以不用管，保持原样或者直接置零。用 Texture 格式的话，你只需要写一个简单的 Fragment Shader，读取纹理的 RGB 值，计算灰度，写到输出颜色就完成了。GPU 处理像素的并行度极高，速度会比 CPU 快很多。

开发流程指引

现在我们把前面零散的信息串起来，走一遍完整的开发流程。

第一步：创建滤镜类

你需要继承声网提供的基类（通常叫 AgoraVideoFilter 或者类似的命名），实现必要的虚函数。最重要的是 onVideoFrame 和 onInit/onRelease 这几个。onInit 里可以做初始化工作，比如创建 OpenGL 上下文、加载 Shader、分配临时缓冲区。onRelease 里做清理工作，释放资源。

第二步：注册滤镜

在初始化阶段调用 registerVideoFilter 接口，把你创建的滤镜实例注册进去。注册成功之后，SDK 就会在每一帧处理时触发你的回调。需要切换滤镜时，先 unregister 当前的，再 register 新的。

第三步：实现帧处理逻辑

在 onVideoFrame 回调里，拿到 VideoFrame 对象，判断数据格式，然后执行相应的处理逻辑。如果是 I420 格式，就用 CPU 遍历像素；如果是 Texture 格式，就执行 OpenGL Shader。处理完之后，把结果写回帧对象，返回 true 表示处理成功。如果返回 false，SDK 会跳过你的滤镜，直接使用原始帧。

第四步：测试与调优

这一步往往是花时间最多的。你需要在各种设备和网络条件下测试滤镜的表现。关注几个指标：滤镜处理耗时（应该控制在 16ms 以内才能保证 60fps）、内存占用（避免频繁分配释放导致的 GC 压力）、在不同分辨率下的表现（4K 和 360P 的处理策略可能需要区分）。

进阶技巧与注意事项

分享几个在实际开发中很有用的小技巧。

关于性能优化，最有效的办法是减少内存拷贝。每一帧数据在滤镜管线里传递时，尽量复用同一块缓冲区，而不是频繁地 new/delete 或者 malloc/free。在异步处理模式下尤其要注意这一点，因为异步本身就意味着数据的拷贝或者锁的使用。

关于多线程，如果你选择异步处理模式，务必注意线程安全。视频帧数据在回调线程里被拿走之后，主线程可能已经开始处理下一帧了。如果多个异步任务同时访问共享资源，没有适当的同步措施就会导致崩溃。最简单的办法是每个异步任务处理自己的帧数据副本，互不干扰。

关于兼容性问题，安卓设备的碎片化是个老难题。不同厂商的 OpenGL 实现在某些细节上可能有差异，比如纹理格式的支持、Shader 语法的细微不同等。如果你的滤镜使用了 OpenGL，建议在主流设备上做充分的回归测试。iOS 端相对统一，但 Metal 和 OpenGLES 的选择也需要根据你的目标机型做权衡。

还有一个点是动态调整。网络波动时，用户端的分辨率可能会动态变化。你的滤镜需要能够正确处理不同尺寸的输入帧，最好在 onVideoFrame 的开始处加上尺寸判断和适应的逻辑，避免因为尺寸不匹配导致的崩溃。

对了，如果你的滤镜涉及美颜或者任何「美化」功能，务必给用户一个开关。有些人喜欢实时看到美化后的自己，也有些人偏好真实。尊重用户的选择权，产品体验会更好。

常见问题与排查思路

开发过程中难免遇到各种问题。这里列几个高频出现的坑，以及对应的排查思路。

画面闪烁或者花屏。这种情况通常是滤镜处理后的像素数据格式或者尺寸和 SDK 期望的不一致。检查一下你写回的帧对象，确保宽高、 stride、像素格式都和输入时一致。如果用了异步模式，还要确认回调返回的帧确实是你处理完的那一帧，而不是别的什么数据。

帧率明显下降。先确认是不是滤镜处理本身太耗时，可以用计时工具测一下 onVideoFrame 的执行时间。如果是异步模式但帧率还是上不去，可能是任务队列积压了——处理速度跟不上采集速度，帧在队列里排队。这种情况要么优化处理算法，要么降低输入分辨率（比如先缩放到小尺寸处理完再放大回去）。

部分设备崩溃。这种往往是 OpenGL 相关的兼容性问题。检查是否在正确的线程创建和销毁 GL 上下文，是否处理了 GL 的错误状态，Shader 语法是否在目标设备上支持。如果确认是兼容性问题，可以考虑在不支持的设备上回退到 CPU 处理的降级方案。

写在最后

自定义视频滤镜是实时音视频场景里非常有趣的一个能力。它让产品有了更多的想象空间，也让开发者有机会展现创意。本文尽力覆盖了接口说明、开发流程和常见问题的方方面面，但技术的东西永远说不尽。最好的学习方式还是动手写代码，遇到问题解决问题。

声网作为全球领先的实时音视频云服务商，在这块沉淀了很久，接口设计经过了大量真实场景的验证。用好这些接口，配合你自己的算法创意，应该能做出不少有意思的东西来。

祝你开发顺利，玩得开心。