API.md

Webcast.js API

webcast.js involves several cutting-edge technologies and, thus, require a fairly modern browser. Here's a quick summary of the technologies required:

• WebSocket API: This is the transport layer. It is readily available in most modern browsers.
• Web Audio API: This is the API used to manipulate audio and video data inside the browser. It is currently implemented in Chrome and in Firefox Nightly.
• asm.js: This is the techonology used to optimize the mp3 encoder. It is currently only supported by Firefox though Chrome is starting to show good performances with it.

The API

The library contains several classes:

• Webcast.Encoder.Raw: encoder returning raw s8 samples.
• Webcast.Encoder.Mp3: encoder returning mp3 data. Requires libshine.js.
• Webcast.Encoder.Resample: a wrapper to resample encoder's input. Requires libsamplerate.js.
• Webcast.Encoder.Asynchronous: a wrapper to encode in a Web Worker
• Webcast.Socket: a simple wrapper around WebSockets that implements the webcast protocol.
• AudioContext::createWebcastSource: a wrapper to create a webcast node, in-par with the Web Audio API.

How to use?

Here's a simple use of the library:

var source = (...);

var encoder = new Webcast.Encoder.Mp3({
  channels: 2,
  samplerate: 44100,
  bitrate: 128
});

if (inputSampleRate !== 44100) {
  encoder = new Webcast.Encoder.Resample({
    encoder:    encoder,
    samplerate: inputSampleRate
  });
}

if (useWorker) {
  encoder = new Webcast.Encoder.Asynchronous({
    encoder: encoder,
    scripts: ["http://bla.com/webcast.js", ...], // full path to required scripts for the worker.
                                                 // usually includes requires encoders and webcast.js
  });
}

var context = new AudioContext;

var webcast = context.createWebcastSource(4096, 2);

source.connect(webcast);
webcast.connect(audioContext.destination);

webcast.connectSocket(encoder, "ws://localhost:8080/mount");

webcast.sendMetadata({
  title:  "My Awesome Stream",
  artist: "The Dude"
});

//... Later ...
webcast.close(function () {
  console.log("connection closed!");
});

You can also look at the example client code for a more detailed use of the library.