Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

.wav/.ogg/.mp3 recorder with Web Audio API
https://github.com/higuma/web-audio-recorder-js

Last synced: about 2 months ago
JSON representation

.wav/.ogg/.mp3 recorder with Web Audio API

Awesome Lists containing this project

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

* `WavAudioEncoder.min.js`: Waveform Audio encoder (from [WavAudioEncoder.js](https://github.com/higuma/wav-audio-encoder-js))

* `OggVorbisEncoder.min.js`: Ogg Vorbis encoder (from [OggVorbisEncoder.js](https://github.com/higuma/ogg-vorbis-encoder-js))

* `Mp3LameEncoder.min.js`: MP3 encoder (from [Mp3LameEncoder.js](https://github.com/higuma/mp3-lame-encoder-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 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](https://xiph.org/ogg/) and [libvorbis](https://xiph.org/vorbis/). 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](http://lame.sourceforge.net/). 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](LICENSE.txt)).