Skip to content

Latest commit

 

History

History
128 lines (98 loc) · 4.87 KB

README.md

File metadata and controls

128 lines (98 loc) · 4.87 KB
Raw

vmsg npm

vmsg is a small library for creating voice messages. While traditional way of communicating on the web is via text, sometimes it's easier or rather funnier to express your thoughts just by saying it. Of course it doesn't require any special support: record your voice with some standard program, upload to file hosting and share the link. But why bother with all of that tedious stuff if you can do the same in browser with a few clicks.

🎊 🎉 DEMO 🎉 🎊

Features

  • No dependencies, framework-agnostic, can be easily added to any site
  • Small: ~73kb gzipped WASM module and ~3kb gzipped JS + CSS
  • Uses MP3 format which is widely supported
  • Works in all latest browsers

Supported browsers

  • Chrome 32+
  • Firefox 27+
  • Safari 11+
  • Edge 12+

Usage

npm install vmsg --save

import { record } from "vmsg";

someButton.onclick = function() {
  record(/* {wasmURL: "/static/js/vmsg.wasm"} */).then(blob => {
    console.log("Recorded MP3", blob);
    // Can be used like this:
    //
    // const form = new FormData();
    // form.append("file[]", blob, "record.mp3");
    // fetch("/upload.php", {
    //   credentials: "include",
    //   method: "POST",
    //   body: form,
    // }).then(resp => {
    // });
  });
};

That's it! Don't forget to include vmsg.css and vmsg.wasm in your project. For browsers without WebAssembly support you need to also include wasm-polyfill.js.

See demo directory for a more feasible example.

A minimal React example for using Recorder with your own UI can be found here.

See also non React demo and Recording mp3 audio in HTML5 using vmsg article.

Development

  1. Install Emscripten SDK.
  2. Install latest LLVM, Clang and LLD with WebAssembly backend, fix LLVM_ROOT variable of Emscripten config.
  3. Make sure you have a standard GNU development environment.
  4. Activate emsdk environment.
  5. git clone --recurse-submodules https://github.com/Kagami/vmsg.git && cd vmsg
make clean all
npm install
npm start

These instructions are very basic because there're a lot of systems with different conventions. Docker image would probably be provided to fix it.

Technical details for nerds

vmsg uses LAME encoder underneath compiled with Emscripten to WebAssembly module. LAME build is optimized for size, weights only little more than 70kb gzipped and can be super-efficiently fetched and parsed by browser. It's like a small image.

Access to microphone is implemented with Web Audio API, data samples sent to Web Worker which is responsibe for loading WebAssembly module and calling LAME API.

Module is produced with modern LLVM WASM backend and LLD linker which should become standard soon, also vmsg has own tiny WASM runtime instead of Emscripten's to decrease overall size and simplify architecture. Worker code is included in the main JS module so end-user has to care only about 3 files: vmsg.js, vmsg.css and vmsg.wasm. CSS can be inlined too but IMO that would be ugly.

In order to support browsers without WebAssembly, WebAssembly polyfill is being used. It translates binary module into semantically-equivalent JavaScript on the fly (almost asm.js compatible but doesn't fully validate yet) so we don't need separate asm.js build and can use standard WebAssembly API. It's not as effecient but for audio encoding should be enough.

See also: Creating WebAssembly-powered library for modern web article.

Why not MediaRecorder?

MediaStream Recording API is great but:

  • Works only in Firefox and Chrome
  • Provides little to no options, e.g. VBR quality can't be specified
  • Firefox/Chrome encode only to Opus which can't be natively played in Safari and Edge

But you can use e.g. ogv.js polyfill!

  • It make things more complicated, now you need both encoder and decoder
  • Opus gives you ~2x bitrate win but for 500kb per minute files it's not that much
  • MP3 is much more widespread, so even while compression is not best compatibility matters

License

vmsg is licensed under CC0.
LAME is licensed under LGPL.
MP3 patents seems to have expired since April 23, 2017.