Skip to content

audio-buffer-source-node.mdx

Latest commit

 

History

History
137 lines (97 loc) · 6.38 KB

audio-buffer-source-node.mdx

File metadata and controls

137 lines (97 loc) · 6.38 KB
sidebar_position 4

import AudioNodePropsTable from "@site/src/components/AudioNodePropsTable" import { Optional, Overridden } from '@site/src/components/Badges';

import InteractivePlayground from '@site/src/components/InteractivePlayground'; import { useAudioBufferSourcePlayground } from '@site/src/components/InteractivePlayground/AudioBufferSourceExample/useAudioBufferSourcePlayground'; import { useGainAdsrPlayground } from '@site/src/components/InteractivePlayground/GainAdsrExample/useGainAdsrPlayground';

AudioBufferSourceNode

The AudioBufferSourceNode is an AudioBufferBaseSourceNode which represents audio source with in-memory audio data, stored in AudioBuffer. You can use it for audio playback, including standard pause and resume functionalities.

An AudioBufferSourceNode can be started only once, so if you want to play the same sound again you have to create a new one. However, this node is very inexpensive to create, and what is crucial you can reuse same AudioBuffer.

Constructor

BaseAudioContext.createBufferSource(options: AudioBufferBaseSourceNodeOptions)

interface AudioBufferBaseSourceNodeOptions {
  pitchCorrection: boolean // specifies if pitch correction algorithm has to be available
}

:::caution The pitch correction algorithm introduces processing latency. As a result, when scheduling precise playback times, you should start input samples slightly ahead of the intended playback time. For more details, see getLatency().

If you plan to play multiple buffers one after another, consider using AudioBufferQueueSourceNode :::

Example

import React, { useEffect, useRef, FC } from 'react';
import {
  AudioContext,
  AudioBufferSourceNode,
} from 'react-native-audio-api';

function App() {
  const audioContextRef = useRef<AudioContext | null>(null);
  if (!audioContextRef.current) {
    audioContextRef.current = new AudioContext();
  }
  const audioBufferSource = audioContextRef.current.createBufferSource();
  const buffer = ...; // Load your audio buffer here
  audioBufferSource.buffer = buffer;
  audioBufferSource.connect(audioContextRef.current.destination);
  audioBufferSource.start(audioContextRef.current.currentTime);
}

Properties

It inherits all properties from AudioBufferBaseSourceNode.

Name Type Description
buffer AudioBuffer Associated AudioBuffer.
loop boolean Boolean indicating if audio data must be replayed after when end of the associated AudioBuffer is reached.
loopSkip boolean Boolean indicating if upon setting up loopStart we want to skip immediately to the loop start.
loopStart number Float value indicating the time, in seconds, at which playback of the audio must begin, if loop is true.
loopEnd number Float value indicating the time, in seconds, at which playback of the audio must end and loop back to loopStart, if loop is true.

Methods

It inherits all methods from AudioBufferBaseSourceNode.

start {#start}

Schedules the AudioBufferSourceNode to start playback of audio data contained in the associated AudioBuffer, or starts to play immediately.

Parameter Type Description
when number The time, in seconds, at which playback is scheduled to start. If when is less than AudioContext.currentTime or set to 0, the node starts playing immediately.
Default: 0.
offset number The position, in seconds, within the audio buffer where playback begins.
The default value is 0, which starts playback from the beginning of the buffer. If the offset exceeds the buffer’s duration (or the defined loopEnd value), it’s automatically clamped to the valid range.
Offsets are calculated using the buffer’s natural sample rate rather than the current playback rate — so even if the sound is played at double speed, halfway through a 10-second buffer is still 5 seconds.
duration number The playback duration, in seconds. If not provided, playback continues until the sound ends naturally or is manually stopped with stop() method.
Equivalent to calling start(when, offset) followed by stop(when + duration).

Errors:

Error type Description
RangeError when is negative number.
RangeError offset is negative number.
RangeError duration is negative number.
InvalidStateError If node has already been started once.

Returns undefined.

Events

onLoopEnded

Sets (or remove) callback that will be fired when buffer source node reached the end of the loop and is looping back to loopStart. You can remove callback either by passing null or calling remove on the returned subscription.

const subscription = audioBufferSourceNode.onLoopEnded = () => { // setting the callback
  console.log("loop ended");
};

subscription.remove(); // removal of the subscription

Remarks

buffer

  • If is null, it outputs a single channel of silence (all samples are equal to 0).

loop

  • Default value is false.

loopStart

  • Default value is 0.

loopEnd

  • Default value is buffer.duration.

playbackRate

  • Default value is 1.0.
  • Nominal range is -∞ to ∞.
  • For example value of 1.0 plays audio at normal speed, whereas value of 2.0 plays audio twice as fast as normal speed.
  • When created with createBufferSource(true) it is clamped to range 0 to 3 and uses pitch correction algorithm.