wavtools

wavtools is a library for both recording and streaming Waveform Audio (.wav) data in the browser. It is intended for managing PCM16 audio streams directly.

This is a fork of open source, MIT licensed tooling initially developed at OpenAI as part of the OpenAI Realtime Console, developed by Keith Horwood.

The two most important classes are the WavRecorder used for capturing audio in the browser, and WavStreamPlayer for queueing and streaming audio chunks to the user.

Installation and usage

To install wavtools in a Webpack project;

$ npm i wavtools --save

import { WavRecorder, WavStreamPlayer } from 'wavtools';

const wavRecorder = new WavRecorder({ sampleRate: 24000 });
wavRecorder.getStatus(); // "ended"

To use as a standalone script, download the script/wavtools.js or script/wavtools.min.js files and import them;

<script src="/script/wavtools.js"></script>
<script>
  // works as part of `window` object
  const wavRecorder = new WavRecorder({ sampleRate: 24000 });
  wavRecorder.getStatus(); // "ended"
</script>

WavRecorder Quickstart

import { WavRecorder } from 'wavtools';

const wavRecorder = new WavRecorder({ sampleRate: 24000 });
wavRecorder.getStatus(); // "ended"

// request permissions, connect microphone
await wavRecorder.begin();
wavRecorder.getStatus(); // "paused"

// Start recording
// This callback will be triggered in chunks of 8192 samples by default
// { mono, raw } are Int16Array (PCM16) mono & full channel data
await wavRecorder.record((data) => {
  const { mono, raw } = data;
});
wavRecorder.getStatus(); // "recording"

// Stop recording
await wavRecorder.pause();
wavRecorder.getStatus(); // "paused"

// outputs "audio/wav" audio file
const audio = await wavRecorder.save();

// clears current audio buffer and starts recording
await wavRecorder.clear();
await wavRecorder.record();

// get data for visualization
const frequencyData = wavRecorder.getFrequencies();

// Stop recording, disconnects microphone, output file
await wavRecorder.pause();
const finalAudio = await wavRecorder.end();

// Listen for device change; e.g. if somebody disconnects a microphone
// deviceList is array of MediaDeviceInfo[] + `default` property
wavRecorder.listenForDeviceChange((deviceList) => {});

WavStreamPlayer Quickstart

import { WavStreamPlayer } from '/src/lib/wavtools/index.js';

const wavStreamPlayer = new WavStreamPlayer({ sampleRate: 24000 });

// Connect to audio output
await wavStreamPlayer.connect();

// Create 1s of empty PCM16 audio
const audio = new Int16Array(24000);
// Queue 3s of audio, will start playing immediately
wavStreamPlayer.add16BitPCM(audio, 'my-track');
wavStreamPlayer.add16BitPCM(audio, 'my-track');
wavStreamPlayer.add16BitPCM(audio, 'my-track');

// get data for visualization
const frequencyData = wavStreamPlayer.getFrequencies();

// Interrupt the audio (halt playback) at any time
// To restart, need to call .add16BitPCM() again
const trackOffset = await wavStreamPlayer.interrupt();
trackOffset.trackId; // "my-track"
trackOffset.offset; // sample number
trackOffset.currentTime; // time in track

Compilation

When modifying the repository, to create appropriate TypeScript types and JavaScript bundles, use npm run compile.

Acknowledgements and contact

Thanks to the OpenAI Realtime team! Without their awesome work this library would not be needed.

• OpenAI Developers / @OpenAIDevs
• Jordan Sitkin / API / @dustmason
• Mark Hudnall / API / @landakram
• Peter Bakkum / API / @pbbakkum
• Atty Eleti / API / @athyuttamre
• Jason Clark / API / @onebitToo
• Karolis Kosas / Design / @karoliskosas
• Romain Huet / DX / @romainhuet
• Katia Gil Guzman / DX / @kagigz
• Ilan Bigio / DX / @ilanbigio
• Kevin Whinnery / DX / @kevinwhinnery

You can reach me directly at;

• Keith Horwood / @keithwhor