search

higuma / web-audio-recorder-js

.wav/.ogg/.mp3 recorder with Web Audio API
MIT License
775 stars 185 forks source link

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.

This library uses following encoder libraries as lower layer.

Demo

Microphone recorder demo.

https://higuma.github.io/web-audio-recorder-js/

Library files

Library consists of one main script and several worker scripts.

lib/ contains uncompressed library files.

lib-minified/ contains minified library files.

Using library

Load main script from HTML first.

<script src="https://github.com/higuma/web-audio-recorder-js/raw/master/javascripts/WebAudioRecorder.js"></script>

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

audioRecorder = new WebAudioRecorder(sourceNode, {
  workerDir: "javascripts/"     // must end with slash
});

API

Constructor

recorder = new WebAudioRecorder(sourceNode, configs)

Create an 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

recorder.setEncoding(encoding)

Change encoding after construction.

You can change encoding when recording is not running. If the method is called during recording, .onError() event is fired.

recorder.setOptions(options)

Set options.

You can set options when recording is not running. If the method is called during recording, .onError() event is fired.

recorder.startRecording()

Start recording.

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.

recorder.isRecording()

Return if recording is running.

recordingTime = recorder.recordingTime()

Report recording time.

recorder.cancelRecording()

Cancel current recording without saving.

recorder.finishRecording()

Finish current recording.

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.

recorder.cancelEncoding()

Cancel encoding.

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

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.

recorder = new WebAudioRecorder(source, { workerDir: "javascripts/" });
recorder.onComplete = function(rec, blob) {
  // use Blob
};

You can also set event handlers from constructor parameter.

recorder = new WebAudioRecorder(source, {
  workerDir: "javascripts/",
  onEncoderLoading: function(recorder, encoding) {
    // show "loading encoder..." display
  },
  onEncoderLoaded: function(recorder, encoding) {
    // hide "loading encoder..." display
  }
});

Event reference

recorder.onEncoderLoading = function(recorder, encoding) { ... }

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

recorder.onEncoderLoaded = function(recorder, encoding) { ... }
recorder.onTimeout = function(recorder) { ... }
recorder.onEncodingProgress = function (recorder, progress) { ... }
recorder.onEncodingCanceled = function(recorder) { ... }
recorder.onComplete = function(recorder, blob) { ... }

This is the most important event. You must override to get the result.

recorder.onError = function(recorder, 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).

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

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

http://lame.sourceforge.net/about.php

All other parts are released under MIT license (see LICENSE.txt).