鸿蒙（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, // 需要配置实际id
title: 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 url
let 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 = arr

    for (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].length
        let 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: number

    for (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、前端等等开发人员，想要转入鸿蒙方向发展。可以直接领取这份资料辅助你的学习。下面是鸿蒙开发的学习路线图。

针对鸿蒙成长路线打造的鸿蒙学习文档。话不多说，我们直接看详细鸿蒙（OpenHarmony ）手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门视频，帮助大家在技术的道路上更进一步。

《鸿蒙 (OpenHarmony)开发学习视频》
《鸿蒙生态应用开发V2.0白皮书》
《鸿蒙 (OpenHarmony)开发基础到实战手册》
OpenHarmony北向、南向开发环境搭建
《鸿蒙开发基础》
《鸿蒙开发进阶》
《鸿蒙开发实战》

总结

鸿蒙---作为国家主力推送的国产操作系统。部分的高校已经取消了安卓课程，从而开设鸿蒙课程；企业纷纷跟进启动了鸿蒙研发。

并且鸿蒙是完全具备无与伦比的机遇和潜力的；预计到年底将有 5,000 款的应用完成原生鸿蒙开发，未来将会支持 50 万款的应用。那么这么多的应用需要开发，也就意味着需要有更多的鸿蒙人才。鸿蒙开发工程师也将会迎来爆发式的增长，学习鸿蒙势在必行！自↓↓↓拿