web-audio-recorder-js

WebAudioRecorder.js is a JavaScript library that records audio input (Web Audio API AudioNode object) and encodes to audio file image (Blob object). It supports three encoding formats.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
web-audio-recorder-js
300.0.27 years ago7 years agoMinified + gzip package size for web-audio-recorder-js in KB

Popular Searches

Readme

WebAudioRecorder.js

What is it?

WebAudioRecorder.js is a JavaScript library that records audio input (Web Audio API AudioNode object) and encodes to audio file image (Blob object). It supports three encoding formats.
  • Waveform Audio (.wav)
  • Ogg Vorbis (.ogg)
  • MP3 (MPEG-1 Audio Layer III) (.mp3)
This library uses following encoder libraries as lower layer.
  • WavAudioEncoder.js:
  • OggVorbisEncoder.js:
  • Mp3LameEncoder.js:

Demo

Microphone recorder demo.

Library files

Library consists of one main script and several worker scripts. lib/ contains uncompressed library files.
  • WebAudioRecorder.js: main script
  • WebAudioRecorderWav.js: worker for Waveform Audio encoder
  • WebAudioRecorderOgg.js: worker for Ogg Vorbis encoder
  • WebAudioRecorderMp3.js: worker for MP3 encoder
  • OggVorbisEncoder.min.js.mem: memory initializer for Ogg Vorbis encoder (must be located on the same directory)
  • Mp3LameEncoder.min.js.mem: memory initializer for MP3 encoder (must be located on the same directory)
lib-minified/ contains minified library files.
  • WebAudioRecorder.min.js: main script (minified)
  • WebAudioRecorderWav.min.js: worker for Waveform Audio (concatenated with encoder and recompressed)
  • WebAudioRecorderOgg.min.js: worker for Ogg Vorbis (concatenated with encoder and recompressed)
  • WebAudioRecorderMp3.min.js: worker for MP3 (concatenated with encoder and recompressed)
  • OggVorbisEncoder.min.js.mem: memory initializer for Ogg Vorbis encoder (same file as above)
  • Mp3LameEncoder.min.js.mem: memory initializer for MP3 encoder (same file as avove)

Using library

Load main script from HTML first. ``` html ``` Worker files are loaded on creating an audio recorder object (or changing encoding by setEncoding()). You must set worker directory on object constructor (see API reference for detail). ``` javascript audioRecorder = new WebAudioRecorder(sourceNode, { workerDir: "javascripts/" // must end with slash }); ```

API

Constructor

``` javascript recorder = new WebAudioRecorder(sourceNode, configs) ``` Create an audio recorder object.
  • Parameters
* `sourceNode`: source input (AudioNode object)
* `configs`: configuration object
* `.workerDir`: worker files directory (default = `"/"`)
* `.numChannels`: number of channels (default = `2` (stereo))
* `.encoding`: encoding (default = `"wav"`, see `.setEncoding()` for detail)
* `.options`: options (see `.setOptions()` for detail)
* you can also set event handlers (see "Event handlers" for detail)
  • Returns
* audio recorder object
Every configuration property has a default value (typically you ought to set only .workerDir and .encoding). You can change encoding by .setEncoding() and options by .setOptions() after construction. If you use MP3 encoding, you cannot change .numChannels from default (current MP3 encoder supports 2-channel stereo only).
In fact, configs is just deep-copied into the recorder object itself.

Methods

``` javascript recorder.setEncoding(encoding) ``` Change encoding after construction.
  • Parameters
* `.encoding`: encoding
* `"wav"`: Waveform Audio (default)
* `"ogg"`: Ogg Vorbis
* `"mp3"`: MP3
  • Returns
* (none)
You can change encoding when recording is not running. If the method is called during recording, .onError() event is fired. ``` javascript recorder.setOptions(options) ``` Set options.
  • Parameters
* `options`: options object
* `.timeLimit`: recording time limit (second) (default = `300`)
* `.encodeAfterRecord`: encoding process mode
* `false`: process encoding on recording background (default)
* `true`: process encoding after recording is finished
* `.progressInterval`: encoding progress report interval (millisecond) (default = `1000`)
* (used only if `.encodeAfterRecord` is `true`)
* `.bufferSize`: recording buffer size (default = `undefined` (use browser default))
* `.wav.mimeType`: Waveform Audio MIME type (default = `"audio/wav"`)
* `.ogg.mimeType`: Ogg Vorbis MIME type (default = `"audio/ogg"`)
* `.ogg.quality`: Ogg Vorbis quality (-0.1 .. 1) (default = `0.5`)
* `.mp3.mimeType`: MP3 MIME type (default = `"audio/mpeg"`)
* `.mp3.bitRate`: MP3 bit rate (typically 64 .. 320 for 44100Hz) (default = `160`)
  • Returns
* (none)
You can set options when recording is not running. If the method is called during recording, .onError() event is fired. ``` javascript recorder.startRecording() ``` Start recording.
  • Parameters
* (none)
  • Returns
* (none)
If .encoderAfterRecord options is false (default), encoding process is performed on recording background. If .encoderAfterRecord is true, audio data is just stored to worker's buffer. Encoding process is performed after recording is finished. ``` javascript recorder.isRecording() ``` Return if recording is running.
  • Parameters
* (none)
  • Returns
* `false`: recording is not running
* `true`: recording is running
``` javascript recordingTime = recorder.recordingTime() ``` Report recording time.
  • Parameters
* (none)
  • Returns
* recording time (second) or `null` (not recording)
``` javascript recorder.cancelRecording() ``` Cancel current recording without saving.
  • Parameters
* (none)
  • Returns
* (none)
``` javascript recorder.finishRecording() ``` Finish current recording.
  • Parameters
* (none)
  • Returns
* (none)
If .encoderAfterRecord options is false (default), it finishes encoding and make a Blob object immediately. You get a Blob with .onComplete() event. If .encoderAfterRecord is true, it starts encoding process. Encoding process may take several seconds to a few minutes (depending on recording time). You can get encoding progress with onEncodingProgress() event. Getting a Blob is same as above. ``` javascript recorder.cancelEncoding() ``` Cancel encoding.
  • Parameters
* (none)
  • Returns
* (none)
This method is used when .encoderAfterRecord is true and worker is processing encoding after .finishRecording(). You can interrupt worker's encoding process and do cleanup.
Internally, it calls worker.terminate() to kill worker process and makes another worker.

Event handlers

Encoder worker's responses are processed by event handlers. Some other breakpoints are also provided as events. Events summary is as below (first parameter is always recorder object). ``` javascript recorder.onEncoderLoading = function(recorder, encoding) { ... } recorder.onEncoderLoaded = function(recorder, encoding) { ... } recorder.onTimeout = function(recorder) { ... } recorder.onEncodingProgress = function (recorder, progress) { ... } recorder.onEncodingCanceled = function(recorder) { ... } recorder.onComplete = function(recorder, blob) { ... } recorder.onError = function(recorder, message) { ... } ``` You can set an event handler to object property. ``` javascript recorder = new WebAudioRecorder(source, { workerDir: "javascripts/" }); recorder.onComplete = function(rec, blob) { // use Blob }; ``` You can also set event handlers from constructor parameter. ``` javascript recorder = new WebAudioRecorder(source, { workerDir: "javascripts/", onEncoderLoading: function(recorder, encoding) { 
// show "loading encoder..." display
}, onEncoderLoaded: function(recorder, encoding) { 
// hide "loading encoder..." display
} }); ```

Event reference

``` javascript recorder.onEncoderLoading = function(recorder, encoding) { ... } ```
  • Fired on
* recorder is going to load an encoder worker (on construction or changing encoding)
  • Parameters
* `recorder`: audio recorder object
* `encoding`: encoding
  • Default handler
* empty function
It is the only event to be fired during construction process. To catch the first event correctly, it should be set from constructor parameter (see above example). ``` javascript recorder.onEncoderLoaded = function(recorder, encoding) { ... } ```
  • Fired on
* encoder worker has finished loading
  • Parameters
* `recorder`: audio recorder object
* `encoding`: encoding
  • Default handler
* empty function
``` javascript recorder.onTimeout = function(recorder) { ... } ```
  • Fired on
* recording time exceeds timeout limit
  • Parameters
* `recorder`: audio recorder object
  • Default handler
* call `recorder.finishRecording()`.
``` javascript recorder.onEncodingProgress = function (recorder, progress) { ... } ```
  • Fired on
* worker reports encoding progress (when `.encodeAfterRecord` is `true`)
  • Parameters
* `recorder`: audio recorder object
* `progress`: progress (from `0` to `1`)
  • Default handler
* empty function
``` javascript recorder.onEncodingCanceled = function(recorder) { ... } ```
  • Fired on
* `.cancelRecording()` is called
  • Parameters
* `recorder`: audio recorder object
  • Default handler
* empty function
``` javascript recorder.onComplete = function(recorder, blob) { ... } ```
  • Fired on
* worker completes encoding to Blob
  • Parameters
* `recorder`: audio recorder object
* `blob`: Blob object
  • Default handler
* warn `"You must override onComplete event"` by `recorder.onError()`
This is the most important event. You must override to get the result. ``` javascript recorder.onError = function(recorder, message) { ... } ```
  • Fired on
* error
  • Parameters
* `recorder`: audio recorder object
* `message`: error message
  • Default handler
* show message by `console.log(message)`

License

Ogg Vorbis encoder part of the library uses JavaScript-converted code of libogg and libvorbis. They are released under Xiph's BSD-like license. Ogg Vorbis encoder part of this library follows the same license (see link below). MP3 encoder part of this library uses JavaScript-converted code of LAME. LAME is licensed under the LGPL. MP3 encoder part of this library follows the same license (see link below). All other parts are released under MIT license (see LICENSE.txt).