BinaryJS

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.

• BinaryPack serialization format is fast, binary, and JSON-type compatible. Data stays binary end to end
• Automatically chunks large binary data buffers for streaming performance
• Send multiple streams of data concurrently over multiplexed websocket connection
• API implements Node.js read/write Streams. You can pipe any stream into BinaryJS streams (and vice-versa)
• "pause," "resume," and "end" as in the Streams API

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.

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);
  }); 
});

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!):

• Realtime multiplayer video games without expensive stringifying
• Streaming FLAC into HTML5 WebAudio api
• Progressive image loading (for retina displays and high-res photorgraphy)
• Streaming file uploads Example
• Live HTML <video> streaming
• PJAX with no HTTP requests. Not even for image assets
• Video / audio chat over websockets

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

• Improved BinaryPack serialization performance, including a native C++ module for node-binarypack
• Fallbacks (either with Flash or XHR2) for non-binary-websocket browsers
• iOS and Android clients
• Ruby, Python, Java servers

Limitations and issues

• Currently supports Chrome 15+ and Firefox 11+, IE10. Fallbacks that will support Safari, mobile iOS and Android, and older FF/Chrome versions are in the works
• Performance is largely untested. Though BinaryPack serialization results in smaller data, I have not compared to native JSON serialization performance. C++ BinaryPack Node.js module is in the works

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.