输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
指南与API参考指南媒体Media Kit（媒体服务）媒体开发指导(C/C++)录制使用AVScreenCapture录屏写文件(C/C++)

使用AVScreenCapture录屏写文件(C/C++)

更新时间: 2026-09-23 02:54
复制页面
本文导读

录屏主要为主屏幕录屏功能。

开发者可以调用AVScreenCapture模块的C API接口，完成录屏，采集设备内、麦克风等的音视频源数据。可以调用录屏模块获取音视频文件，然后通过文件的形式流转到其他模块进行播放或处理，达成文件形式分享屏幕内容的场景。

录屏模块和窗口（Window）、图形（Graphic）等模块协同完成整个视频采集的流程。

使用AVScreenCapture录屏涉及到AVScreenCapture实例的创建、音视频采集参数的配置、采集的开始与停止、资源的释放等。

开始录屏时正在通话中或者录屏过程中来电，录屏将自动停止。因通话中断的录屏会上报OH_SCREEN_CAPTURE_STATE_STOPPED_BY_CALL状态。

录屏过程中发生系统用户切换事件时，录屏将自动停止。因系统用户切换中断的录屏会上报OH_SCREEN_CAPTURE_STATE_STOPPED_BY_USER_SWITCHES状态。

本开发指导将以完成一次屏幕数据录制的过程为例，向开发者讲解如何使用AVScreenCapture进行录屏，详细的API声明请参考AVScreenCapture API参考。

如果配置了采集麦克风音频数据，需申请对应麦克风权限ohos.permission.MICROPHONE和长时任务。配置方式请参考向用户申请权限、申请长时任务。

从API version 22开始，在PC/2in1设备上对应用进行录屏时，可通过申请权限ohos.permission.TIMEOUT_SCREENOFF_DISABLE_LOCK，实现在屏幕熄灭但不锁屏的场景下，继续保持录制的效果，配置方式请参见声明权限。

从API version 22开始，在PC/2in1设备上对应用进行录屏时，可通过申请权限ohos.permission.CUSTOM_SCREEN_RECORDING，实现在录屏时不再弹出隐私告警弹窗。配置方式请参见受限开放权限。

开发步骤及注意事项

使用AVScreenCapture时要明确其状态的变化，在创建实例后，调用对应的方法可以进入指定的状态实现对应的行为。

在确定的状态下执行不合适的方法会导致AVScreenCapture发生错误，开发者需要在调用状态转换的方法前进行状态检查，避免程序运行异常。

在 CMake 脚本中链接动态库

收起
自动换行
深色代码主题
复制
  1. target_link_libraries(entry PUBLIC libnative_avscreen_capture.so libability_runtime.so libnative_display_manager.so)

  1. 添加头文件。

    收起
    自动换行
    深色代码主题
    复制
    1. #include "hilog/log.h"
    2. #include "napi/native_api.h"
    3. #include <window_manager/oh_display_info.h>
    4. #include <window_manager/oh_display_manager.h>
    5. #include <AbilityKit/ability_runtime/application_context.h>
    6. #include <multimedia/player_framework/native_avscreen_capture.h>
    7. #include <multimedia/player_framework/native_avscreen_capture_base.h>
    8. #include <multimedia/player_framework/native_avscreen_capture_errors.h>
    9. #include <unistd.h>
    10. #include <fcntl.h>
    11. #include <string>
    main.h

  2. 创建AVScreenCapture实例g_avCapture。

    收起
    自动换行
    深色代码主题
    复制
    1. g_avCapture = OH_AVScreenCapture_Create();
    napi_init.cpp

  3. 配置录屏参数。

    创建AVScreenCapture实例g_avCapture后，可以设置录屏所需要的参数。

    其中，录屏存文件时默认录制内录，麦克风可以动态开关，可以同时内外录制。

    同时，录屏存文件需要设置状态回调，感知录制状态。

    收起
    自动换行
    深色代码主题
    复制
    1. void SetConfig02(OH_AVScreenCaptureConfig &config, OH_RecorderInfo &recorderInfo)
    2. {
    3.     // 录屏时获取麦克风或者内录，内录参数必填，如果都设置了，内录和麦克风的参数设置需要一致。
    4.     OH_AudioCaptureInfo micCapInfo = {.audioSampleRate = 48000, .audioChannels = 2, .audioSource = OH_MIC};
    5. 

    6.     OH_AudioCaptureInfo innerCapInfo = {.audioSampleRate = 48000, .audioChannels = 2, .audioSource = OH_ALL_PLAYBACK};
    7.     // 录屏音频输出规格配置。audioBitrate保证输出文件的比特率为设置的预期比特率，和audioSampleRate无强关联。
    8.     // 为保证音频质量，此处音频比特率取值128000。如果录屏内容以语音为主，不包含音乐、游戏音效等，可以降低为96000或48000。
    9.     OH_AudioEncInfo audioEncInfo = {
    10.         .audioBitrate = 128000,
    11.         .audioCodecformat = OH_AAC_LC
    12.     };
    13. 

    14.     // 获取屏幕信息。
    15.     uint64_t displayId = 0;
    16.     NativeDisplayManager_ErrorCode ret = OH_NativeDisplayManager_GetDefaultDisplayId(&displayId);
    17. 

    18.     NativeDisplayManager_DisplayInfo* displayInfo = nullptr;
    19.     ret = OH_NativeDisplayManager_CreateDisplayById(displayId, &displayInfo);
    20.     if (ret != DISPLAY_MANAGER_OK || !displayInfo) {
    21.         return;
    22.     }
    23.     int32_t screenWidth = displayInfo->width;
    24.     int32_t screenHeight = displayInfo->height;
    25.     OH_NativeDisplayManager_DestroyDisplay(displayInfo);
    26.     displayInfo = nullptr;
    27.     OH_VideoCaptureInfo videoCapInfo = {
    28.         .videoFrameWidth = screenWidth,
    29.         .videoFrameHeight = screenHeight,
    30.         .videoSource = OH_VIDEO_SOURCE_SURFACE_RGBA
    31.     };
    32. 

    33.     OH_VideoEncInfo videoEncInfo = {
    34.         .videoCodec = OH_H264,
    35.         .videoBitrate = 2000000,
    36.         .videoFrameRate = 30
    37.     };
    38. 

    39.     OH_AudioInfo audioInfo = {
    40.         .micCapInfo = micCapInfo,
    41.         .innerCapInfo = innerCapInfo,
    42.         .audioEncInfo = audioEncInfo
    43.     };
    44. 

    45.     OH_VideoInfo videoInfo = {
    46.         .videoCapInfo = videoCapInfo,
    47.         .videoEncInfo = videoEncInfo
    48.     };
    49. 

    50.     config = {
    51.         .captureMode = OH_CAPTURE_HOME_SCREEN,
    52.         .dataType = OH_CAPTURE_FILE, // 录屏数据类型，文件。
    53.         .audioInfo = audioInfo,
    54.         .videoInfo = videoInfo,
    55.         .recorderInfo = recorderInfo // 录制文件信息。
    56.     };
    57.     // 设置状态回调函数、错误回调函数和录屏屏幕ID回调函数等。
    58.     SetCallbackFile(g_avCapture);
    59. }
    napi_init.cpp

  4. 调用OH_AVScreenCapture_StartScreenRecording()方法开始进行录屏。

    收起
    自动换行
    深色代码主题
    复制
    1. result = OH_AVScreenCapture_StartScreenRecording(g_avCapture);
    napi_init.cpp

  5. 调用OH_AVScreenCapture_StopScreenRecording()方法停止录制。

    收起
    自动换行
    深色代码主题
    复制
    1. result = OH_AVScreenCapture_StopScreenRecording(g_avCapture);
    napi_init.cpp

  6. 调用OH_AVScreenCapture_Release()方法销毁实例，释放资源。

    收起
    自动换行
    深色代码主题
    复制
    1. result = OH_AVScreenCapture_Release(g_avCapture);
    napi_init.cpp

完整示例

针对使用AVScreenCapture录屏存文件的完整示例代码可参考：

录屏常见问题
使用AVScreenCapture实现窗口级录屏(C/C++)
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明