A library for encoding and decoding web audio as OggOpus.
WebAssembly JavaScript Other
Clone or download
Pull request Compare This branch is 554 commits ahead, 12 commits behind mattdiamond:master.
Permalink
Failed to load latest commit information.
.circleci Update node version Dec 18, 2017
dist-unminified Fix serial May 28, 2018
dist Fix serial May 28, 2018
example Fix option name in example May 22, 2018
opus @ defbc37 Update dist Jul 15, 2017
speexdsp @ 887ac10 Update dist Jul 15, 2017
src Fix serial May 28, 2018
test Fix serial May 28, 2018
.gitignore Add placeholder tests Apr 3, 2017
.gitmodules Update dist Jul 15, 2017
LICENSE.md Update LICENSE.md Mar 4, 2018
Makefile Update webpack May 21, 2018
README.md Cleanup example May 19, 2018
bower.json Update bower Dec 18, 2017
package-lock.json Update webpack May 21, 2018
package.json Fix serial May 28, 2018
test.js Add test.js Nov 16, 2017
webpack.config.js Update webpack May 21, 2018

README.md

Opus & Wave Recorder

A javascript library to encode the output of Web Audio API nodes in Ogg Opus or WAV format using WebAssembly.

Libraries Used

  • Libopus: v1.2.1 compiled with emscripten 1.38.1
  • speexDSP: 1.2RC3 compiled with emscripten 1.38.1

Required Files

The required files are in the dist folder. Unminified sources are in dist-unminified. Examples for recording, encoding, and decoding are in examples folder.


Usage

Constructor

The Recorder object is available in the global namespace and supports CommonJS and AMD imports.

var rec = new Recorder([config]);

Creates a recorder instance.

  • config - An optional configuration object.

General Config options

  • bufferLength - (optional) The length of the buffer that the internal JavaScriptNode uses to capture the audio. Can be tweaked if experiencing performance issues. Defaults to 4096.
  • encoderPath - (optional) Path to encoderWorker.min.js or waveWorker.min.js worker script. Defaults to encoderWorker.min.js
  • leaveStreamOpen - (optional) Keep the stream and context around when trying to stop recording, so you can re-start without re-initializing the stream and context. Defaults to false.
  • mediaTrackConstraints - (optional) Object to specify media track constraints. Defaults to true.
  • monitorGain - (optional) Sets the gain of the monitoring output. Gain is an a-weighted value between 0 and 1. Defaults to 0
  • numberOfChannels - (optional) The number of channels to record. 1 = mono, 2 = stereo. Defaults to 1. Maximum 2 channels are supported.
  • recordingGain - (optional) Sets the gain of the recording input. Gain is an a-weighted value between 0 and 1. Defaults to 1

Config options for OGG OPUS encoder

  • encoderApplication - (optional) Supported values are: 2048 - Voice, 2049 - Full Band Audio, 2051 - Restricted Low Delay. Defaults to 2049.
  • encoderBitRate - (optional) Target bitrate in bits/sec. The encoder selects an application-specific default when this is not specified.
  • encoderComplexity - (optional) Value between 0 and 10 which determines latency and processing for encoding. 0 is fastest with lowest complexity. 10 is slowest with highest complexity. The encoder selects a default when this is not specified.
  • encoderFrameSize - (optional) Specifies the frame size in ms used for encoding. Defaults to 20.
  • encoderSampleRate - (optional) Specifies the sample rate to encode at. Defaults to 48000. Supported values are 8000, 12000, 16000, 24000 or 48000.
  • maxBuffersPerPage - (optional) Maximum number of buffers to use before generating an Ogg page. This can be used to lower the streaming latency. The lower the value the more overhead the ogg stream will incur. Defaults to 40.
  • originalSampleRateOverride - (optional) Override the ogg opus 'input sample rate' field. Google Speech API requires this field to be 16000.
  • resampleQuality - (optional) Value between 0 and 10 which determines latency and processing for resampling. 0 is fastest with lowest quality. 10 is slowest with highest quality. Defaults to 3.
  • streamPages - (optional) dataAvailable event will fire after each encoded page. Defaults to false.

Config options for WAV recorder

  • wavBitDepth - (optional) Desired bit depth of the WAV file. Defaults to 16. Supported values are 8, 16, 24 and 32 bits per sample.

Instance Methods

rec.clearStream()

clearStream will stop and delete the stream as well as close the audio context. You will only ever call this manually if you have config.leaveStreamOpen set to true.

rec.pause()

pause will keep the stream and monitoring alive, but will not be recording the buffers. Will call the onpause callback when paused. Subsequent calls to resume will add to the current recording.

rec.resume()

resume will resume the recording if paused. Will call the onresume callback when recording is resumed.

rec.setRecordingGain( gain )

setRecordingGain will set the volume on what will be passed to the recorder. Gain is an a-weighted value between 0 and 1.

rec.setMonitorGain( gain )

setMonitorGain will set the volume on what will be passed to the monitor. Monitor level does not affect the recording volume. Gain is an a-weighted value between 0 and 1.

rec.start( [sourceNode] )

start Initalizes the worker, audio context, and an audio stream and begin capturing audio. Returns a promise which resolves when recording is started. Will callback onstart when started. Optionally accepts a source node which can be used in place of initializing the microphone stream. For iOS support, start needs to be initiated from a user action.

rec.stop()

stop will cease capturing audio and disable the monitoring and mic input stream. Will request the recorded data and then terminate the worker once the final data has been published. Will call the onstop callback when stopped.


Static Methods

Recorder.isRecordingSupported()

Returns a truthy value indicating if the browser supports recording.


Callback Handlers

rec.ondataavailable( arrayBuffer )

A callback which returns an array buffer of audio data. If streamPages is true, this will be called with each page of encoded audio. If streamPages is false, this will be called when the recording is finished with the complete data.

rec.onpause()

A callback which occurs when media recording is paused.

rec.onresume()

A callback which occurs when media recording resumes after being paused.

rec.onstart()

A callback which occurs when media recording starts.

rec.onstop()

A callback which occurs when media recording ends.


Gotchas

  • To be able to read the mic stream, the page must be served over https
  • iOS Safari requires rec.start() to be called from a user initiated event
  • macOS Safari v11 native opus playback is not yet supported
  • iOS Safari v11 native opus playback is not yet supported
  • Microsoft Edge native opus playback is not yet supported

Browser Support

Supported:

  • Chrome v58
  • Firefox v53
  • Microsoft Edge v41
  • Opera v44
  • macOS Safari v11
  • iOS Safari v11

Unsupported:

  • IE 11 and below
  • iOS 11 Chrome

Known Issues


Building from sources

Prebuilt sources are included in the dist folder. However below are instructions if you want to build them yourself. Opus and speex are compiled without SIMD optimizations. Performace is significantly worse with SIMD optimizations enabled.

Mac: Install autotools using MacPorts

port install automake autoconf libtool pkgconfig

Windows: Install autotools using MSYS2

pacman -S make autoconf automake libtool pkgconfig

Inatall Node.js

Install EMScripten

Install npm dependencies:

npm install

checkout, compile and create the dist from sources:

npm run make

Running the unit tests:

npm test

Clean the dist folder and git submodules:

make clean