rntpc_react-native-sound:基于 react-native-sound 的 OpenHarmony 适配版,用于播放音频文件

基于 react-native-sound 的 OpenHarmony 适配版,用于播放音频文件

分支5Tags3

文档模板:v0.4.2

react-native-sound

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

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

三方库名称 三方库版本(npm地址) 发布信息 支持RN版本 Autolink 编译API版本 社区基线版本 源码地址
@react-native-ohos/react-native-sound ~ 0.13.0 Gitcode Releases 0.82.* / 0.84.* 是 API12+ 0.13.0 master
@react-native-ohos/react-native-sound ~ 0.12.0 Gitcode Releases 0.77.* 否 API12+ 0.11.2 br_rnoh0.77
@react-native-ohos/react-native-sound ~ 0.11.3 Gitcode Releases 0.72.* 是 API12+ 0.11.2 br_rnoh0.72

简介

React Native 音频播放模块。
基于 AVPlayer 在 HarmonyOS 上实现音频播放能力,支持播放、暂停、停止、音量、倍速、循环等常用控制接口。

下载安装

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

npm

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

yarn

yarn add @react-native-ohos/react-native-sound
是否支持autolink RN框架版本
~ 0.13.0 Yes 0.82/0.84

使用AutoLink的工程需要根据该文档配置,Autolink框架指导文档:https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

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

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK,需要在工程根目录的 oh-package.json5 添加 overrides 字段,指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号,也可以是一个模糊版本,还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

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

2. 引入原生端代码

目前有两种方法:

  • 通过 har 包引入;
  • 直接链接源码。

方法一:通过 har 包引入(推荐)

har 包位于三方库安装路径的 `harmony` 文件夹下。

打开 entry/oh-package.json5,添加以下依赖

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

点击右上角的 sync 按钮

或者在命令行终端执行:

cd entry
ohpm install

方法二:直接链接源码

如需使用直接链接源码,请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md)

3. 配置 CMakeLists 和引入 SoundPackage

打开 entry/src/main/cpp/CMakeLists.txt,添加:

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

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

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_sound)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp,添加:

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "SoundPackage.h"

using namespace rnoh;

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

4. 在 ArkTs 侧引入 SoundPackage

打开 entry/src/main/ets/RNPackagesFactory.ts,添加:

  ...
+ import { SoundPackage } from '@react-native-ohos/react-native-sound/ts';

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

运行

点击右上角的 sync 按钮

或者在命令行终端执行:

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

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

  1. RNOH: 0.82.7; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112 SP12;
  2. RNOH: 0.84.2; SDK: HarmonyOS 6.1.0 Release SDK; IDE: DevEco Studio 6.1.0.830; ROM: 6.0.0.130;

权限要求

  • 如果使用网络 URL 播放音频,应用需要申请网络权限

    在entry/src/main/module.json5中添加

requestPermissions: [
  {
    name: "ohos.permission.INTERNET",
  },
],

使用示例

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

使用时 import 的库名不变。

import React from "react";
import { Button, View } from "react-native";
import Sound from "react-native-sound";

let sound: Sound;

const App = () => {
  const onPlay = () => {
    sound?.release();
    sound = new Sound(
      "https://music.163.com/song/media/outer/url?id=447925558.mp3",
      "",
      (error) => {
        if (error) {
          return;
        }
        sound.play();
      }
    );
  };

  return (
    <View style={{ flex: 1, justifyContent: "center" }}>
      <Button title="播放" onPress={onPlay} />
    </View>
  );
};

export default App;

使用说明

播放控制

import Sound from "react-native-sound";

const sound = new Sound("whoosh.mp3", "", (error) => {
  if (error) {
    return;
  }
  // 播放
  sound.play((success) => {
    // 播放完成回调
  });
  // 暂停
  sound.pause();
  // 停止
  sound.stop();
  // 重置
  sound.reset();
  // 释放资源
  sound.release();
});

音量与倍速

sound.setVolume(0.5);
sound.getVolume();

sound.setSpeed(1.5);
sound.getSpeed();

循环与进度

sound.setNumberOfLoops(-1); // 循环播放
sound.getNumberOfLoops();

sound.setCurrentTime(3); // 跳转到第 3 秒
sound.getCurrentTime((seconds, isPlaying) => {
  // 当前进度(秒)
});

接口说明

"Platform"列表示该属性在原三方库上支持的平台。

"OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。

静态方法

名称 类型 参数类型 返回值 必填 平台 OpenHarmony平台支持 描述
setActive function boolean / No iOS no 设置设备激活状态
setCategory function string, boolean? / No iOS、Android yes 设置 AVAudioSession 类别
enable function boolean / No iOS no 启用或禁用音频播放
enableInSilenceMode function boolean / No iOS no 是否在静音模式下启用播放
setMode function string / No iOS no 设置会话模式

API

名称 类型 参数类型 返回值 必填 平台 OpenHarmony平台支持 描述
play function callback? Sound No iOS、Android yes 开始播放音频
pause function callback? Sound No iOS、Android yes 暂停音频播放
stop function callback? Sound No iOS、Android yes 停止播放音频
reset function / Sound No Android yes 重置音频状态
release function / Sound No iOS、Android yes 释放音频资源
getVolume function / number No iOS、Android yes 获取音频音量
setVolume function number Sound No iOS、Android yes 设置相对音频音量
getCurrentTime function callback / No iOS、Android yes 获取当前播放时间点
setCurrentTime function number Sound No iOS、Android yes 设置播放时间点
getSpeed function / number No iOS、Android yes 获取播放速度
setSpeed function number Sound No iOS、Android yes 设置播放速度
getFilename function / string No iOS、Android yes 获取音频文件名
getDuration function / number No iOS、Android yes 获取音频时长
getNumberOfLoops function / number No iOS、Android yes 获取是否循环播放
setNumberOfLoops function number Sound No iOS、Android yes 设置是否循环播放
isPlaying function / boolean No iOS、Android yes 音频是否正在播放
isLoaded function / boolean No iOS、Android yes 是否加载完成
getPitch function / number No Android no 获取音调
setPitch function number / No Android no 设置音调
getPan function / number No iOS、Android no 获取左右声道平衡
setPan function number Sound No iOS、Android no 设置左右声道平衡
getSystemVolume function callback / No iOS、Android no 获取系统音量
setSystemVolume function number / No iOS、Android no 设置系统音量
getNumberOfChannels function / number No iOS、Android no 获取声道数
setSpeakerphoneOn function boolean / No Android no 设置扬声器

遗留问题

  • 原库部分接口在 HarmonyOS 中没有对应属性及接口处理相关逻辑,问题: issue#21

其他

无

目录结构

/rntpc_react-native-sound  # 项目根目录
├── harmony                # 鸿蒙适配代码
│    └─ sound.har          # har包
│    └─ sound              # 鸿蒙适配核心代码
│          └─ index.ets    # 鸿蒙适配代码入口
│          └─ src/main/ets
│              └─ SoundTurboModule.ts   # TurboModule 实现
│              └─ AVPlayerController.ts # 基于 AVPlayer 的播放控制
│              └─ SoundPackage.ets      # Package 注册
├── src                    # RN代码
│    └─ index.ts           # 入口文件
│    └─ NativeSound.ts     # TurboModule Spec
│    └─ index.d.ts         # 类型定义
├── example                # 示例工程
├── README.md              # 中文安装使用方法
├── README_en.md           # 英文安装使用方法

贡献代码

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

开源协议

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

项目介绍

基于 react-native-sound 的 OpenHarmony 适配版,用于播放音频文件

定制我的领域