1. 认识阿里云音视频终端SDK
阿里云音视频终端SDK，官方统称为MediaBox音视频SDK，是阿里云面向开发者推出的一站式音视频解决方案。该SDK将直播推流、视频播放、短视频创作、美颜特效、音频特效等核心能力整合为一体，支持移动端、桌面端、Web端等多终端接入。开发者可以根据业务需求灵活选择集成方式——既可以采用一体化SDK一次性接入多个功能模块，也可以按照业务需要自由组合单独的SDK，按需打包贴合实际场景。
MediaBox音视频SDK底层依托阿里云视频直播、视频点播、智能媒体服务等云产品，覆盖了从拍摄、编辑、上传、推流到播放的完整音视频业务链条。产品级Demo和开源UI组件的配套提供，使得开发者可以低代码方式快速搭建应用。经过数亿级请求量的打磨，该SDK在功能稳定性、服务质量等方面均有可靠保障。
2. SDK选型：一体化与模块化
在正式对接之前，开发者需要根据业务场景选择合适的SDK形态。MediaBox音视频SDK目前提供两种主要的集成方案：
一体化SDK方案：融合直播和点播核心能力，复用核心组件，能够缩小SDK包体积。一次集成即可获得多个功能模块，适合需要直播、点播、短视频等多种能力的综合性应用。
模块化SDK方案：按照业务需要自由组合功能模块，按需打包贴合业务场景。目前MediaBox音视频SDK提供四个场景的一体化SDK：基础直播SDK、互动直播SDK、短视频场景SDK、标准一体化SDK。每个场景SDK内部已经包含了对应场景所需的播放器、推流、ARTC等子SDK能力。
对于只需要实时音视频通话能力的场景，可以选择ARTC SDK单独集成。如果业务场景还需要用到直播与点播能力，则推荐使用音视频终端组合SDK，例如AliVCSDK_Standard或AliVCSDK_InteractiveLive。具体组合方式可参考官方的SDK选择与下载文档。
3. License申请与鉴权流程
需要先登录阿里云控制台，点击：阿里云控制台
音视频终端SDK通过License机制进行授权管理，License通过与应用标识一一绑定，以实现对该应用调用SDK进行授权。获取SDK License后，需要在对应的直播推流SDK、短视频SDK、播放器SDK、美颜特效SDK中接入License以完成授权流程。
3.1 创建应用
进入点播控制台的“我的授权”页面，选择应用管理标签页，点击创建应用。编辑应用信息时，需要根据端类型区分填写：
- Web端：依次填入应用名称和对应的Web域名。标准填写示例为"aliyun.com"。当需要同时覆盖多个子域名时（例如pc.aliyun.com和mobile.aliyun.com），只需填写主域名即可。需要注意不能包含协议头（如http://或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 添加Maven仓库
在项目级build.gradle文件中添加阿里云Maven仓库：
allprojects { repositories { google() jcenter() maven { url 'https://maven.aliyun.com/repository/google' } maven { url 'https://maven.aliyun.com/repository/public' } } }
4.3 引入SDK依赖
在app模块的build.gradle文件中引入对应的SDK依赖。以ARTC SDK为例：
dependencies { implementation 'com.aliyun.aio:AliVCSDK_ARTC:x.x.x' implementation 'com.aliyun.auikits.android:ARTCAICallKit:x.x.x' implementation 'com.alivc.live.component:PluginAEC:2.0.0' }
其中x.x.x需要替换为工程适配的版本号。ARTC SDK最新版本为7.10.0，AICallKit SDK最新版本为2.11.0。
4.4 申请应用权限
在AndroidManifest.xml中声明摄像头和麦克风权限，并在运行时动态申请：
<uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.RECORD_AUDIO" />
权限申请示例代码：
PermissionX.init(this) .permissions(PermissionUtils.getPermissions()) .request((allGranted, grantedList, deniedList) -> { // 处理权限申请结果 });
4.5 创建与初始化引擎
创建并初始化ARTCAICallEngine引擎：
String userId = "123"; // userId推荐使用App登录后的用户id ARTCAICallEngineImpl engine = new ARTCAICallEngineImpl(this, userId);
如果使用数字人类型，需要配置数字人显示的视图容器：
if (aiAgentType == AvatarAgent) { ViewGroup avatarlayer; engine.setAgentView(avatarlayer, new ViewGroup.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT )); }
如果使用视觉理解类型，需要配置本地视频预览显示的视图容器：
else if (aiAgentType == VisionAgent) { ViewGroup previewLayer; engine.setLocalView(previewLayer, new FrameLayout.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT )); }
5. iOS平台集成指南
5.1 环境要求
iOS平台集成需要Xcode 16.0及以上版本（推荐使用最新正式版本），CocoaPods 1.9.3及以上版本。
5.2 创建Podfile
在项目目录下执行命令`pod init`创建Podfile文件。
5.3 添加SDK依赖
修改Podfile文件，添加SDK依赖。以互动直播场景为例：
pod 'AliVCSDK_InteractiveLive' # 适用于互动直播的音视频终端SDK # 或使用标准版 pod 'AliVCSDK_Standard'
执行命令`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：
npm install aliyun-webrtc-sdk
6.3 初始化SDK
Web端初始化示例：
import AliRtcEngine from 'aliyun-webrtc-sdk'; const engine = new AliRtcEngine(); // 配置AppId和频道信息等参数 engine.joinChannel({ appId: 'your-app-id', channelId: 'your-channel-id', userId: 'your-user-id' });
6.4 RTS拉流
对于RTS超低延时直播场景，可以通过以下方式接入：
var aliRts = AliRTS.createClient(); // 检测浏览器是否支持 aliRts.isSupport().then(result => { if (result.support) { // 开始RTS拉流 aliRts.startPlay(url, videoElement); } });
7. 核心功能模块详解
7.1 直播推流
直播推流SDK提供了将采集的音视频流推送到阿里云直播服务的能力。推流SDK支持多路视频采集和本地混流，默认只支持一路视频流，开启本地混流后可以采集多路视频流和一路音频流，并按照需要调整这些视频流的位置和大小。
获取视频效果管理器的示例：
const videoEffectManager = pushClient.getVideoEffectManager();
推流URL中需要填入有效的推流RTMP地址。推流成功后，可以使用阿里云播放器SDK、FFplay、VLC等工具查看播放效果。
需要注意的是，推流SDK暂不支持与播放器SDK同时集成。如果需要同时集成推流SDK和播放器SDK，应选择音视频终端一体化SDK。
7.2 视频播放
播放器SDK是MediaBox音视频SDK的子产品之一，提供直播和点播场景中的视频播放功能，支持Web、Android、iOS、Flutter、HarmonyOS、Windows、macOS等多种平台。
Web播放器SDK初始化示例：
var player = new Aliplayer({ license: { domain: "example.com", // 申请License时填写的域名 key: "example-key" // License Key }, source: "https://example.com/video.mp4", width: "100%", height: "500px" });
播放器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内部采集的示例：
// Android mAliRtcEngine.enableLocalVideo(false); // iOS [_engine enableLocalVideo:NO]; // Mac [self.engine enableLocalVideo:NO]; // Windows mAliRtcEngine->EnableLocalVideo(false);
设置自定义采集视频源的示例：
// Android - YUV方式输入 mAliRtcEngine.setExternalVideoSource( true, // 开启外部采集 false, // 不使用纹理 AliRtcVideoTrackCamera, // 相机流 AliRtcRenderModeAuto // 自动渲染模式 );
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。集成美颜特效SDK需要申请开通对应的License。
问6：遇到SDK初始化失败怎么办？
答：首先检查SDK版本是否正确、依赖是否完整。然后确认LicenseKey和License文件（如需）配置是否正确。检查网络连接是否正常，因为License鉴权需要联网。如果问题仍然存在，可以查看具体的错误码，参考官方错误码列表进行排查。
