Scripting
开始
文档
更新日志
开始
文档
更新日志
简体中文

录音

AudioRecorder 类允许您将音频数据录制到文件。它提供了开始、停止、暂停和管理音频录制的功能，并可配置音频质量、采样率、格式等。

功能

  • 从系统的活跃输入设备录制音频。
  • 可以录制指定时长，或在手动停止前一直录制。
  • 暂停并恢复录制。
  • 删除已录制的音频文件。

用法

设置 SharedAudioSession

在创建 AudioRecorder 实例之前，需要先设置 SharedAudioSession。因为音频会话与硬件相关，因此需要确保正确激活会话。

1await SharedAudioSession.setActive(true)
2await SharedAudioSession.setCategory(
3  "playAndRecord",
4  ["defaultToSpeaker"]
5)

创建 AudioRecorder 实例

使用 create 方法来创建一个音频录制器实例：

1async function createRecorder() {
2  try {
3    const filePath = Path.join(
4      FileManager.documentsDirectory,
5      "recording.m4a"
6    )
7    const recorder = await AudioRecorder.create(filePath, {
8      format: "MPEG4AAC",
9      sampleRate: 44100,
10      numberOfChannels: 2,
11      encoderAudioQuality: AVAudioQuality.high
12    })
13    return recorder
14  } catch (error) {
15    console.error("Failed to create recorder: ", error)
16  }
17}

录制音频

您可以使用 record() 方法开始录制：

1async function startRecording() {
2  const recorder = await createRecorder()
3  if (recorder) {
4    const success = recorder.record()
5    console.log("Recording started: ", success)
6  }
7}

也可以提供额外的选项来控制录制开始的时间及录制时长：

1function startSynchronizedRecording(recorderOne, recorderTwo) {
2  let timeOffset = recorderOne.deviceCurrentTime + 0.01
3  
4  // 使两个 recorder 的录制时间同步
5  recorderOne.record({ atTime: timeOffset })
6  recorderTwo.record({ atTime: timeOffset })
7}

暂停和停止录制

暂停录制：

1function pauseRecording(recorder) {
2  recorder.pause()
3  console.log("Recording paused.")
4}

停止录制：

1function stopRecording(recorder) {
2  recorder.stop()
3  console.log("Recording stopped.")
4}

删除录音文件

要删除已经录制好的文件：

1function deleteRecording(recorder) {
2  const success = recorder.deleteRecording()
3  console.log("Recording deleted: ", success)
4}

释放 Recorder

当不再需要使用录制器时，应调用 dispose() 来释放资源：

1function disposeRecorder(recorder) {
2  recorder.dispose()
3  console.log("Recorder disposed.")
4}

事件处理

可以使用 onFinish 和 onError 回调来处理录制完成和错误情况：

1async function setupRecorder() {
2  const recorder = await createRecorder()
3  if (recorder) {
4    recorder.onFinish = (success) => {
5      console.log("Recording finished successfully: ", success)
6    }
7
8    recorder.onError = (message) => {
9      console.error("Recording error: ", message)
10    }
11  }
12}

API 参考

AudioRecorder.create(filePath, settings?)

使用指定的设置创建一个 AudioRecorder 实例。

  • filePath (string): 要录制到的文件系统路径。
  • settings (可选对象): 录音的音频设置：
    • format (AudioFormat): 音频数据的格式，可选值包括 "LinearPCM", "MPEG4AAC", "AppleLossless", "AppleIMA4", "iLBC", "ULaw"。
    • sampleRate (number): 采样率，单位为赫兹 (范围 8000 到 192000)。
    • numberOfChannels (number): 声道数量 (1 到 64)。
    • encoderAudioQuality (AVAudioQuality): 音频编码质量 (从 AVAudioQuality.min 到 AVAudioQuality.max)。

返回值: 一个 Promise，解析后返回 AudioRecorder 实例。

AudioRecorder.isRecording

一个布尔值，用于指示录制器当前是否正在录音。

AudioRecorder.currentTime

从录音开始到当前的时间（单位为秒）。

AudioRecorder.deviceCurrentTime

主机音频设备的当前时间（单位为秒）。

AudioRecorder.record(options?)

开始录制音频。

  • options (可选对象):
    • atTime (number): 相对于 deviceCurrentTime，指定开始录制的时间。
    • duration (number): 录音时长（单位为秒）。

返回值: 一个布尔值，表示录制是否成功开始。

AudioRecorder.pause()

暂停当前录制。

AudioRecorder.stop()

停止录制并关闭音频文件。

AudioRecorder.deleteRecording()

删除已经录制的音频文件。

返回值: 一个布尔值，表示删除操作是否成功。

AudioRecorder.dispose()

释放录制器所使用的资源。

AudioRecorder.onFinish

录音完成后调用的回调函数。

  • success (boolean): 表示录制是否成功完成。

AudioRecorder.onError

在录制或编码出现错误时调用的回调函数。

  • message (string): 描述错误的字符串。

使用示例

1import { Path } from 'scripting'
2
3async function run() {
4
5  await SharedAudioSession.setActive(true)
6  await SharedAudioSession.setCategory(
7    "playAndRecord",
8    ["defaultToSpeaker"]
9  )
10
11  try {
12    const filePath = Path.join(
13      FileManager.documentsDirectory,
14      "recording.m4a"
15    )
16    const recorder = await AudioRecorder.create(filePath, {
17      format: "MPEG4AAC",
18      sampleRate: 48000,
19      numberOfChannels: 2,
20      encoderAudioQuality: AVAudioQuality.high
21    })
22
23    recorder.onFinish = (success) => console.log("Recording finished successfully: ", success)
24    recorder.onError = (message) => console.error("Recording error: ", message)
25
26    recorder.record()
27    setTimeout(() => {
28      recorder.stop()
29    }, 5000) // 5秒后停止录制
30  } catch (error) {
31    console.error("Error: ", String(error))
32  }
33}
34
35run()

使用 AudioRecorder 类，您可以在脚本中轻松管理音频录制操作，并灵活控制音频录制流程。

大纲