AudioPlayer

ug-js-sdk

---

ug-js-sdk / AudioPlayer

Class: AudioPlayer

Defined in: playback-manager/audio-player/AudioPlayer.ts:62

Audio player for streaming MP3 playback in the browser.

Handles real-time audio streaming by decoding MP3 frames and scheduling playback through the Web Audio API. Used internally by the SDK for text-to-speech audio playback.

Main Methods for Users:

• initialize - Initialize the audio context (call first, requires user gesture)
• play - Start audio playback
• pause - Pause playback
• resume - Resume paused playback
• stop - Stop playback and clear queue
• dispose - Clean up resources when done

Events emitted:

• AudioPlayerEvents.Ready - Audio is ready to play
• AudioPlayerEvents.Playing - Playback started
• AudioPlayerEvents.Paused - Playback paused
• AudioPlayerEvents.Stopped - Playback stopped
• AudioPlayerEvents.Finished - All audio finished playing
• AudioPlayerEvents.AboutToComplete - Audio is about to finish (for pre-loading)

Example

const player = new AudioPlayer();

// Initialize (requires user gesture like button click)
await player.initialize();

// Listen for events
player.on(AudioPlayerEvents.Ready, () => player.play());
player.on(AudioPlayerEvents.Finished, () => console.log('Done'));

// Enqueue audio data (base64 MP3 chunks)
player.enqueue(base64AudioChunk);
player.markComplete(); // Signal no more audio coming

// Control playback
await player.pause();
await player.resume();
await player.stop();

// Clean up when done
player.dispose();

Fires

AudioPlayerEvents.Ready - When audio is queued and ready to play

Fires

AudioPlayerEvents.Playing - When playback starts or resumes

Fires

AudioPlayerEvents.Paused - When playback is paused

Fires

AudioPlayerEvents.Stopped - When playback is stopped

Fires

AudioPlayerEvents.Finished - When all audio has finished playing

Fires

AudioPlayerEvents.AboutToComplete - When audio is about to finish

Extends

• EventEmitter

Implements

• IAudioPlayer

Constructors

Constructor

new AudioPlayer(): AudioPlayer

Defined in: playback-manager/audio-player/AudioPlayer.ts:96

Returns

AudioPlayer

Overrides

EventEmitter.constructor

Properties

logger

protected logger: ILogger

Defined in: core/EventEmitter.ts:5

Implementation of

IAudioPlayer.logger

Inherited from

EventEmitter.logger

Methods

on()

on<K>(event, callback): void

Defined in: core/EventEmitter.ts:11

Type Parameters

K

K extends string

Parameters

event

K

callback

any

Returns

void

Implementation of

IAudioPlayer.on

Inherited from

EventEmitter.on

---

off()

off<K>(event, callback): void

Defined in: core/EventEmitter.ts:18

Type Parameters

K

K extends string

Parameters

event

K

callback

any

Returns

void

Implementation of

IAudioPlayer.off

Inherited from

EventEmitter.off

---

emit()

emit<K>(event, data?): Promise<void>

Defined in: core/EventEmitter.ts:28

Type Parameters

K

K extends string

Parameters

event

K

data?

unknown

Returns

Promise<void>

Implementation of

IAudioPlayer.emit

Inherited from

EventEmitter.emit

---

removeAllListeners()

removeAllListeners(event?): void

Defined in: core/EventEmitter.ts:73

Parameters

event?

string

Returns

void

Implementation of

IAudioPlayer.removeAllListeners

Inherited from

EventEmitter.removeAllListeners

---

initialize()

initialize(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:131

Initialize the audio player and prepare for playback.

Must be called before any other methods. Should be called in response to a user gesture (click, tap) to ensure the AudioContext can start.

Returns

Promise<void>

Example

// In a button click handler
button.onclick = async () => {
  await player.initialize();
  // Now ready to receive and play audio
};

Implementation of

IAudioPlayer.initialize

---

reset()

reset(): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:189

Returns

void

Implementation of

IAudioPlayer.reset

---

enqueue()

enqueue(audioData): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:209

Enqueue audio data for playback.

Add base64-encoded MP3 audio chunks to the playback queue. Call markComplete when all audio has been enqueued.

Parameters

audioData

string

Base64-encoded MP3 audio chunk

Returns

void

Example

// Enqueue streaming audio chunks
player.enqueue(chunk1);
player.enqueue(chunk2);
player.markComplete(); // Signal end of audio

Implementation of

IAudioPlayer.enqueue

---

markComplete()

markComplete(): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:237

Signal that all audio has been enqueued.

Call this after enqueuing all audio chunks to indicate that no more audio will be added. This triggers the Finished event when playback completes.

Returns

void

Example

player.enqueue(chunk1);
player.enqueue(chunk2);
player.markComplete(); // No more audio coming

Implementation of

IAudioPlayer.markComplete

---

play()

play(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:483

Start audio playback.

Begins playing audio from the queue. Emits Playing event on success. Does nothing if already playing or queue is empty.

Returns

Promise<void>

Fires

AudioPlayerEvents.Playing - When playback starts

Example

player.on(AudioPlayerEvents.Ready, async () => {
  await player.play();
});

Implementation of

IAudioPlayer.play

---

pause()

pause(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:588

Pause audio playback.

Suspends the audio context, pausing playback at the current position. Use resume to continue playback.

Returns

Promise<void>

Fires

AudioPlayerEvents.Paused - When playback is paused

Example

await player.pause();
// Later...
await player.resume();

Implementation of

IAudioPlayer.pause

---

resume()

resume(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:611

Resume paused audio playback.

Continues playback from where it was paused.

Returns

Promise<void>

Fires

AudioPlayerEvents.Playing - When playback resumes

Example

await player.pause();
// Later...
await player.resume();

Implementation of

IAudioPlayer.resume

---

stop()

stop(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:637

Stop audio playback and clear the queue.

Immediately stops all playback and clears any queued audio. To play again, you'll need to enqueue new audio.

Returns

Promise<void>

Fires

AudioPlayerEvents.Stopped - When playback is stopped

Example

// Stop playback immediately
await player.stop();

Implementation of

IAudioPlayer.stop

---

getCurrentTime()

getCurrentTime(): number

Defined in: playback-manager/audio-player/AudioPlayer.ts:643

Returns

number

Implementation of

IAudioPlayer.getCurrentTime

---

getQueueLength()

getQueueLength(): number

Defined in: playback-manager/audio-player/AudioPlayer.ts:650

Returns

number

Implementation of

IAudioPlayer.getQueueLength

---

getRemainingAudioSeconds()

getRemainingAudioSeconds(): number

Defined in: playback-manager/audio-player/AudioPlayer.ts:658

Get the total remaining audio playback time in seconds. Includes both queued buffers and currently scheduled (playing) audio.

Returns

number

Implementation of

IAudioPlayer.getRemainingAudioSeconds

---

flush()

flush(): Promise<void>

Defined in: playback-manager/audio-player/AudioPlayer.ts:740

Returns

Promise<void>

---

resetAboutToComplete()

resetAboutToComplete(): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:775

Returns

void

Implementation of

IAudioPlayer.resetAboutToComplete

---

getFrameStats()

getFrameStats(): object

Defined in: playback-manager/audio-player/AudioPlayer.ts:782

Get frame statistics for debugging

Returns

object

totalFramesExtracted

totalFramesExtracted: number

totalFramesDecoded

totalFramesDecoded: number

totalFramesFailed

totalFramesFailed: number

extractorRemainingBufferSize

extractorRemainingBufferSize: number

---

dispose()

dispose(): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:800

Dispose of all resources and clean up. Should be called when the audio player is no longer needed.

Returns

void

Implementation of

IAudioPlayer.dispose

---

destroy()

destroy(): void

Defined in: playback-manager/audio-player/AudioPlayer.ts:855

Destroy the audio player and clean up resources

Returns

void

Deprecated

Use dispose() instead