opus-media-recorder is a MediaRecorder API polyfill written in ES6 and WebAssembly. It aims for cross-browser Opus codec support with various audio formats such as Ogg and WebM. opus-media-recorder can be used as a polyfill, or it can replace the built-in MediaRecorder since opus-media-recorder supports more MIME types.
opus-media-recorder uses WebAssembly compiled from popular libraries (e.g libopus, libogg, libwebm, and speexdsp) to ensure good performance and standards-compliance.
| opus-media-recorder | Chrome | Firefox | iOS | Edge | |
|---|---|---|---|---|---|
audio/ogg |
O | X | O | X | X |
audio/webm |
O | O | X | X | X |
audio/wav |
O | X | X | X | X |
* Both audio/ogg and audio/webm refer containers for Opus audio codec.
Currently the MediaRecorder API suffers from the two problems:
opus-media-recorder tackles these problems by supporting all major modern browsers (Chrome, Firefox, iOS, and Edge) and by providing various formats.
By taking advantages of WebAssembly and Web Workers, opus-media-recorder tries to have minimum performace penalties of running encoders in a browser.
opus-media-recorder is compatible with the Mediastream Recording API standard.
mimeType is not specified a default encoder is loaded depending on OS:
audio/webmaudio/oggaudio/webmaudio/wave - because they cannot play Opus at all.For standard usages of MediaRecorder, see the MDN reference and other online resources. Our testing website and example section may be useful as well.
npm install --save-dev opus-media-recorderBecause opus-media-recorder needs to load a dedicated web worker and .wasm binaries, special configurations are necessary. In general:
import OpusMediaRecorder from 'opus-media-recorder';
// Choose desired format like audio/webm. Default is audio/ogg
const options = { mimeType: 'audio/ogg' }
// Web worker and .wasm configuration. Note: This is NOT a part of W3C standard.
const workerOptions = {
encoderWorkerFactory: function () {
// UMD should be used if you don't use a web worker bundler for this.
return new Worker('.../path/to/opus-media-recorder/encoderWorker.umd.js')
},
OggOpusEncoderWasmPath: '.../path/to/opus-media-recorder/OggOpusEncoder.wasm',
WebMOpusEncoderWasmPath: '.../path/to/opus-media-recorder/WebMOpusEncoder.wasm'
};
window.MediaRecorder = OpusMediaRecorder;
recorder = new MediaRecorder(stream, options, workerOptions);import MediaRecorder from 'opus-media-recorder';
// Use worker-loader
import EncoderWorker from 'worker-loader!opus-media-recorder/encoderWorker.js';
// You should use file-loader in webpack.config.js.
// See webpack example link in the above section for more detail.
import OggOpusWasm from 'opus-media-recorder/OggOpusEncoder.wasm';
import WebMOpusWasm from 'opus-media-recorder/WebMOpusEncoder.wasm';
// Non-standard options
const workerOptions = {
encoderWorkerFactory: _ => new EncoderWorker(),
OggOpusEncoderWasmPath: OggOpusWasm,
WebMOpusEncoderWasmPath: WebMOpusWasm
};
let recorder;
function startRecording () {
navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
let options = { mimeType: 'audio/ogg' };
// Start recording
recorder = new MediaRecorder(stream, options, workerOptions);
recorder.start();
// Set record to <audio> when recording will be finished
recorder.addEventListener('dataavailable', (e) => {
audioElement.src = URL.createObjectURL(e.data);
});
});
}
// Recording should be started in user-initiated event like buttons
recordButton.addEventListener('click', startRecording);
// Stop recording
stopButton.addEventListener('click', () => {
recorder.stop();
// Remove “recording” icon from browser tab
recorder.stream.getTracks().forEach(i => i.stop());
})<script> tagThe OpusMediaRecorder object is available in the global namespace using UMD.
<!-- load OpusMediaRecorder.umd.js. OpusMediaRecorder will be loaded. -->
<script src="https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/OpusMediaRecorder.umd.js"></script>
<!-- load encoderWorker.umd.js. This should be after OpusMediaRecorder. -->
<!-- This script tag will create OpusMediaRecorder.encoderWorker. -->
<script src="https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/encoderWorker.umd.js"></script>
<script>
...
// If you already load encoderWorker.js using <script> tag,
// you don't need to define encoderWorkerFactory.
const workerOptions = {
OggOpusEncoderWasmPath: 'https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/OggOpusEncoder.wasm',
WebMOpusEncoderWasmPath: 'https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/WebMOpusEncoder.wasm'
};
// Replace MediaRecorder
window.MediaRecorder = OpusMediaRecorder;
let recorder = new MediaRecorder(stream, {}, workerOptions);
...
</script>// Check if MediaRecorder available.
if (!window.MediaRecorder) {
window.MediaRecorder = OpusMediaRecorder;
}
// Check if a target format (e.g. audio/ogg) is supported.
else if (!window.MediaRecorder.isTypeSupported('audio/ogg;codecs=opus')) {
window.MediaRecorder = OpusMediaRecorder;
}Supported:
Browsers with issues:
audio/webmaudio/webm; codecs=opusaudio/oggaudio/ogg; codecs=opusaudio/wav or audio/waveopus-media-recorder throws generic Error objects instead of native DOMException.audio/wav is not designed for streaming, when mimeType is audio/wav, each dataavailabe events produces a complete and separated .wav file that cannot be concatenated together unlike Ogg and WebM. Therefore, it is recommended not to use timeslice option when calling start(), unless you know what the implication is.SecurityError case implemented. (WIP)To build from the source, you need Emscripten, yarn, Python 2.7 or higher, and basic C program build systems such as GNU Make.
yarn install to install JavaScript dependencies.
yarn run build to build. yarn run build:production to build files for distribution.
yarn run serve to run a test web server locally. Default URL is https://localhost:9000 (It has to be HTTPS). You might have to change DEV_SERVER_URL and DEV_SERVER_PORT to change the address of the local test server.
yarn run clean to clean up build files.
See CHANGELOG.md.