OpenHarmony AVScreenCaptureRecorder录屏开发指导

一、简介

OpenHarmony 5.0新增了AVScreenCaptureRecorder ArkTs API。用户可以调用录屏AVScreenCaptureRecorder API录制屏幕，采集音频源数据，获取封装后的音视频文件，然后通过文件的形式流转到其他模块进行播放或处理，用于以文件形式分享屏幕内容的场景。

二、框架图

屏幕录制：应用通过AVScreenCapture ArkTs接口实现屏幕录制功能时，框架层会通过录屏框架，调用图形服务捕获屏幕视频数据，调用音频服务捕获音频数据，通过媒体录制服务将音视频数据编码封装后保存至文件中，实现屏幕录制功能。

三、版本信息

OpenHarmony-v5.0.1-Release 标准系统。AVScreenCaptureRecorder ArkTs API从API version 12开始支持。

四、API参考

详细的API参考可查看 AVScreenCaptureRecorder API

  // 创建屏幕录制实例
  createAVScreenCaptureRecorder(): Promise<AVScreenCaptureRecorder>

   // 设置录屏参数，异步方式进行录屏初始化
  init(config: AVScreenCaptureRecordConfig): Promise<void>

  // 异步方式开始录屏
  startRecording(): Promise<void>

  // 异步方式结束录屏
  stopRecording(): Promise<void>

  // 录屏时，应用可对本应用的隐私窗口做安全豁免。如录屏时，用户在本应用进行输入密码等操作，应用不  会进行黑屏处理
  skipPrivacyMode(windowIDs: Array<number>): Promise<void>

  // 异步方式设置麦克风开关
  setMicEnabled(enable: boolean): Promise<void>

  // 异步方式释放录屏实例
  release(): Promise<void>

  // 订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户
  on(type: 'stateChange', callback: Callback<AVScreenCaptureStateCode>): void

  // 订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理
  on(type: 'error', callback: ErrorCallback): void

  interface AVScreenCaptureRecordConfig {
    fd: number;                            // 录制输出的文件fd，必需参数
    frameWidth?: number;                   //录屏的视频宽度，默认屏幕宽度，非必需参数
    frameHeight?: number;
    videoBitrate?: number;
    audioSampleRate?: number;
    audioChannelCount?: number;
    audioBitrate?: number;
    preset?: AVScreenCaptureRecordPreset;  // 录屏使用的编码和封装格式，非必需参数
  }

  enum AVScreenCaptureRecordPreset { 
    SCREEN_RECORD_PRESET_H264_AAC_MP4 = 0,
    SCREEN_RECORD_PRESET_H265_AAC_MP4 = 1,
  }
  // 屏幕录制的状态回调
  enum AVScreenCaptureStateCode {
    SCREENCAPTURE_STATE_STARTED = 0,                   // 录屏已开始
    SCREENCAPTURE_STATE_CANCELED = 1,                  // 录屏被取消
    SCREENCAPTURE_STATE_STOPPED_BY_USER = 2,           // 录屏被用户手动停止
    SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER = 3,      // 录屏被其他录屏打断
    SCREENCAPTURE_STATE_STOPPED_BY_CALL = 4,           // 录屏被来电打断
    SCREENCAPTURE_STATE_MIC_UNAVAILABLE = 5,           // 录屏无法使用麦克风录音
    SCREENCAPTURE_STATE_MIC_MUTED_BY_USER = 6,         // 麦克风被用户关闭
    SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER = 7,       // 麦克风被用户打开
    SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE = 8,       // 录屏进入隐私页面
    SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE = 9,        // 录屏退出隐私页面
    SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES = 10, //系统用户切换，录屏中断
  }

五、开发步骤

1、导入头文件

import media from '@ohos.multimedia.media';

2、创建一个AVScreenCaptureRecorder类型的成员变量

// 声明一个AVScreenCaptureRecorder类型的变量
private screenCapture?: media.AVScreenCaptureRecorder;
// 创建一个AVScreenCaptureRecorder实例
this.screenCapture = await media.createAVScreenCaptureRecorder();

3、对录屏实例设置状态切换监听函数，可监听录屏不同状态和异常情况

  this.screenCapture.on('stateChange', async (infoType: media.AVScreenCaptureStateCode) => {
	switch (infoType) {
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_STARTED:
          	console.info("开始录屏成功后收到的回调");
          	break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_CANCELED:
            this.screenCapture?.release();
            this.screenCapture = undefined;
          	break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_STOPPED_BY_USER:
            this.screenCapture?.release();
            this.screenCapture = undefined;
          	break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER:
            console.info("录屏因其他中断而停止，底层录制已停止");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_STOPPED_BY_CALL:
            console.info("录屏过程因通话中断，底层录制已停止");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_MIC_UNAVAILABLE:
            console.info("录屏麦克风不可用");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_MIC_MUTED_BY_USER:
            console.info("录屏麦克风被用户静音");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER:
            console.info("录屏麦克风被用户取消静音");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE:
            console.info("录屏进入隐私场景");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE:
            console.info("录屏退出隐私场景");
            break;
        case media.AVScreenCaptureStateCode.SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES:
            console.info("用户账号切换，底层录制已停止");
            break;
        default:
          	break;
    }
  })
  this.screenCapture.on('error', (err) => {
    console.info("异常情况处理");
  })

4、配置屏幕录制参数。

​创建AVScreenCaptureRecorder实例后，可以设置屏幕录制所需要的参数

​参数videoBitrate、audioSampleRate、audioChannelCount、audioBitrate、preset都是可选参数，若不设置则可按默认值进行设置。

  captureConfig: media.AVScreenCaptureRecordConfig = {
    // 用户可以根据需求设置录屏宽高
    frameWidth: 1920,
    frameHeight: 1080,
    // 新建文件fd
    fd: xx,
    // 可选参数的默认值
    videoBitrate: 10000000,
    audioSampleRate: 48000,
    audioChannelCount: 2,
    audioBitrate: 96000,
    preset: media.AVScreenCaptureRecordPreset.SCREEN_RECORD_PRESET_H264_AAC_MP4
  };

5、基于预先配置的屏幕录制参数，调用init()方法初始化录屏实例

await this.screenCapture.init(this.captureConfig);

6、创建豁免隐私窗口，这里填写子窗口id和主窗口id，具体开发步骤可参见窗口API

let windowIDs = [xxx, xxx];
await screenCapture.skipPrivacyMode(windowIDs);

7、调用startRecording()方法开始进行屏幕录制，并通过监听函数监听状态。

await this.screenCapture.startRecording();

8、停止录屏

（1）点击录屏胶囊中的结束按钮停止录制：基于回调函数实现，录屏实例会触发SCREENCAPTURE_STATE_STOPPED_BY_USER的回调，通知应用此次录屏已停止，不需要应用主动调用stopRecording()方法。

（2）应用主动调用stopRecording()方法，停止录屏

await this.screenCapture.stopRecording();

9、调用release()方法销毁实例，释放资源。

await this.screenCapture.release();

六、注意事项

1、目前AVScreenCaptureRecorder ArkTs API功能是受限的，用户若想实现更丰富的录屏功能可以调用Native API，比如获取录屏码流数据、选择音频源等；

2、开始屏幕录制时正在通话中或者屏幕录制过程中来电，录屏将自动停止；因通话中断的录屏会上报SCREENCAPTURE_STATE_STOPPED_BY_CALL状态；

3、如果配置了采集麦克风音频数据，需对应配置麦克风权限ohos.permission.MICROPHONE和申请长时任务；

4、音频默认录制的是系统音和麦克风的混合声音，内录的系统音和外录的麦克风共用用户配置的音频参数；

5、录屏的音频采样率默认是48000Hz，仅支持设置48000或16000；

6、录屏的音频通道数，默认2声道，仅支持设置1或2声道。