[HarmonyOS-媒体技术-AVPlayer]音视频播放开发全攻略
你还在为音视频播放功能发愁吗？
HarmonyOS的AVPlayer，就是你一直在寻找的那把“万能钥匙”！
一、功能全面，兼容性强，开箱即用
AVPlayer是HarmonyOS平台上强大的音视频播放组件，支持以下主流格式：
音频解码格式：AAC、MP3等
视频解码格式：264/AVC、H.265/HEVC等
封装格式：MP4、M4A等
无论是在线视频播放，还是本地媒体播放，AVPlayer都能轻松应对！
典型应用：图库、华为视频、华为音乐、美团、新华社、蜻蜓FM、京东、UC浏览器；
二、开发门槛低，功能强大，支持多种语言
ArkTS开发
快速构建音视频播放界面
状态监听、错误捕获、流程控制一体化
C/C++NDK开发
与底层硬件深度整合，适用于高性能播放、自定义渲染等复杂项目
三、开发流程清晰，代码结构规范，易于维护
音视频播放流程（ArkTS示例）：
//1.调用createAVPlayer创建AVPlayer实例，初始化进入idle状态。
this.avPlayer=awaitmedia.createAVPlayer;
//2.设置业务需要的监听事件，搭配全流程场景使用。其中最关键的是AVPlayer状态变化：
this.avPlayer.on(‘stateChange’,async(state,reason)=>{
if(this.avPlayer==null){
console.info(`${this.tag}:avPlayerhasnotinitonstatechange`);
return;
}
switch(state){
case‘idle’://成功调用reset接口后触发该状态机上报
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstateidlecalled.`);
break;
case‘initialized’://avplayer设置播放源后触发该状态上报
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstateinitializedcalled.`);
//4.设置窗口：获取并设置属性SurfaceID，用于设置显示画面。可在收到initialized状态回调后设置,应用需要从XComponent组件获取surfaceID，获取方式请参考[XComponent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent)
if(this.surfaceId){
this.avPlayer.surfaceId=this.surfaceId;//设置显示画面，当播放的资源为纯音频时无需设置
console.info(`${this.tag}:setAVPlayerCallbackthis.avPlayer.surfaceId=${this.avPlayer.surfaceId}`);
//5.准备播放：调用prepare，AVPlayer进入prepared状态
this.avPlayer.prepare;
}
break;
case‘prepared’://prepare调用成功后上报该状态机
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstatepreparedcalled.`);
//6.视频播控：播放play，暂停pause，跳转seek，停止stop等操作
this.avPlayer.play;//调用播放接口开始播放
break;
case‘playing’://play成功调用后触发该状态机上报
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstateplayingcalled.`);
break;
case‘completed’://播放结束后触发该状态机上报
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstatecompletedcalled.`);
break;
case‘released’:
console.info(`${this.tag}:setAVPlayerCallbackreleasedcalled.`);
break
case‘stopped’:
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstatestoppedcalled.`);
break
case‘error’:
console.error(`${this.tag}:setAVPlayerCallbackAVPlayerstateerrorcalled.`);
//7.（可选）更换资源：调用reset重置资源，AVPlayer重新进入idle状态，允许更换资源url。
this.avPlayer.reset;
break
case‘paused’:
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstatepausedcalled.`);
break
default:
console.info(`${this.tag}:setAVPlayerCallbackAVPlayerstateunknowncalled.`);
break;
}
});
//3.设置资源：设置属性url，AVPlayer进入initialized状态。
this.avPlayer.url=“xxx”;
四、NDK开发：
示例代码片段（C++）：
//1.创建AVPlayer实例：调用OH_AVPlayer_Create，AVPlayer初始化为AV_IDLE状态。
OH_AVPlayer*player=OH_AVPlayer_Create;
//2.设置回调监听函数
OHAVPlayerOnInfoCallback(OH_AVPlayer*player,AVPlayerOnInfoTypetype,OH_AVFormat*infoBody,void*userData){
AVPlayerStateavState=AV_IDLE;
switch(type){
caseAV_INFO_TYPE_STATE_CHANGE:
LOG(“AVPlayerOnInfoTypeAV_INFO_TYPE_STATE_CHANGE”);
OH_AVFormat_GetIntValue(infoBody,OH_PLAYER_STATE,&state);
OH_AVFormat_GetIntValue(infoBody,OH_PLAYER_STATE_CHANGE_REASON,&stateChangeReason);
LOG(“OHAVPlayerOnInfoCallbackAV_INFO_TYPE_STATE_CHANGEstate:%{public}d,stateChangeReason:%{public}d”,
state,stateChangeReason);
avState=static_cast(state);
switch(avState){
caseAV_IDLE://成功调用reset接口后触发该状态机上报
LOG(“AVPlayerStateAV_IDLE”);
break;
caseAV_INITIALIZED:{
LOG(“AVPlayerStateAV_INITIALIZED”);
autocontext=SampleManager::GetInstance;
//4.设置播放画面窗口：调用OH_AVPlayer_SetVideoSurface设置播放画面窗口。此函数必须在SetSource之后，Prepare之前调用。
ret=OH_AVPlayer_SetVideoSurface(player,context->nativeWindow_);
LOG(“OH_AVPlayer_SetVideoSurfaceret:%{public}d”,ret);
//5.准备播放：调用OH_AVPlayer_Prepare，AVPlayer进入AV_PREPARED状态，此时可以获取时长，设置音量。
ret=OH_AVPlayer_Prepare(player);//设置播放源后触发该状态上报
if(ret!=AV_ERR_OK){
//处理异常
LOG(“player%{public}s”,“OH_AVPlayer_PrepareErr”);
}
}break;
caseAV_PREPARED:
LOG(“AVPlayerStateAV_PREPARED”);
ret=OH_AVPlayer_SetAudioEffectMode(player,EFFECT_NONE);//设置音频音效模式
LOG(“OH_AVPlayer_SetAudioEffectModeret:%{public}d”,ret);
//6.视频播控：播放OH_AVPlayer_Play，暂停OH_AVPlayer_Pause，跳转OH_AVPlayer_Seek，停止OH_AVPlayer_Stop等操作。
ret=OH_AVPlayer_Play(player);//调用播放接口开始播放
LOG(“OH_AVPlayer_Playret:%{public}d”,ret);
break;
caseAV_PLAYING:
LOG(“AVPlayerStateAV_PLAYING”);
break;
caseAV_PAUSED:
LOG(“AVPlayerStateAV_PAUSED”);
break;
caseAV_STOPPED:
LOG(“AVPlayerStateAV_STOPPED”);
break;
caseAV_COMPLETED:
LOG(“AVPlayerStateAV_COMPLETED”);
break;
caseAV_ERROR:
LOG(“AVPlayerStateAV_ERROR”);
break;
caseAV_RELEASED:
LOG(“AVPlayerStateAV_RELEASED”);
break;
default:
break;
}
}
//3.设置资源：调用OH_AVPlayer_SetURLSource，设置属性url，AVPlayer进入AV_INITIALIZED状态。
OH_AVPlayer_SetURLSource(player,url);
五、开发建议与最佳实践
严格遵守状态机规则：在prepared/paused/completed状态下调用play，在playing状态下调用pause。
资源释放不可忽视：播放结束后务必调用release避免内存、线程等系统资源泄漏。
权限管理要到位：当需要网络访问、媒体播放权限时，需要提前申请。
六、为什么选择AVPlayer？
简单、便捷、高效——功能强大、兼容广泛、性能稳定
若你想打造本地播放、在线点播、在线直播等功能场景的应用，AVPlayer都是你不可或缺的开发利器！
七、立即行动，开启你的音视频播放开发之旅！
点击了解完整开发示例与API文档
HarmonyOSAVPlayer开发指南ArkTSAPI
HarmonyOSAVPlayer开发指南CAPI
加入HarmonyOS社区，共创未来！
我们诚邀广大开发者一起参与HarmonyOS技术生态建设，共建更开放、更智能的未来世界！
加入开发者社区，获取最新资讯和技术支持
HarmonyOS官方社区
让AVPlayer成为你开发路上的得力助手，开启你的音视频播放新纪元！
