OggVorbisEncoder.js

What is it?

OggVorbisEncoder.js is a JavaScript library that encodes audio data to Ogg Vorbis on web browsers.

libogg and libvorbis are used for encoding engine. Emscripten is used to convert libogg/libvorbis C code into JavaScript.

Acknowledgement

It was originally a fork of https://github.com/Garciat/libvorbis.js (and also its ancestors). API has been totally re-designed and simplified. Now it has been a lower layer part of WebAudioRecorder.js.

Demo

https://higuma.github.io/ogg-vorbis-encoder-js/

Library files

lib/ contains library files.

• OggVorbisEncoder.js: JavaScript library (uncompressed)
• OggVorbisEncoder.min.js: JavaScript library (minified)
• OggVorbisEncoder.min.js.mem: memory initializer data for OggVorbisEncoder.min.js

Using library

Uncompressesd library is a single file. You can use it from both HTML and Web Worker.

• from HTML: <script src="javascripts/OggVorbisEncoder.js"></script>
• from Worker: importScripts("javascripts/OggVorbisEncoder.js");

Using minified library is same way. But you must pay attention to memory initializer location.

• from HTML: default directory is same as HTML which loads OggVorbisEncoder.min.js
• from Worker: default directory is same as OggVorbisEncoder.min.js path

To change memory initializer path from HTML:

<script>
// default path is on the same directory as this HTML
OggVorbisEncoderConfig = {
  memoryInitializerPrefixURL: "javascripts/"   // must end with slash
  // => changed to javascripts/OggVorbisEncoder.min.js.mem
};
</script>
<script src="javascripts/OggVorbisEncoder.min.js"></script>

From Worker:

// default path is on the same directory as OggVorbisEncoder.min.js
self.OggVorbisEncoderConfig = {
  memoryInitializerPrefixURL: "javascripts/memory/"
  // => changed to javascripts/memory/OggVorbisEncoder.min.js.mem
};
importScripts("javascripts/OggVorbisEncoder.min.js");

API

encoder = new OggVorbisEncoder(sampleRate, numChannels, quality)

Create an encoder object.

• Parameters
  • samleRate: sampling rate [Hz]
  • numChannels: number of audio channels
  • quality: Vorbis quality (-0.1 <= quality <= 1)
• Returns
  • encoder object

Current implementation supports VBR encoding only.

encoder.encode(buffers)

Encode audio buffers.

• Parameters
  • buffers: array of sample buffers ([Float32Array, Float32Array ...])
• Returns
  • (none)

buffers must be an array of Float32Array audio data (range = [-1, 1]). Array length must be same as number of channels. It supports stream (incremental) processing. Sample buffers are processed to Ogg Vorbis stream and appended to internal data.

blob = encoder.finish([mimeType])

Finish encoding and get Ogg Vorbis as a Blob.

• Parameters
  • mimeType(optional): MIME type (default = "audio/ogg")
• Returns
  • Blob object

After calling .finish(), all internal data is cleared (to avoid resource leak). You must create a new encoder object to encode another audio data.

encoder.cancel()

• Parameters
  • (none)
• Returns
  • (none)

Cancel encoding and clear all internal data.

You should call .cancel() manually to avoid resource leak when recording is canceled (encoder's internal memory is not deallocated by unbinding an object variable).

Build

Emscripten and ruby are required to build the library.

$ rake

Download and extract libogg + libvorbis, build library files (see Rakefile for more details).

License

libogg and libvorbis are released under Xiph's BSD-like license below. JavaScript-converted part of this library follows the same license.

http://www.xiph.org/licenses/bsd/

C and JavaScript wrapper API part of this library is released under MIT licence (see LICENSE.txt).