Skip to content

README.md

Latest commit

 

History

History
150 lines (101 loc) · 3.49 KB

README.md

File metadata and controls

150 lines (101 loc) · 3.49 KB

@nativescript/audio-context

Web Audio API style audio graph support for NativeScript (iOS and Android).

This package provides a native-backed AudioContext/OfflineAudioContext with common Web Audio nodes so you can keep a familiar Web Audio programming model in NativeScript apps.

Installation

ns plugin add @nativescript/audio-context

or

npm install @nativescript/audio-context

Quick Start

import { AudioContext } from '@nativescript/audio-context';

const ctx = new AudioContext({ latencyHint: 'interactive' });

const osc = ctx.createOscillator({ type: 'sine', frequency: 440 });
const gain = ctx.createGain({ gain: 0.12 });

osc.connect(gain);
gain.connect(ctx.destination);

await ctx.resume();
osc.start();

setTimeout(async () => {
	osc.stop();
	await ctx.close();
}, 1200);

Decode And Play Audio

decodeAudioData supports:

  • App-relative file paths (~/...)
  • file:// paths
  • Other string sources handled by native decoders (for example URL/data string inputs)
  • ArrayBuffer / ArrayBufferView
import { AudioContext } from '@nativescript/audio-context';

const ctx = new AudioContext({ latencyHint: 'playback' });
await ctx.resume();

const buffer = await ctx.decodeAudioData('~/assets/file-assets/audio/sine441stereo.mp3');

const source = ctx.createBufferSource();
source.buffer = buffer;
source.connect(ctx.destination);
source.start();

source.onended = async () => {
	await ctx.close();
};

Media Element Source

Use createMediaElementSource to route a media element/player through the audio graph.

import { AudioContext } from '@nativescript/audio-context';
import { Audio } from '@nativescript/canvas-media';

const ctx = new AudioContext();
await ctx.resume();

const media = new Audio();
media.src = '~/assets/file-assets/audio/gs-16b-1c-44100hz.wav';
media.loop = true;

const mediaSource = ctx.createMediaElementSource(media);
const panner = ctx.createPanner({ panningModel: 'equalpower' });

mediaSource.connect(panner);
panner.connect(ctx.destination);

await media.play();

// Cleanup when done.
media.pause();
await ctx.close();

Offline Rendering

import { OfflineAudioContext } from '@nativescript/audio-context';

const sampleRate = 44100;
const seconds = 2;
const off = new OfflineAudioContext(1, sampleRate * seconds, sampleRate);

const osc = off.createOscillator({ type: 'sine', frequency: 440 });
const gain = off.createGain({ gain: 0.2 });

osc.connect(gain);
gain.connect(off.destination);
osc.start();

const rendered = await off.startRendering();
console.log(rendered.length, rendered.sampleRate, rendered.numberOfChannels);

Supported API Surface

Main contexts:

  • AudioContext
  • OfflineAudioContext

Core graph primitives:

  • AudioNode, AudioParam, AudioBuffer
  • AudioBufferSourceNode, MediaElementAudioSourceNode
  • GainNode, BiquadFilterNode, PannerNode, StereoPannerNode, DelayNode
  • ConstantSourceNode, OscillatorNode
  • AnalyserNode, WaveShaperNode, IIRFilterNode, ConvolverNode, PeriodicWave

Context lifecycle and routing:

  • resume(), suspend(), close()
  • state, onstatechange
  • sinkId, setSinkId(deviceId)

Optional: Global Polyfill Integration

If you also use @nativescript/canvas-polyfill, it can register Web Audio globals such as:

  • AudioContext
  • webkitAudioContext
  • OfflineAudioContext
  • node constructors (GainNode, PannerNode, etc.)

This is useful when running libraries that expect browser-like globals.

License

Apache License Version 2.0