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
WavAudioEncoder.min.js
: Waveform Audio encoder (from WavAudioEncoder.js)
OggVorbisEncoder.min.js
: Ogg Vorbis encoder (from OggVorbisEncoder.js)
Mp3LameEncoder.min.js
: MP3 encoder (from Mp3LameEncoder.js)
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 bysetEncoding()
). 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)`