Need help with opus-media-recorder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

kbumsik
188 Stars 22 Forks Other 113 Commits 26 Opened issues

Description

MediaRecorder polyfill for Opus recording using WebAssembly

Services available

!
?

Need anything else?

Contributors list

# 61,276
C
adafrui...
mpd
stm32f4
110 commits
# 5,310
Django
microph...
wavefor...
flash
1 commit

opus-media-recorder

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.

Why opus-media-recorder?

| | 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:

  1. Not all browsers support MediaRecorder.
  2. Even the browsers that provides MediaRecorder don't support the same format.

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.

How to use

opus-media-recorder is compatible with the Mediastream Recording API standard.

Thing to know

  • The page must be served over HTTPS in order to record.
  • Being able to record does not always mean you can play it in a browser:
    • macOS/iOS Safari cannot play Opus natively yet.
    • Old Edge requires an extension to play Opus natively.
    • You can get an Opus decorder to play it. There are Opus decoders available, such as Chris Rudmin's Opus decoder.
    • Otherwise, users can download as a recording file and play it using apps like VLC.
  • When
    mimeType
    is not specified a default encoder is loaded depending on OS:
    • Chrome:
      audio/webm
    • Firefox:
      audio/ogg
    • Edge:
      audio/webm
    • iOS/macOS Safari:
      audio/wave
      - because they cannot play Opus at all.

JavaScript

For standard usages of

MediaRecorder
, see the MDN reference and other online resources. Our testing website and example section may be useful as well.

Examples

Installation

npm install --save-dev opus-media-recorder

Working with a bundler

Because

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);

Simple JavaScript example (webpack)

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

// 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()); })

HTML
 tag

The

OpusMediaRecorder
object is available in the global namespace using UMD.




Use opus-media-recorder only when a browser doesn't support it

// 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;
}

Browser support

Supported:

  • Chrome >= 58
  • Firefox >= 53
  • Microsoft Edge >= 41
  • Safari (macOS and iOS) >= 11

Browsers with issues:

  • iOS 11.2 only: Not working due to a regression in WebAssembly: https://bugs.webkit.org/show_bug.cgi?id=181781

MIME Type support

  • audio/webm
  • audio/webm; codecs=opus
  • audio/ogg
  • audio/ogg; codecs=opus
  • audio/wav
    or
    audio/wave

Limitations

  • Does not support Video recording.
  • opus-media-recorder
    throws generic Error objects instead of native DOMException.
  • Because
    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.
  • There is no
    SecurityError
    case implemented. (WIP)

How to build

  1. To build from the source, you need Emscripten, yarn, Python 2.7 or higher, and basic C program build systems such as GNU Make.

  2. yarn install
    to install JavaScript dependencies.
  3. yarn run build
    to build.
    yarn run build:production
    to build files for distribution.
  4. 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.
  5. yarn run clean
    to clean up build files.

Changelog

See CHANGELOG.md.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.