鸿蒙（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	注册当前播放内容更新的回调，返回当前播放的内容的信息。

开发步骤

1. 创建播放器，并创建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}`);
}

1. 设置媒体资源信息。

   说明

   需要在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);
  }

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

import { AVCastPicker } from '@kit.AVSessionKit';;

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

1. 设置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}`);
    }
  }

1. 使用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');
    });
  }

1. 使用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');
    });
  }

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

   说明

   在申请长时任务时，需要在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}`);
    }
}

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

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

2. 结束投播。

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

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

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 万款的应用。那么这么多的应用需要开发，也就意味着需要有更多的鸿蒙人才。鸿蒙开发工程师也将会迎来爆发式的增长，学习鸿蒙势在必行！ 自↓↓↓拿