BinaryJS

Realtime binary streaming for the web using websockets

Get Started

Documentation

Examples / Demos

GitHub / Twitter

Binary data for the web is here

BinaryJS is bidrectional realtime binary data with binary websockets

A year ago if someone asked you "how do I stream binary data / audio / video / files to Javascript?" the answer would have been "Flash" or "no" (or "Java applets")

But as of Chrome 15+, Firefox 11+, Internet Explorer 10, and Safari nightly builds, that is no longer true.

BinaryJS is a lightweight framework that utilizes websockets to send, stream, and pipe binary data bidirectionally between browser javascript and Node.js.

Show me the API

BinaryJS allows multiple streams (of pure binary data!) over a single realtime websocket connection. Either the client or server can create a stream that both client and server can write to.

Node.js server
var server = BinaryServer({port: 9000});
server.on('connection', function(client){
  client.on('stream', function(stream, meta){
    var file = fs.createWriteStream(meta.file);
    stream.pipe(file);
  }); 
});
Browser:
var client = BinaryClient('ws://localhost:9000');
client.on('open', function(stream){
  var stream = client.createStream({file: 'hello.txt'});
  stream.write('Hello');
  stream.write('World!');
  stream.end();
});

View the "Getting Started" guide

View the API reference

View the "Hello world" example

See more examples

What can you do with this?

You have just as much flexibility as a full TCP socket between client and server

Here are some ideas that are now possible (beta-testers are already working on some!):

Additional details

BinaryJS employs `BinaryPack` a modified version of the MessagePack protocol. The Node.js server uses a modified version of the `ws` library enhanced to pass through the status of the socket buffer so adherence to Node.js Stream API is possible.

Both the server and the client can write or accept any arbitrary JSON type or structure – Objects, arrays, null, booleans, strings – and also binary data. Because BinaryPack is a binary protocol, the wire format has negligible serialization/deserialization overhead for large chunks of binary data. This also means binary data types such as Buffer in Node.js and Blob or ArrayBuffer in the client can be serialized and deserialized (without the inefficiencies of JSON or Base64!).

On the client, feature detection is employed to choose between using BlobBuilder, the Blob constructor, and ArrayBufferViews or ArrayBuffers themselves for assembling Blobs for transport.

When using `stream.write` data chunking is up to the caller. When a stream is piped, it is up to the source stream to chunk data. When sending a larger binary type using `client.send` a new stream is created and the buffer will piped into the stream in chunks automatically.

For piped streams, BinaryJS correctly provides boolean return values from `stream.write` calls so that if the socket buffer is full, the incoming stream is paused. This powerful cascade of stream throttling allows large streams to be transferred without excessive memory use.

Future plans

The items below are in no particular order. If you would like to contribute go ahead and issue a pull request or email me at really.ez+1010@gmail.com

Limitations and issues

Support and questions

If you want you can email me at really.ez+1010@gmail.com

Please file a GitHub issue for the bugs you find.

Fork me on GitHub