1. 认识阿里云音视频终端SDK

阿里云音视频终端SDK，官方命名为MediaBox音视频SDK，本质上是一套面向开发者的端到端音视频解决方案。它把直播推流、视频播放、短视频创作、美颜特效、音频特效这些核心能力打包在一起，支持移动端、桌面端和Web端接入。开发者可以根据实际业务需求灵活选择集成方式——既可以选择一体化SDK一次性接入多个功能模块，也可以按需组合独立的SDK，真正做到“搭积木”式开发。

MediaBox音视频SDK底层依托于阿里云的视频直播、视频点播、智能媒体服务等云产品，覆盖了从拍摄、编辑、上传、推流到播放的完整业务链路。配套的产品级Demo和开源UI组件，帮助开发者以低代码的方式快速搭建应用。经过数亿级请求量的实际考验，其功能稳定性和服务质量都经过了充分验证。

2. SDK选型：一体化与模块化

在正式对接之前，首先需要根据业务场景选择合适的SDK形态。MediaBox音视频SDK提供两种主要的集成方案：

一体化SDK方案：融合了直播和点播的核心能力，通过复用底层组件来减小SDK包体积。一次集成即可获得直播、点播、短视频等多种功能，适合综合性较强的应用。

模块化SDK方案：按照业务需要自由组合功能模块，按需打包，贴合实际场景。MediaBox音视频SDK目前提供四个场景的一体化SDK：基础直播、互动直播、短视频场景、标准一体化。每个场景SDK内部已经包含了相应场景所需的播放器、推流、ARTC等子SDK能力。

如果业务场景只需要实时音视频通话能力，单独集成ARTC SDK即可。如果需要同时使用直播与点播能力，推荐使用音视频终端组合SDK，比如AliVCSDK_Standard或AliVCSDK_InteractiveLive。

3. License申请与鉴权流程

音视频终端SDK通过License机制进行授权管理，License与应用标识一一绑定。获取SDK License后，需要在对应的直播推流SDK、短视频SDK、播放器SDK、美颜特效SDK中接入License以完成授权流程。

3.1 创建应用

进入点播控制台的“我的授权”页面，选择应用管理标签页，点击创建应用。编辑应用信息时，需要根据端类型区分填写：

Web端：依次填入应用名称和对应的Web域名。标准填写示例为“aliyun.com”。需要同时覆盖多个子域名（如pc.aliyun.com和mobile.aliyun.com）时，只需填写主域名即可。需要注意，不能包含协议头（https://或https://）、不能包含路径或子页面、不能使用泛域名。

移动端：选择平台后，填入应用名称，并填入对应的安卓包名、iOS BundleID及HarmonyOS BundleID。

对于Android应用，如果勾选了绑定签名，则需要填入Android应用签名的MD5值。绑定签名后可以提高安全性，避免License被同Package Name的应用盗用。新版本SDK（MediaBox音视频SDK v1.7.0及以上版本）支持免绑定签名。获取Android应用签名MD5值，可以通过命令`keytool -v -list -keystore your.keystore`查看，或通过AndroidStudio的Gradle > Tasks > android > signingReport获取。

3.2 购买与绑定License

返回“我的授权”页面，选择订单实例标签页，点击License购买。进入音视频终端SDK购买页，根据业务需求选择SDK和对应的功能模块。购买播放器SDK License时，需确保所选平台与应用的端类型匹配。支付成功后，订单实例标签页即可看到新购买的订单实例。

短视频SDK从3.29.0版本开始，接入一体化License服务（即音视频终端SDK License），该License包含直播推流、短视频、播放器、美颜特性等SDK的授权。每一个License最多可以绑定一款Android应用和一款iOS应用。

3.3 License鉴权配置

音视频终端SDK的License鉴权流程依赖LicenseKey与License文件，配置要求如下：

• LicenseKey（必填）：用于请求更新License文件。SDK初始化时会检查更新认证文件，在程序运行时也会每隔15分钟检查更新。
• License文件（建议配置）：用于当未能从服务端成功请求到认证时的鉴权备用文件，例如由于网络问题导致无法下载认证等极端情况。认证文件内容包含开通的权限以及有效期。Native端播放器SDK 7.6.0版本之后必须配置License文件。Web端不需要配置License文件。

在续约场景下，认证会联网自动更新，但由于涉及检查有效期，建议更新本地License文件。如果不希望内置License文件，可以不填写LicenseFile相关配置，但鉴权依据将全部来源于服务端，可能因网络不稳定而导致鉴权不稳定。

4. Android平台集成指南

4.1 环境要求

Android平台集成需要Android Studio插件版本4.1.3及以上、Gradle 7.0.2及以上、Android Studio自带JDK11。

4.2 添加Ma ven仓库

在项目级build.gradle文件中添加阿里云Ma ven仓库：

4.3 引入SDK依赖

在app模块的build.gradle文件中引入对应的SDK依赖。以ARTC SDK为例：

其中x.x.x需要替换为工程适配的版本号。ARTC SDK最新版本为7.10.0，AICallKit SDK最新版本为2.11.0。

4.4 申请应用权限

在AndroidManifest.xml中声明摄像头和麦克风权限，并在运行时动态申请：

权限申请示例代码：

4.5 创建与初始化引擎

创建并初始化ARTCAICallEngine引擎：

如果使用数字人类型，需要配置数字人显示的视图容器：

如果使用视觉理解类型，需要配置本地视频预览显示的视图容器：

5. iOS平台集成指南

5.1 环境要求

iOS平台集成需要Xcode 16.0及以上版本（推荐使用最新正式版本），CocoaPods 1.9.3及以上版本。

5.2 创建Podfile

在项目目录下执行命令`pod init`创建Podfile文件。

5.3 添加SDK依赖

修改Podfile文件，添加SDK依赖。以互动直播场景为例：

执行命令`pod install`安装SDK。

5.4 初始化SDK

iOS端的初始化流程与Android类似，需要先申请摄像头和麦克风权限，然后创建并初始化引擎实例。

6. Web平台集成指南

6.1 环境要求

集成Web端SDK必须使用HTTPS协议。浏览器版本要求：Mac和Windows平台Chrome不低于67。建议将SDK升级至最新版本。

6.2 安装SDK

通过npm安装ARTC Web SDK：

6.3 初始化SDK

Web端初始化示例：

6.4 RTS拉流

对于RTS超低延时直播场景，可以通过以下方式接入：

7. 核心功能模块详解

7.1 直播推流

直播推流SDK提供将采集的音视频流推送到阿里云直播服务的能力。推流SDK支持多路视频采集和本地混流，默认只支持一路视频流，开启本地混流后可以采集多路视频流和一路音频流，并按需调整这些视频流的位置和大小。

获取视频效果管理器的示例代码如下：

推流URL中需要填入有效的推流RTMP地址。推流成功后，可以使用阿里云播放器SDK、FFplay、VLC等工具查看播放效果。

需要注意一点：推流SDK暂不支持与播放器SDK同时集成。如果需要同时使用推流和播放能力，应选择音视频终端一体化SDK。

7.2 视频播放

播放器SDK是MediaBox音视频SDK的子产品之一，提供直播和点播场景中的视频播放功能，支持Web、Android、iOS、Flutter、HarmonyOS、Windows、macOS等多种平台。

Web播放器SDK初始化示例：

播放器SDK支持多种播放控制功能，包括自动播放、自定义播放器外观和控件、视频截图等，同时支持H.265/H.266编码协议视频流的播放。

7.3 短视频创作

短视频SDK提供视频录制、编辑、上传等核心能力。从3.29.0版本开始，短视频SDK接入一体化License服务。短视频场景SDK适用于娱乐、社交、教育、新闻资讯、电商等对短视频拍摄制作和多创意玩法有需求的场景。

7.4 美颜特效

美颜特效SDK基于智能视觉算法和海量规模的人脸、人体检测与识别技术，为视频创作者提供人脸美颜、美型、美妆美化、滤镜贴纸等编辑加工能力。

从v6.7.0版本起，音视频终端SDK对全功能美颜特效场景进行了分离，只保留基础美颜功能（美白、磨皮、锐化、红润、滤镜）。全功能美颜特效需要通过独立的美颜特效SDK接入。集成Queen智能美化特效功能需要申请开通License。

7.5 实时音视频（ARTC）

ARTC SDK提供实时音视频通信能力，支持按需发布和订阅音视频流。用户可以通过API与RTC服务端交互，在加入频道或房间后，进行本地推流、订阅远端用户等操作，实现频道内不同用户之间的实时音视频通话。

8. 进阶功能

8.1 自定义视频采集

ARTC SDK提供灵活的自定义视频采集功能，支持开发者根据业务需求自主管理视频采集设备。当对视频质量、设备兼容性或采集流程有特殊要求，无法使用SDK内部采集时，自定义视频采集提供了更强的扩展性和定制能力。

关闭SDK内部采集的示例代码如下：

设置自定义采集视频源的示例：

8.2 自定义输入（Web）

阿里云ARTC Web SDK除了支持从摄像头、麦克风、屏幕共享获取输入源外，还支持自定义输入，例如从视频文件中获取视频流和音频流，或者从canvas中获取画布的图像传输给远端用户。

9. 常见错误码与问题排查

在集成和使用音视频终端SDK的过程中，难免会遇到各种错误。以下是常见错误码及排查思路：

• JoinBadAppId（33620481）：AppId不存在。请在控制台创建应用。
• already joined（16843521）：用户已经加入房间。请检查接口调用逻辑。
• join timeout（16908804）：加入频道超时。请检查网络连接是否正常。
• sdk init error：初始化SDK异常。检查SDK版本是否正确、JAR包是否缺失。
• audio device not found（10001）：没有找到音频设备。
• video device not found（10002）：没有找到视频设备。

对于推流SDK的异常，可以参考官方的自助排查思路和操作步骤定位问题。如果遇到API相关问题，应查阅相应的API文档。对于无法解决的问题，可以提交工单联系技术支持。

10. 最佳实践建议

基于阿里云音视频终端SDK的对接经验，这里总结几点最佳实践：

• License管理：提前规划好License的申请和绑定流程，确保在应用上线前完成所有授权配置。留意License的有效期，及时续期。
• 权限处理：在Android和iOS平台，需要明确在应用启动时合理处理摄像头和麦克风权限的申请，避免因权限问题导致功能异常。
• 网络环境：Web端集成必须使用HTTPS协议。在弱网环境下，建议配置License文件作为鉴权备用，以提高鉴权通过率。
• 版本选择：建议使用最新版本的SDK，以获取最新的功能支持和问题修复。同时注意不同版本之间的API差异和集成方式变化。
• Demo参考：充分利用官方提供的产品级Demo和开源示例工程。MediaBox音视频SDK的Demo包含短视频、播放器、直播推流三个子业务解决方案，各解决方案可独立运行。
• 错误处理：在业务代码中完善错误处理逻辑，对常见的错误码进行针对性处理，提升用户体验。

常见问题问答

问1：音视频终端SDK和播放器SDK是什么关系？

答：播放器SDK是MediaBox音视频SDK的子产品之一。音视频终端SDK是一体化产品，集成了直播推流、播放器、短视频、美颜特效等多个子SDK的能力。开发者可以根据需要选择集成完整的音视频终端SDK，也可以单独集成播放器SDK。

问2：License申请后多久生效？

答：License购买并绑定成功后通常立即生效。SDK初始化时会检查更新认证文件，在程序运行时也会每隔15分钟检查更新认证文件。如果遇到鉴权问题，可以检查LicenseKey和License文件的配置是否正确。

问3：推流SDK和播放器SDK可以同时集成吗？

答：推流SDK暂不支持与播放器SDK同时集成。如果需要同时使用推流和播放能力，应选择音视频终端一体化SDK。一体化SDK已经融合了推流和播放的核心能力。

问4：Web端集成必须使用HTTPS吗？

答：是的，Web端SDK必须使用HTTPS协议。这是浏览器安全策略的要求，也是WebRTC等实时音视频技术的通用规范。

问5：美颜特效功能如何集成？

答：从v6.7.0版本起，音视频终端SDK只保留基础美颜功能（美白、磨皮、锐化、红润、滤镜）。如需全功能美颜特效（美型、美妆等），需要单独接入美颜特效SDK，并申请开通对应的License。

问6：遇到SDK初始化失败怎么办？

答：首先检查SDK版本是否正确、依赖是否完整。然后确认LicenseKey和License文件（如需）配置是否正确。同时检查网络连接是否正常，因为License鉴权需要联网。如果问题仍然存在，可以查看具体的错误码，参考官方错误码列表进行排查。