visualeraudio

Capacitor 7 audio player with HLS playback and real-time visualization frames.

Platform support

| Platform | Playback | audioFrame analysis | | --- | --- | --- | | Android | HLS and regular audio | Yes | | iOS 14+ | HLS and regular audio | Regular file-based audio | | iOS 27+ | HLS and regular audio | HLS and regular audio (except FairPlay-protected HLS) | | Web | Browser-supported audio/HLS | Yes, when the stream permits CORS |

Apple only makes the decoded HLS mix available to audio processing taps starting with iOS 27. On iOS 14–26, HLS playback works normally but audioFrame is not emitted for HLS streams. The plugin never generates synthetic visualization data.

Install

npm install visualeraudio
npx cap sync

Usage

import { VisualerAudio } from 'visualeraudio';

const frameListener = await VisualerAudio.addListener('audioFrame', frame => {
  console.log(frame.bins, frame.timestamp);
});

await VisualerAudio.start({
  url: 'https://example.com/live/stream.m3u8',
  bins: 32,
});

await VisualerAudio.stop();
await frameListener.remove();

iOS background playback

Playback uses AVAudioSession.Category.playback. To keep it running after the app goes to the background, enable Background Modes → Audio, AirPlay, and Picture in Picture for the app target in Xcode. This adds audio to the app's UIBackgroundModes; a library cannot enable that entitlement for the host app.

API

• start(...)
• stop()
• addListener('audioFrame', ...)
• removeAllListeners()
• Interfaces

start(...)

start(options: StartOptions) => Promise<void>

Starts playback, replacing any item that is already playing.

| Param | Type | | ------------- | ----------------------------------------------------- | | options | StartOptions |

stop()

stop() => Promise<void>

Stops playback and releases the native player.

addListener('audioFrame', ...)

addListener(eventName: 'audioFrame', listenerFunc: (frame: AudioFrame) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | --------------------------------------------------------------------- | | eventName | 'audioFrame' | | listenerFunc | (frame: AudioFrame) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Interfaces

StartOptions

| Prop | Type | Description | | ---------- | ------------------- | --------------------------------------------------------------------- | | url | string | HTTP(S) URL of the audio stream. HLS (.m3u8) is supported natively. | | bins | number | Number of RMS values emitted in each audio frame. Defaults to 32. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

AudioFrame

| Prop | Type | Description | | --------------- | --------------------- | -------------------------------------- | | bins | number[] | Normalized RMS values between 0 and 1. | | timestamp | number | Unix timestamp in milliseconds. |