阿里云音视频终端SDK全平台对接实战指南：从License申请到核心功能集成
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的其他应用盗用。
3.2 License鉴权机制
音视频终端SDK的License鉴权流程依赖LicenseKey与License文件。LicenseKey用于请求更新License文件，SDK初始化时会检查更新认证文件，在程序运行时也会每隔15分钟检查更新认证文件。License文件用于当未能从服务端成功请求到认证时鉴权使用的认证文件，例如由于网络问题导致无法下载认证等极端情况。
认证文件内容包含了开通的权限以及有效期间。因此，为了在弱网络环境下提高鉴权通过率，建议在权限发生变化时主动更新内置认证文件。Native端播放器SDK 7.6.0版本之后必须配置License文件，Web端不需要配置License文件。
4. 各平台SDK集成步骤
4.1 Android端集成
在开始集成之前，请确保开发环境满足以下要求：Android Studio 2020.3.1及以上版本，Android 5.0（SDK API Level 21）及以上版本的测试设备，且需要连接网络环境。
第一步，在项目级build.gradle文件中添加阿里云Maven仓库：
allprojects {
repositories {
google()
jcenter()
maven {
url 'https://maven.aliyun.com/repository/google'
}
maven {
url 'https://maven.aliyun.com/repository/public'
}
maven {
url "https://maven.aliyun.com/nexus/content/repositories/releases"
}
}
}第二步，在app/build.gradle文件中添加SDK依赖：
dependencies {
// 实时通信SDK (RTC SDK)
implementation 'com.aliyun.aio:AliVCSDK_ARTC:7.10.0'
// 或根据场景选择其他组合SDK
// implementation 'com.aliyun.aio:AliVCSDK_Standard:x.x.x'
// implementation 'com.aliyun.aio:AliVCSDK_InteractiveLive:x.x.x'
}第三步，在AndroidManifest.xml中添加设备权限：
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />第四步，在代码中初始化SDK并配置License：
// 创建引擎实例
String userId = "123"; // 推荐使用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
)
);
}
// 如果是视觉理解类型，配置本地视频预览显示的视图容器
if (aiAgentType == VisionAgent) {
ViewGroup previewLayer;
engine.setLocalView(previewLayer,
new FrameLayout.LayoutParams(
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
);
}4.2 iOS端集成
iOS端推荐使用CocoaPods进行集成。首先在Podfile中添加依赖：
platform :ios, '10.0'
target 'YourAppTarget' do
pod 'AliVCSDK_ARTC', '7.10.0'
# 或根据场景选择
# pod 'AliVCSDK_Standard', 'x.x.x'
# pod 'AliVCSDK_InteractiveLive', 'x.x.x'
end执行pod install命令安装依赖。在代码中初始化SDK时，需要配置License信息：
// 初始化SDK并配置License
// License Key从控制台获取
[AlivcLiveBase setLicenseKey:@"your_license_key"];4.3 Web端集成
Web端集成最为轻量，只需在HTML页面中引入SDK的JavaScript文件即可。Web端播放器SDK通过HTML5的video标签在Web应用中实现视频播放。
第一步，在页面中引入播放器SDK：
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>阿里云Web播放器示例</title>
</head>
<body>
<div id="player-container"></div>
<script src="https://g.alicdn.com/apsara-media-box/imp-web-player/2.29.1/aliplayer-min.js"></script>
<script>
// 初始化播放器并配置License
var player = new Aliplayer({
id: 'player-container',
width: '100%',
height: '500px',
license: {
domain: 'example.com', // 申请License时填写的域名
key: 'your_license_key' // 控制台获取的License Key
},
source: 'https://example.com/video.mp4',
autoplay: true,
isLive: false
});
</script>
</body>
</html>Web端播放器SDK 2.28.0及之后版本的集成使用需要接入License服务。如果使用Vue框架，可以基于阿里云Web播放器SDK封装Vue组件。
5. 直播推流功能实现
直播推流是把采集阶段封装好的音视频直播流推送到阿里云直播服务中心的过程。阿里云推流SDK是基于阿里云强大内容分发网络和音视频实时通讯技术的客户端推流开发工具，支持Android、iOS、Flutter多端多平台推流。
5.1 Android端推流实现
以下代码展示了如何在Android端实现基础的直播推流功能：
// 创建推流配置对象
AlivcLivePushConfig pushConfig = new AlivcLivePushConfig();
pushConfig.setResolution(AlivcResolutionEnum.RESOLUTION_720P);
pushConfig.setFps(20);
pushConfig.setVideoEncodeGop(2);
pushConfig.setVideoCodec(AlivcVideoCodecEnum.VIDEO_CODEC_H264);
// 创建推流客户端
AlivcLivePusher pusher = new AlivcLivePusher();
pushConfig.setAudioCodec(AlivcAudioCodecEnum.AUDIO_CODEC_AAC);
pushConfig.setAudioSampleRate(AlivcAudioSampleRateEnum.AUDIO_SAMPLE_RATE_44100);
// 设置推流地址并开始推流
String pushUrl = "rtmp://push.aliyun.com/live/stream_key";
pusher.startPreview(context, frameLayout); // 开始预览
pusher.startPush(pushUrl); // 开始推流
// 停止推流
pusher.stopPush();
pusher.stopPreview();
pusher.destroy();5.2 Web端RTS推流
阿里云RTS推流SDK支持利用浏览器进行本地混流，将多个视频源合并为一路：
// 创建推流客户端实例
const pushClient = AliRTS.createPusher();
// 获取视频效果管理器实例
const videoEffectManager = pushClient.getVideoEffectManager();
// 监听推流事件
pushClient.on('connect', () => {
console.log('推流连接成功');
});
pushClient.on('error', (error) => {
console.error('推流错误:', error);
});
// 开始推流
const pushUrl = 'rtmp://push.aliyun.com/live/stream_key';
pushClient.startPush(pushUrl);6. 视频播放功能实现
阿里云播放器SDK提供高稳定、高性能、全平台的音视频解码能力，适用于视频直播、视频点播、音频收听等音视频消费场景。播放器SDK同时支持视频直播、点播常见协议，无缝对接直播服务。
6.1 Android端播放器
// 创建播放器实例
AliPlayer player = new AliPlayer(context);
// 设置播放源
String videoUrl = "https://example.com/video.mp4";
player.setDataSource(videoUrl);
// 准备播放
player.prepare();
// 开始播放
player.start();
// 暂停播放
player.pause();
// 停止播放
player.stop();
// 释放资源
player.release();6.2 iOS端播放器
// 创建播放器实例
AliPlayer *player = [[AliPlayer alloc] init];
// 设置播放源
NSString *videoUrl = @"https://example.com/video.mp4";
[player setDataSource:videoUrl];
// 准备播放
[player prepare];
// 开始播放
[player start];
// 暂停播放
[player pause];6.3 Web端播放器进阶配置
Web播放器SDK提供可视化的在线体验，支持自动播放、自定义播放器外观和控件、视频截图等常见功能。
var player = new Aliplayer({
id: 'player-container',
width: '100%',
height: '500px',
license: {
domain: 'example.com',
key: 'your_license_key'
},
source: 'https://example.com/stream.m3u8',
autoplay: true,
isLive: true, // 直播流
format: 'm3u8',
preload: true,
cover: 'https://example.com/cover.jpg',
// 清晰度切换
qualitySort: 'asc',
// 多码率自适应
enableAdaptive: true
});
// 播放控制
player.play();
player.pause();
player.seek(30); // 跳转到30秒
// 事件监听
player.on('ready', function() {
console.log('播放器就绪');
});
player.on('error', function(error) {
console.error('播放错误:', error);
});7. 美颜特效功能集成
从v6.7.0版本起，音视频终端SDK对全功能美颜特效场景进行分离，SDK只保留基础美颜功能（美白、磨皮、锐化、红润、滤镜）。如果需要更专业的美颜特效能力，可以单独集成美颜特效SDK。
阿里云推流SDK集成了Queen智能美化特效，开放含人脸识别的高级美颜功能，可实现瘦脸、小脸、大眼以及基于人脸识别的美白功能。集成Queen智能美化特效功能需要申请开通License。
// Android端开启基础美颜
AlivcLivePushConfig pushConfig = new AlivcLivePushConfig();
// 开启基础美颜
pushConfig.setBeautyOn(true);
// 设置美颜级别（0-100）
pushConfig.setBeautyLevel(80);
// 设置美白级别（0-100）
pushConfig.setWhitenLevel(70);
// 设置红润级别（0-100）
pushConfig.setRuddyLevel(50);
// 如果集成了Queen美颜特效SDK
// QueenEngine queenEngine = new QueenEngine();
// queenEngine.setBeautyLevel(80);
// queenEngine.setWhitenLevel(70);
// queenEngine.setFaceSlimming(50); // 瘦脸
// queenEngine.setEyeEnlarging(30); // 大眼8. 实时音视频（RTC）功能实现
阿里云RTC采用信令与媒体分离的分布式设计。信令服务负责会话管理、用户加入退出频道、权限控制等控制面任务，而媒体服务专门处理音视频数据的实时传输与转发。这种架构设计实现了完全无中心节点瓶颈，信令服务和媒体服务都采用分布式设计，支持无限扩展和高可用架构。
阿里云RTC搭建了1500+边缘节点构成的全球实时传输网络GRTN，结合全链路WebRTC协议实现200至400毫秒的端到端超低延迟。
8.1 Token鉴权机制
Token是阿里云设计的一种安全保护签名，目的是为了阻止恶意攻击者盗用云服务使用权。需要在相应SDK的登录函数中提供AppID、UserID、ChannelId、Nonce、TimeStamp和Token信息。
服务端生成Token的Java示例：
// 服务端生成Token（Java示例）
public String generateToken(String appId, String userId, String channelId) {
long timestamp = System.currentTimeMillis() / 1000;
int nonce = new Random().nextInt(100000);
// 使用AppKey进行签名
String signStr = appId + userId + channelId + timestamp + nonce;
String token = HMAC_SHA256(signStr, appKey);
// 组装Token
return appId + ":" + userId + ":" + channelId + ":" +
timestamp + ":" + nonce + ":" + token;
}8.2 客户端加入频道
Android端加入RTC频道：
// 创建RTC引擎实例
AliRtcEngine engine = AliRtcEngine.getInstance(context);
// 设置事件监听
engine.setEventHandler(new AliRtcEngineEventHandler() {
@Override
public void onJoinChannelResult(int result, String channel) {
if (result == 0) {
Log.d("RTC", "加入频道成功: " + channel);
} else {
Log.e("RTC", "加入频道失败: " + result);
}
}
@Override
public void onLeaveChannelResult(int result) {
Log.d("RTC", "离开频道");
}
});
// 加入频道
String channelId = "test_channel";
String userId = "user_001";
String token = "your_generated_token";
engine.joinChannel(token, channelId, userId);
// 离开频道
engine.leaveChannel();
// 销毁引擎
engine.destroy();8.3 推拉流模式选择
RTC提供两种模式：
互动模式：有角色限制，只有被赋予主播身份的用户可以进行推流操作。参与者可以灵活地切换角色。观众的任何活动不会通告给主播，保持了主播的直播流程不受干扰。
通信模式：无角色限制，所有参与者都拥有推流和拉流的权限。会议参与者能够相互察觉到彼此的存在。
9. 进阶特性实战
9.1 自定义视频采集
在某些场景下，开发者可能需要从非摄像头源采集视频数据（如屏幕录制、外部视频文件等）。SDK支持自定义视频采集接口：
// 自定义视频采集（Android）
pusher.setCustomVideoCapture(true);
// 推送自定义视频帧
byte[] videoData; // YUV或RGB数据
int width = 1280;
int height = 720;
int rotation = 0;
long pts = System.currentTimeMillis() * 1000; // 微秒
pusher.inputVideoFrame(videoData, width, height, rotation, pts);9.2 本地混流
推流SDK默认只支持一路视频流，开启本地混流后可以采集多路视频流和一路音频流，并按照需要调整这些视频流的位置和大小。
// Web端开启本地混流
const pushClient = AliRTS.createPusher();
// 获取视频效果管理器
const videoEffectManager = pushClient.getVideoEffectManager();
// 添加混流布局
const mixStreamConfig = {
layout: [
{ x: 0, y: 0, width: 640, height: 360, zOrder: 0 },
{ x: 660, y: 0, width: 300, height: 200, zOrder: 1 }
]
};
pushClient.startMixStream(mixStreamConfig);9.3 跨频道订阅
在复杂的实时音视频场景中，可能需要跨频道订阅音视频流：
// Android端跨频道订阅
// 订阅B房间中B1的摄像头流和音频流
aliRtcEngine.subscribeRemoteVideoStream(
"targetUserId",
AliRtcEngine.AliRtcVideoTrack.AliRtcVideoTrackCamera
);
aliRtcEngine.subscribeRemoteAudioStream("targetUserId", true);10. 常见问题排查与最佳实践
10.1 常见错误码
实时音视频SDK常见的错误码及对应解决方案：
- 0x01010301：鉴权参数错误。检查Token生成时使用的AppID、UserID、ChannelId等参数是否与SDK传入的一致。
- 33620481（JoinBadAppId）：AppId不存在。请在控制台确认应用是否已创建。
- 33620484（JoinBadChannel）：频道不存在或已过期。
10.2 播放异常排查
首先判断当前音视频流的协议是否为操作系统与应用环境所支持，若不支持，请做转码处理。播放器SDK支持的音视频协议及编码格式需要提前确认。
10.3 最佳实践建议
License安全：AppKey必须妥善保管，绝对不可在客户端代码中明文暴露，避免安全风险。建议在服务端生成Token后下发给客户端。
权限申请：在调用SDK前检查APP麦克风、摄像头权限，如未授权则弹框交给用户进行授权。
版本升级：从v6.6.0及以下版本的SDK升级到v6.7.0（含）以上版本时，需注意美颜特效集成的变更。新购License订单不兼容旧版Web播放器SDK，建议接入2.29.1及以上版本。
弱网优化：License文件建议内置在应用中，用于当未能从服务端成功请求到认证时鉴权使用，提高弱网络环境下的鉴权通过率。
Demo参考：MediaBox音视频SDK Demo提供完整的产品级交互UI和业务源码，帮助开发者快速实现业务需求。
11. 问答环节
问1：阿里云音视频终端SDK是否支持免费试用？
答：支持。开发者可以通过控制台申请试用版License，在试用期内免费使用SDK的核心功能。具体试用申请流程请参考控制台的“我的授权”页面。
问2：Android和iOS端是否可以共用同一个License？
答：不可以。License通过与应用标识一一绑定，Android端绑定包名和签名MD5，iOS端绑定BundleID。不同平台需要分别创建应用并绑定对应的License。
问3：Web播放器SDK是否需要配置License文件？
答：不需要。Web端只需在初始化播放器时传入license字段，包含域名和License Key即可，无需配置License文件。
问4：推流SDK和播放器SDK可以同时集成吗？
答：可以。但推流SDK暂不支持与播放器SDK（AliyunPlayer）同时集成，如果需要同时集成推流和播放能力，建议选择音视频终端一体化SDK。
问5：RTC通信模式和互动模式有什么区别？
答：通信模式无角色限制，所有参与者都可推流和拉流，适合视频会议等场景。互动模式有角色限制，只有主播可推流，观众只能拉流，适合直播互动场景。
问6：遇到鉴权失败应该如何排查？
答：首先检查AppID是否正确，确认应用已在控制台创建。其次验证Token生成参数（UserID、ChannelId、Timestamp、Nonce）是否与SDK传入的一致。最后可以使用阿里云提供的示例代码运行后对比验证。
