鸿蒙（API 12 Beta3版）【投播组件开发指导】分布式媒体会话

通过本开发指导，完成一次音视频跨设备投播。

约束与限制

需同时满足以下条件，才能使用该功能：

设备限制

本端设备：HarmonyOS NEXT Developer Preview0及以上版本的手机设备

远端设备：HarmonyOS NEXT Developer Preview0及以上版本的2in1设备/华为智慧屏HarmonyOS3.1及以上版本
使用限制
- 双端设备打开蓝牙和WIFI，并可访问网络。

接口说明

在开发具体功能前，请先查阅参考文档，获取详细的接口说明。

[AVCastPicker]：投播组件，提供设备发现认证连接的统一入口。

[AVCastController]：投播控制器，用于投播场景下，完成播放控制、远端播放状态监听等操作。

说明

AVCastController由系统获取并返回，在设备连接成功后获取，在设备断开后不能继续使用，否则会抛出异常。

支持在线DRM视频资源投播能力，需注册DRM许可证请求回调函数，获取许可证后，调用处理许可证响应函数。

接口	说明
getAVCastController(callback: AsyncCallback): void	获取远端投播时的控制接口。
on(type: ‘outputDeviceChange’, callback: (state: ConnectionState, device: OutputDeviceInfo) => void): void	注册设备变化的回调，同时包含了设备的连接状态。
sendControlCommand(command: AVCastControlCommand, callback: AsyncCallback): void	投播会话的控制接口，用于进行投播中的各种播控指令。
setAVMetadata(data: AVMetadata, callback: AsyncCallback): void	配置媒体信息，包括ID，标题，作者以及DRM类型等。
prepare(item: AVQueueItem, callback: AsyncCallback): void	准备播放，进行资源加载和缓冲，不会触发真正的播放。
start(item: AVQueueItem, callback: AsyncCallback): void	开始播放媒体资源。
processMediaKeyResponse(assetId: string, response: Uint8Array): Promise	提供DRM资源所需的秘钥。
on(type: ‘keyRequest’, callback: KeyRequestCallback): void	注册DRM秘钥请求的回调。
on(type: ‘playbackStateChange’, filter: Array	‘all’, callback: (state: AVPlaybackState) => void): void
on(type: ‘mediaItemChange’, callback: Callback): void	注册当前播放内容更新的回调，返回当前播放的内容的信息。

开发步骤

创建播放器，并创建AVSession。

通过AVSessionManager创建并激活媒体会话。

import  { avSession }  from '@kit.AVSessionKit'; // 导入AVSession模块// 声明全局的session对象，此写法是加在class类外的声明，如果需要在class类内申明全局变量，需要去掉 export let
export let session: avSession.AVSession;
// 创建session
async createSession(context: Context) {session = await avSession.createAVSession(context, 'video_test', 'video'); // 'audio'代表音频应用，'video'代表视频应用await session.activate();// 需要将应用加入支持投播的应用名单中，才能成功投播。session.setExtras({requireAbilityList: ['url-cast'],}); console.info(`Session created. sessionId: ${session.sessionId}`);
}

设置媒体资源信息。

说明

需要在AVCastPicker中仅显示支持DRM资源投播的设备时，应在AVMetaData设置明确的drmSchemes。

// 与session声明不在同一文件时，需要import
import { session } from './xxx'; // session声明的文件public setAVMetadata(playInfo: avSession.AVMediaDescription): Promise<void> {const metadata: avSession.AVMetadata = {assetId: playInfo.assetId, // 需要配置实际idtitle: playInfo.title, // 播放媒体资源的标题subtitle: playInfo.subtitle,// 播放媒体资源的副标题// 发现Cast+ Stream 和 DLNA协议设备，TYPE_CAST_PLUS_STREAM为默认必选。filter: avSession.ProtocolType.TYPE_CAST_PLUS_STREAM|avSession.ProtocolType.TYPE_DLNA,mediaImage: playInfo.mediaImage,artist: playInfo.artist,// 如果是DRM资源，配置支持的DRM uuid 用于设备过滤。非DRM资源不配置。drmSchemes: ['3d5e6d35-9b9a-41e8-b843-dd3c6e72c42c']};return session.setAVMetadata(metadata);}

在需要投播的播放界面创建投播组件AVCastPicker。

import { AVCastPicker } from '@kit.AVSessionKit';;// 创建组件，并设置大小
build() {Row() {Column() {AVCastPicker().size({height:'100%',width:'100%'})}}
}

设置AVSession的信息，注册AVSession的回调。用于感知投播连接。

说明

下面代码展示设备连接成功后的相应的处理
- 连接成功后通过session获取AVCastController，用于后期的投播控制；
- 如需要推送DRM在线资源，根据远端设备支持的DRM能力，从服务端获取对应的资源；
- 推送DRM资源后，应注册监听许可证请求事件，从服务器端获取许可证后，通过处理许可证响应函数提供给远端。

import { BusinessError } from '@kit.BasicServicesKit';
import { avSession } from '@kit.AVSessionKit';
import { session } from './xxx'; // session声明的文件castController: avSession.AVCastController | undefined = undefined;getAVCastController() {// 监听设备连接状态的变化session.on('outputDeviceChange', async (connectState: avSession.ConnectionState,device: avSession.OutputDeviceInfo) => {let currentDevice: avSession.DeviceInfo = device?.devices?.[0];if (currentDevice.castCategory === avSession.AVCastCategory.CATEGORY_REMOTE && connectState === avSession.ConnectionState.STATE_CONNECTED) { // 设备连接成功console.info(`Device connected: ${device}`);this.castController = await session.getAVCastController();console.info('Succeeded in getting a cast controller');// 查询当前播放的状态let avPlaybackState = await this.castController?.getAVPlaybackState();console.info(`Succeeded in AVPlaybackState resource obtained: ${avPlaybackState}`);// 监听播放状态的变化this.castController?.on('playbackStateChange', 'all', (state: avSession.AVPlaybackState) => {console.info(`Succeeded in Playback state changed: ${state}`);});if (currentDevice.supportedProtocols === avSession.ProtocolType.TYPE_CAST_PLUS_STREAM) {// 此设备支持cast+投播协议} else if (currentDevice.supportedProtocols === avSession.ProtocolType.TYPE_DLNA) {// 此设备支持DLNA投播协议}// 此设备支持chinaDRM，监听许可证请求事件，也可在发起DRM资源投播前监听。if (currentDevice.supportedDrmCapabilities?.includes('3d5e6d35-9b9a-41e8-b843-dd3c6e72c42c')) {this.castController?.on('keyRequest', this.keyRequestCallback);}}})}// 处理DRM许可证请求事件private keyRequestCallback: avSession.KeyRequestCallback = async (assetId: string, requestData: Uint8Array) => {// 根据assetId获取对应的DRM urllet drmUrl: string = 'http://license.xxx.xxx.com:8080/drmproxy/getLicense';// 从服务器获取许可证，具体实现可参考附录。let licenseResponseData = await this.getLicense(drmUrl, requestData); try {// 处理DRM许可证响应await this.castController?.processMediaKeyResponse(assetId, licenseResponseData);} catch (error) {console.error(`Failed to process the response corresponding to the media key. Error: ${error}`);}}

使用AVCastController进行资源播放。

说明

下面代码示例中的url仅作示意使用，开发者需根据实际情况，确认资源有效性并设置：
- 如果使用本地资源播放，必须确认资源文件可用，并使用应用沙箱路径访问对应资源，参考[获取应用文件路径]。应用沙箱的介绍及如何向应用沙箱推送文件，请参考[文件管理]。
- 如果通过FilePicker使用用户文件，请参考[选择用户文件]。
- 如果使用网络播放路径，需[申请相关权限]：ohos.permission.INTERNET。
- 如果是DRM资源，需配置drmSchemes字段。

playItem() {// 设置播放参数，开始播放let playItem : avSession.AVQueueItem = {itemId: 0,description: {assetId: 'VIDEO-1',title: 'ExampleTitle',artist: 'ExampleArtist',mediaUri: 'https://xxx.xxx.com/example.mp4',mediaType: 'VIDEO',mediaSize: 1000,startPosition: 0,duration: 100000,albumCoverUri: 'https://www.example.jpeg',albumTitle: '《ExampleAlbum》',appName: 'ExampleApp',// DRM资源，需要配置支持的DRM类型, 以chinaDRM为例。drmScheme: '3d5e6d35-9b9a-41e8-b843-dd3c6e72c42c',}};// 准备播放，这个不会触发真正的播放，会进行加载和缓冲this.castController?.prepare(playItem, () => {console.info('Preparation done');});// 启动播放this.castController?.start(playItem, () => {console.info('Playback started');});}

使用AVCastController，监听控制命令和进行播放控制。

playControl() {// 记录从avsession获取的远端控制器// 下发播放命令let avCommand: avSession.AVCastControlCommand = {command:'play'};this.castController?.sendControlCommand(avCommand);// 下发暂停命令avCommand = {command:'pause'};this.castController?.sendControlCommand(avCommand);// 监听上下一首切换this.castController?.on('playPrevious', () => {console.info('PlayPrevious done');});this.castController?.on('playNext', () => {console.info('PlayNext done');});}

申请投播长时任务，避免应用在投播进入后台时被系统冻结，导致无法持续投播。

说明

在申请长时任务时，需要在module.json5文件中：
1. 配置长时任务权限ohos.permission.KEEP_BACKGROUND_RUNNING。
2. 为需要使用长时任务的UIAbility声明相应的后台模式类型：MULTI_DEVICE_CONNECTION。

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { wantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';let context: Context = getContext(this);function startContinuousTask() {let wantAgentInfo: wantAgent.WantAgentInfo = {// 点击通知后，将要执行的动作列表wants: [{bundleName: "com.example.myapplication",abilityName: "EntryAbility",}],// 点击通知后，动作类型operationType: wantAgent.OperationType.START_ABILITY,// 使用者自定义的一个私有值requestCode: 0,// 点击通知后，动作执行属性wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]};// 通过wantAgent模块的getWantAgent方法获取WantAgent对象try {wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {try {backgroundTaskManager.startBackgroundRunning(context,backgroundTaskManager.BackgroundMode.MULTI_DEVICE_CONNECTION, wantAgentObj).then(() => {console.info('Succeeded in requesting to start running in background');}).catch((error: BusinessError) => {console.error(`Failed to request to start running in background. Code: ${error.code}, message: ${error.message}`);});} catch (error) {console.error(`Failed to request to start running in background. Error: ${error}`);}});} catch (error) {console.error(`Failed to get WantAgent. Error: ${error}`);}
}

处理音频焦点。请参考[多音频并发处理]

在应用进入投播后，当前应用需要取消注册焦点处理事件，以免被其他应用的焦点申请而影响。
结束投播。

当远端设备断开的时候，应用会收到事件，系统会自动断开连接。

应用也可以使用断开投播的接口，主动进行投播连接的断开。

async release() {// 一般来说，应用退出时，而不希望继续投播，可以主动结束await session.stopCasting();
}

附录

从服务器获取许可证

开发者需要根据实际的资源和服务地址获取DRM许可证，以下示例代码仅作为参考。

import { http } from '@kit.NetworkKit';// 获取DRM许可证, 仅做参考，需要结合实际资源和服务地址进行获取。async getLicense(drmUrl: string, requestData: Uint8Array): Promise<Uint8Array | undefined> {let licenseRequestStr: string = this.byteToString(requestData);let licenseResponseStr: string = 'defaultStr';let httpRequest = http.createHttp();try {let response: http.HttpResponse = await httpRequest.request(drmUrl, {method: http.RequestMethod.POST,header: {'Content-Type': 'application/json','Accept-Encoding': 'gzip, deflate',},extraData: licenseRequestStr,expectDataType: http.HttpDataType.STRING,});if (response?.responseCode == http.ResponseCode.OK) {if (typeof response.result == 'string') {licenseResponseStr = response.result;}}httpRequest.destroy();} catch (error) {console.error(`Failed to request Http. Error: ${error}`);return undefined;}return this.stringToByte(licenseResponseStr);}/*** Uint8Array to string* @param arr Uint8Array* @returns string*/byteToString(arr: Uint8Array): string {let str: string = ''let _arr: Uint8Array = arrfor (let i = 0; i < _arr.length; i++) {// 将数值转为二进制字符串let binaryStr: string = _arr[i].toString(2)let matchArray = binaryStr.match(new RegExp('/^1+?(?=0)/'))if (matchArray && binaryStr.length == 8) {let bytesLength: number = matchArray[0].lengthlet store: string = _arr[i].toString(2).slice(7 - bytesLength)for (let j = 1; j < bytesLength; j++) {store += _arr[j + i].toString(2).slice(2)}str += String.fromCharCode(Number.parseInt(store, 2))i += bytesLength - 1} else {str += String.fromCharCode(_arr[i])}}return str}/*** string 转 Uint8Array* @param str string* @returns Uint8Array*/stringToByte(str: string): Uint8Array {let bytes: number[] = new Array()let unicode: numberfor (let i = 0; i < str.length; i++) {unicode = str.charCodeAt(i)if (unicode >= 0x010000 && unicode <= 0x10FFFF) {bytes.push(((unicode >> 18) & 0x07) | 0xf0)bytes.push(((unicode >> 12) & 0x3F) | 0x80)bytes.push(((unicode >> 6) & 0x3F) | 0x80)bytes.push((unicode & 0x3F) | 0x80)} else if (unicode >= 0x000800 && unicode <= 0x00FFF) {bytes.push(((unicode >> 12) & 0x07) | 0xf0)bytes.push(((unicode >> 6) & 0x3F) | 0x80)bytes.push((unicode & 0x3F) | 0x80)} else if (unicode >= 0x000800 && unicode <= 0x0007FF) {bytes.push(((unicode >> 6) & 0x3F) | 0x80)bytes.push((unicode & 0x3F) | 0x80)} else {bytes.push(unicode & 0xFF)}}return new Uint8Array(bytes);}

最后呢

很多开发朋友不知道需要学习那些鸿蒙技术？鸿蒙开发岗位需要掌握那些核心技术点？为此鸿蒙的开发学习必须要系统性的进行。

而网上有关鸿蒙的开发资料非常的少，假如你想学好鸿蒙的应用开发与系统底层开发。你可以参考这份资料，少走很多弯路，节省没必要的麻烦。由两位前阿里高级研发工程师联合打造的《鸿蒙NEXT星河版OpenHarmony开发文档》里面内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、Harmony南向开发、鸿蒙项目实战等等）鸿蒙（Harmony NEXT）技术知识点

如果你是一名Android、Java、前端等等开发人员，想要转入鸿蒙方向发展。可以直接领取这份资料辅助你的学习。下面是鸿蒙开发的学习路线图。

在这里插入图片描述