Skip to content

Latest commit

 

History

History
426 lines (349 loc) · 8.18 KB

README-EN.md

File metadata and controls

426 lines (349 loc) · 8.18 KB
Raw

AMR Recorder

npm npm size gzip size

Play, record, reformat AMR audio, in pure Javascript, without any server.

This project is based on amr.js and RecorderJs.

NOTE: Since amr.js is used for encoding and decoding, the js file is close to 500 KB (minified, no gzipped), please consider before use.

Feature

  • Simple API for playing and recording AMR audio.
  • Supported url or blob (e.g. <input type="file">) to initialize AMR.
  • Supported reformat audio which browser is supported (such as MP3 or OGG) to AMR audio.
  • AMR that is encoded could be downloaded, without any server.

Demo

demo-en.html

Browser Compatibility

For the latest browser compatibility, please refer to Can I Use.

  - Play only: https://caniuse.com/#feat=audio-api   - Play + Record: https://caniuse.com/#feat=stream

Setup

Load the JS file directly:

<script type="text/javascript" src="./BenzAMRRecorder.min.js"></script>

OR use npm:

NPM

npm install benz-amr-recorder

var BenzAMRRecorder = require('benz-amr-recorder');

Usage

Note: It is recommended to bind the initWithXXX() or play() methods to a user event (eg click, touchstart). Because almost all mobile devices (and the desktop version of Chrome 70+) prohibit JavaScript from playing audio automatically. reference:

Play an AMR:

var amr = new BenzAMRRecorder();
amr.initWithUrl('path/to/voice.amr').then(function() {
  amr.play();
});
amr.onEnded(function() {
  alert('play ended');
})

Play a local file:

<input type="file" id="amr-file" accept=".amr">
var amr = new BenzAMRRecorder();
var amrFileObj = document.getElementById('amr-file');
amrFileObj.onchange = function() {
  amr.initWithBlob(this.files[0]).then(function() {
    amr.play();
  });
}

Record AMR:

var amrRec = new BenzAMRRecorder();
amrRec.initWithRecord().then(function() {
  amrRec.startRecord();
});

Download AMR:

window.location.href = window.URL.createObjectURL(amr.getBlob());

Reformat MP3 to AMR (Need browser support MP3 format):

var amrFromMp3 = new BenzAMRRecorder();
amrFromMp3.initWithUrl('path/to/file.mp3').then(function() {
  // Download the AMR file
  window.location.href = window.URL.createObjectURL(amrFromMp3.getBlob());
})

API

Initialize

/**
 * If AMR was initialized
 * @return {boolean}
 */
amr.isInit();
/**
 * Init with Float32Array
 * @param {Float32Array} array
 * @return {Promise}
 */
amr.initWithArrayBuffer(array);
/**
 * Init with Blob object ( <input type="file"> )
 * @param {Blob} blob
 * @return {Promise}
 */
amr.initWithBlob(blob);
/**
 * Init with URL
 * @param {string} url
 * @return {Promise}
 */
amr.initWithUrl(url);
/**
 * Initialize record
 * @return {Promise}
 */
amr.initWithRecord();

Event listeners

Notice: They will NOT add the event listener. They simply cover the old listener only.

/**
 * On play
 * @param {Function | null} fn
 */
amr.onPlay(function() {
  console.log('play');
});
/**
 * On stop (Include onEnded)
 * @param {Function | null} fn
 */
amr.onStop(function() {
  console.log('stop playing');
});
/**
 * On pause
 * @param {Function | null} fn
 */
amr.onPause(function() {
  console.log('pause');
});
/**
 * On resume (form the paused state)
 * @param {Function | null} fn
 */
amr.onResume(function() {
  console.log('resume');
});
/**
 * on play ended
 * @param {Function | null} fn
 */
amr.onEnded(function() {
  console.log('play ended');
});
/**
 * on play to end and automatically ended
 * @param {Function | null} fn
 */
amr.onAutoEnded(function() {
  console.log('play automatically ended');
});
/**
 * on start record
 * @param {Function | null} fn
 */
amr.onStartRecord(function() {
  console.log('start record');
});
/**
 * on finish record
 * @param {Function | null} fn
 */
amr.onFinishRecord(function() {
  console.log('finish record');
});

Playing controls

/**
 * play (ignore the paused state)
 * @param {number?} startTime - specify the start position (in seconds, float number, optional)
 */
amr.play();
/**
 * stop
 */
amr.stop();
/**
 * pause
 * @since 1.1.0
 */
amr.pause();
/**
 * resume from the paused state
 * @since 1.1.0
 */
amr.resume();
/**
 * Integrate `play()` and `resume()`, if it is paused, continue, otherwise play from the beginning
 * @since 1.1.0
 */
amr.playOrResume();
/**
 * Integrate `resume()` and `pause()` to toggle the pause state
 * @since 1.1.0
 */
amr.pauseOrResume();
/**
 * Integrate play() , resume() , and pause()
 * @since 1.1.0
 */
amr.playOrPauseOrResume();
/**
 * Jump to the specified position of the audio, it will not change the playback status (if it is stopped, it is equivalent to `play(time)`)
 * @since 1.1.0
 * @param {Number} time the specified position（in seconds, float number）
 */
amr.setPosition(12.34);
/**
 * Get the current playback position (in seconds) 
 * @since 1.1.0
 * @return {Number} position, in seconds, float number
 */
amr.getCurrentPosition();
/**
 * If AMR was playing
 * @return {boolean}
 */
amr.isPlaying();
/**
 * If audio was paused
 * @since 1.1.0
 * @return {boolean}
 */
amr.isPaused();

Recording controls

/**
 * Start record
 */
amr.startRecord();
/**
 * Finish record, and then reformat to AMR
 * @return {Promise}
 */
amr.finishRecord();
/**
 * Cancel record
 */
amr.cancelRecord();
/**
 * If it was recording
 * @return {boolean}
 */
amr.isRecording();

Other APIs

/**
 * Get duration of the AMR (by second)
 * @return {Number}
 */
amr.getDuration();
/**
 * Get the Blob object of the AMR file (Use for download)
 * @return {Blob}
 */
amr.getBlob();
/**
 * Release AMR data and PCM data, stop recording, remove all event listeners
 * @since 1.1.4
 */
amr.destroy();
/**
 * Determine if the browser supports playback
 * Note that this is a static method
 * @since 1.1.0
 * @return {boolean}
 */
BenzAMRRecorder.isPlaySupported();
// NOT `amr.isPlaySupported();`
/**
 * Determine if the browser supports recording
 * Note that this is a static method
 * @since 1.1.0
 * @return {boolean}
 */
BenzAMRRecorder.isRecordSupported();
// NOT `amr.isRecordSupported();`

Todo list

  • Encode & decode with WebWorker.（v1.0.9）
  • Pause playback.（v1.1.0）
  • Pause recording.
  • Playing progress and jump to a position.（v1.1.0）
  • Browser compatibility check API (#9 #11).（v1.1.0）

License

MIT.