文档模板：v0.4.2

react-native-audio

本项目基于 react-native-audio 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-audio 版本所属关系如下：

简介

react-native-audio 是一个 React Native 音频录制扩展库，提供麦克风权限申请、录音参数配置、开始/暂停/恢复/停止录制，以及录制进度与完成回调等能力。鸿蒙侧基于系统 AVRecorder 实现，接口与上游社区库保持一致，import 包名不变。

下载安装

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-audio

yarn

yarn add @react-native-ohos/react-native-audio

Link

使用 AutoLink 的工程需要根据 Autolink 框架指导文档 配置。

如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "~0.72.140" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

"dependencies": {
    "@react-native-ohos/react-native-audio": "file:../../node_modules/@react-native-ohos/react-native-audio/harmony/audio.har"
  }

cd entry
ohpm install

+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

# RNOH_BEGIN: manual_package_linking_1
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-audio/src/main/cpp" ./audio)
# RNOH_END: manual_package_linking_1

# RNOH_BEGIN: manual_package_linking_2
+ target_link_libraries(rnoh_app PUBLIC rnoh_audio)
# RNOH_END: manual_package_linking_2

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
+ #include "AudioPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<RNOHGeneratedPackage>(ctx),
+       std::make_shared<AudioPackage>(ctx)
    };
}

  ...
+ import {AudioPackage} from '@react-native-ohos/react-native-audio/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
+   new AudioPackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮，或在命令行终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

1. RNOH: 0.72.140; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;

权限要求

录音功能需要在 HarmonyOS 工程 entry/src/main/module.json5 中声明麦克风权限：

"requestPermissions": [
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:permission_microphone",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

编译运行 API 要求

使用示例

下面的代码展示了这个库的基本使用场景：

import React, { useEffect } from 'react';
import { SafeAreaView, Text, Button, View } from 'react-native';
import { AudioRecorder, AudioUtils, AudioSource } from 'react-native-audio';

export default function App() {
  const initRecording = async () => {
    await AudioRecorder.requestAuthorization();
    await AudioRecorder.checkAuthorizationStatus();

    await AudioRecorder.prepareRecordingAtPath(
      `${AudioUtils.FilesDirectoryPath}/audio_demo.m4a`,
      {
        SampleRate: 44100,
        Channels: 2,
        AudioQuality: 'High',
        AudioEncoding: 'aac',
        AudioEncodingBitRate: 32000,
        AudioSource: AudioSource.MIC,
        OutputFormat: 'm4a',
        MeteringEnabled: false,
        IncludeBase64: false,
      }
    );

    AudioRecorder.onProgress = (data) => {
      console.log('currentTime:', data.currentTime);
    };

    AudioRecorder.onFinished = (data) => {
      console.log('finished:', data.audioFileURL, data.duration);
    };
  };

  useEffect(() => {
    initRecording();
  }, []);

  return (
    <SafeAreaView>
      <View style={{ flexDirection: 'row', gap: 8, padding: 16 }}>
        <Button title="start" onPress={() => AudioRecorder.startRecording()} />
        <Button title="pause" onPress={() => AudioRecorder.pauseRecording()} />
        <Button title="resume" onPress={() => AudioRecorder.resumeRecording()} />
        <Button title="stop" onPress={() => AudioRecorder.stopRecording()} />
      </View>
    </SafeAreaView>
  );
}

使用说明

录音流程

1. 调用 requestAuthorization 申请麦克风权限；
2. 调用 prepareRecordingAtPath(path, options) 初始化录音参数并订阅原生事件；
3. 设置 AudioRecorder.onProgress / AudioRecorder.onFinished 回调；
4. 调用 startRecording 开始录音，可 pauseRecording / resumeRecording；
5. 调用 stopRecording 停止录音；约 200ms 后会自动移除事件订阅并清空回调引用；
6. 开始新的录音会话前，需重新调用 prepareRecordingAtPath 并重新设置回调。

prepareRecordingAtPath 默认参数

JS 层默认值（与上游社区库对齐）如下，鸿蒙/Android 未显式传入 AudioEncoding 时会自动将 ima4 替换为 aac，并默认 AudioSource: 1（MIC）：

AudioUtils 路径（HarmonyOS）

鸿蒙平台提供以下目录路径，用于拼接录音文件保存位置：

AudioEncoding 格式支持

OutputFormat 格式支持

OutputFormat 为 Android 专用参数；iOS 通过文件扩展名与 AudioEncoding 决定输出格式。MP3 编码须配合 OutputFormat=mp3。

AudioSource 常量

电平计量（MeteringEnabled^4.2.5+）

当 MeteringEnabled: true 时，onProgress 回调除 currentTime 外还会包含 currentMetering 与 currentPeakMetering 字段。

接口说明

事件回调

注意：stopRecording 会在约 200ms 延迟后自动移除原生事件订阅并清除 onProgress / onFinished 回调引用。开始新的录音会话前，必须重新调用 prepareRecordingAtPath 并重新设置回调。

API

prepareRecordingAtPath 参数（RecordingOptions）

AudioUtils 属性

库导出的目录路径常量（均为 string 类型），用于拼接录音文件保存位置；按平台取值不同：

鸿蒙平台取值来自 getAllPath() 返回的应用沙箱目录，在模块加载时生成。

遗留问题

• MeasurementMode 为 iOS 专用参数，HarmonyOS 侧忽略
• ima4、vorbis、webm 等格式在 HarmonyOS 侧不支持，请参见上方格式支持表
• AudioSource 中 VOICE_UPLINK、VOICE_DOWNLINK、VOICE_CALL、REMOTE_SUBMIX、UNPROCESSED 在 HarmonyOS 侧不支持

其他

• 完整 API 演示可参考工程内 example/src/AudioDemo.tsx
• 英文文档见 README_EN.md

目录结构

/rntpc_react-native-audio           # 项目根目录
├── harmony                         # 鸿蒙适配代码
│   ├── audio.har                   # HAR 包（npm 发布产物）
│   └── audio                       # 鸿蒙适配核心模块
│       ├── index.ets
│       ├── oh-package.json5
│       └── src/main
│           ├── cpp                 # C++ TurboModule 与 codegen 产物
│           │   ├── AudioPackage.h
│           │   ├── CMakeLists.txt
│           │   └── generated/
│           └── ets
│               ├── AudioPackage.ets
│               ├── AudioModule.ts
│               ├── AudioRecordManager.ts
│               ├── AudioApiCompat.ts
│               ├── AudioType.ts
│               ├── StopWatch.ts
│               └── generated/      # codegen 产物
├── example                         # 示例工程
├── index.js                        # JS 入口
├── NativeAudio.ts                  # TurboModule 类型定义
├── package.json
├── README.md                       # 中文文档
├── README_EN.md                    # 英文文档
└── LICENSE

贡献代码

使用过程中发现任何问题都可以提交 Issue，也非常欢迎提交 PR。

开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。