agrathwohl / opus-buffer-player

opus-buffer-player

A feed decoding class. Converts new opus audio messages into AudioBuffer for immediate playback.

Run the example.mjs to see it work.

The class expects the opus to be mono @ 48kHz.

Getting Started

After doing npm install, use this npm script to build the module and the web worker:

npm run build-all

Move the outputs feeddecoder.js and decodeworker.js to test.

Then, run this script to launch the test server:

npm run serve

Generating bundles

Create distributions of these modules by running:

npm run dist

Implementation Guide

This repo provides a FeedDecoder class and a DecodeWorker Web Worker.

Read on to learn how to integrate the Web Worker and the class into your app.

DecodeWorker Web Worker

First we need to instantiate the Web Worker. This should happen as soon as the audio messages feed loads. This is so that we can begin decoding opus audio files provided by the feed right away.

To get the worker running, do the following immediately after the page loads:

const decodeWorker = new Worker('decodeworker.js')

When the feed receives a new opus audio message URL, send it to the decode worker:

decodeWorker.postMessage({url})

The web worker will send a new message containing the decoded audio data once decoding is done.

FeedDecoder Class

Before we can do anything with the decoded audio returned by our Web Worker, we need to also instantiate a class instance of FeedDecoder. This class should also be loaded immediately after page load.

Instantiation

Setup the class this way:

import FeedDecoder from 'feeddecoder'
const decoder = new FeedDecoder({feed: 'feedId'})
// or in vanilla JS...
// const FD = FeedDecoder.default
// const decoder = new FD({feed: 'feedId'})

Play audio from the DecodeWorker

Listen on the web worker to send new audio to the feed decoder class instance.

decodeWorker.onmessage = async function (chunks) {
  // Create an AudioBuffer from the chunks returned by the worker
  const audioBuffer = await decoder._onNewMessageChunks(chunks.data)

  // Save the audio buffer to the FeedDecoder's `messages` object
  decoder.messages[messageId] = audioBuffer
}

Using FeedDecoder you can store AudioBuffers from new feed items and recall them at any time during the user session, via the playMessage() method.

// This allows you to easily play the content by keying its URL or message ID
decoder.playMessage(messageId, seek=0)
// or you can play from any valid seek point in the audio:
decoder.playMessage(messageId, seek=30)

Standard audio player controls are provided:

decoder._pauseBuffer() // Pauses playback at playhead position
decoder._resumeBuffer() // Resumes playback at playhead after pausing
decoder._stopBuffer() // Stops playback entirely and returns playhead to 0
decoder._seekBuffer(seekAmount) // seekAmount can be any positive or negative float

Playback events

You can setup some event listeners for audio playback too:

decoder.e.on('play', () => console.log('play emitted'))
decoder.e.on('pause', () => console.log('pause emitted'))
decoder.e.on('stop', () => console.log('stop emitted'))
decoder.e.on('seek', () => console.log('seek emitted'))

Tracking Progress

Use the timeupdate event to track the current playhead position for the loaded audio buffer.

decoder.e.on('timeupdate', (t) => {
  console.log(`current playhead position is: `${t}`)
})

TODOs

Playback Controls

• play
• seek
• pause
• stop
• resume

Time

• playback duration tracking
• TimeRanges tracking
• AudioContext newEvent/endEvent

Events

MediaElement

• play
• pause
• stop
• canplay/canplaythrough
• waiting
• seeked