AudioBufferQueueSourceNode

Mobile only

The AudioBufferQueueSourceNode is an AudioScheduledSourceNode which represents a player that consists of many short buffers.

Constructor

constructor(context: BaseAudioContext, options?: AudioBufferQueueSourceOptions)

AudioBufferQueueSourceOptions

Parameter	Type	Default
detune Optional	number	0	Initial value for detune.
playbackRate Optional	number	1.0	Initial value for playbackRate.
pitchCorrection Optional	boolean	false	Enables the pitch correction algorithm when changing playbackRate.

info

You can also create an AudioBufferQueueSourceNode via BaseAudioContext.createBufferQueueSource(), which uses default values.

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. Use getLatency() to obtain the compensation value for the current playbackRate.

Example

import React, { useRef } from 'react';
import {
  AudioContext,
  AudioBufferQueueSourceNode,
} from 'react-native-audio-api';

function App() {
    const audioContextRef = useRef<AudioContext | null>(null);
    if (!audioContextRef.current) {
        audioContextRef.current = new AudioContext();
    }
    const audioBufferQueue = audioContextRef.current.createBufferQueueSource();
    const buffer1 = ...; // Load your audio buffer here
    const buffer2 = ...; // Load another audio buffer if needed
    audioBufferQueue.enqueueBuffer(buffer1);
    audioBufferQueue.enqueueBuffer(buffer2);
    audioBufferQueue.connect(audioContextRef.current.destination);
    audioBufferQueue.start(audioContextRef.current.currentTime);
}

Properties

Inherits all properties from AudioScheduledSourceNode.

AudioNodeproperties

Name	Type	Description
detune	AudioParam	k-rate AudioParam representing detuning of oscillation in cents.
playbackRate	AudioParam	k-rate AudioParam defining speed factor at which the audio will be played.

Methods

It inherits all methods from AudioScheduledSourceNode.

getLatency

Returns an estimated scheduling compensation for the WSOLA pitch-correction path, in seconds. Use this value when calling start() — do not hardcode a fixed delay.

Condition	Returned value
pitchCorrection: false	0.0
pitchCorrection: true	0.01 + 0.02 × playbackRate (seconds)

At playbackRate = 1.0, that is 0.03s. At playbackRate = 1.5, that is 0.04s. Read playbackRate and call getLatency() immediately before scheduling — the estimate scales with the current rate.

Returns 0.0 when pitch correction is disabled.

Returns: number.

Example usage

const source = audioContext.createBufferQueueSource({ pitchCorrection: true });
source.connect(audioContext.destination);

const latency = source.getLatency();

// Schedule playback slightly earlier to compensate for latency
const startTime = audioContext.currentTime + 1.0; // play in 1 second
source.start(startTime - latency);

enqueueBuffer

Adds another buffer to queue. Returns bufferId that can be used to identify the buffer in onBufferEnded event.

Parameter	Type	Description
buffer	AudioBuffer	Buffer with next data.

Returns string.

dequeueBuffer

Removes a buffer from the queue. Note that onBufferEnded event will not be fired for the removed buffers.

Parameter	Type	Description
bufferId	string	ID of the buffer to remove from the queue. It should be valid id provided by enqueueBuffer method.

Returns undefined.

clearBuffers

Removes all buffers from the queue. Note that onBufferEnded event will not be fired for buffers that were removed.

Returns undefined.

start

Overridden

#start

Schedules the AudioBufferQueueSourceNode to start playback of enqueued AudioBuffers, or starts to play immediately.

Parameter	Type	Description
when Optional	number	The time, in seconds, at which playback is scheduled to start. If when is less than AudioContext.currentTime or set to 0.0, the node starts playing immediately. Default: 0.0.
offset Optional	number	The position, in seconds, within the first enqueued audio buffer where playback begins. The default value is 0.0, which starts playback from the beginning of the first enqueued buffer. If the offset exceeds the buffer’s duration, it’s automatically clamped to the valid range.

Errors:

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

Returns undefined.

pause

Stops audio immediately. Unlike stop(), which fully stops playback and clears the queued buffers, pause() halts the audio while keeping the current playback position, allowing you to resume from the same point later.

Errors:

Error type	Description
InvalidStateError	If the node has not been started yet, has already been stopped, or is already paused.

Returns undefined.

resume

Resumes audio playback with a specified delay. If no time is given, it resumes immediately.

Parameter	Type	Description
when Optional	number	The time, in seconds, at which playback is scheduled to resume. If when is less than AudioContext.currentTime or set to 0.0, the node resumes playing immediately. Default: 0.0.

Errors:

Error type	Description
RangeError	when is negative number.
InvalidStateError	If the node has not been started yet, has already been stopped, or is not currently paused.

Returns undefined.

Events

It inherits all events from AudioScheduledSourceNode.

onPositionChanged

Mobile only

Allows to set (or remove) a callback that will be fired after processing certain part of an audio. Frequency is defined by onPositionChangedInterval. By setting this callback you can achieve pause functionality. You can remove the callback by passing null.

onPositionChangedInterval

Mobile only

Allows to set frequency for onPositionChanged event. Value that can be set is around 1000/x Hz.

import { AudioContext, AudioBufferQueueSourceNode } from 'react-native-audio-api';

function App() {
    const ctx = new AudioContext();
    const sourceNode = ctx.createBufferQueueSource();
    let offset = 0;

    sourceNode.onPositionChanged = (event) => { //setting callback
        this.offset = event.value;
    };

    sourceNode.onPositionChangedInterval = 100; //setting frequency to ~10Hz

    sourceNode.start();
}

onBufferEnded

Sets (or removes) a callback that will be fired when a specific buffer has ended with payload of type OnBufferEndEventType

You can remove the callback by passing null.

audioBufferQueueSourceNode.onBufferEnded = (event) => { //setting callback
  console.log(`buffer with id {event.bufferId} ended`);

  if (event.isLastBufferInQueue) {
    console.log('That was the last buffer in the queue');
  }
};

Remarks

detune

• Default value is 0.0.
• Nominal range is -∞ to ∞.
• For example value of 100 detune the source up by one semitone, whereas -1200 down by one octave.

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 pitchCorrection it is clamped to range -4 to 4 and uses the WSOLA pitch-correction algorithm when the rate is not 1.0.

OnBufferEndEventType

Type definitions

interface OnBufferEndEventType {
  bufferId: string; // the ID of the buffer that has ended
  isLastBufferInQueue: boolean; // a boolean indicating whether it was the last buffer in the queue
}