Macadam

Prototype bindings to link Node.js and the Blackmagic Desktop Video SDK, enabling asynchronous capture and playback to and from Blackmagic Design devices via a simple Javascript API.

This is prototype software and is not yet suitable for production use. Currently supported platforms are Mac and Windows. Linux support is now available but is experimental and the getFirstDevice() call does not work as expected.

Why macadam? Tarmacadam is the black stuff that magically makes roads, so it seemed appropriate as a name for a steampunk-style BlackMagic binding.

Installation

Macadam has a number of prerequisites:

Install Node.js for your platform. This software has been developed against the long term stable (LTS) release.
Install the latest version of the Blackmagic Desktop Video SDKs for your platform, available from https://www.blackmagicdesign.com/support.
Install node-gyp and make sure that you have the prerequisites for compiling Javascript addons for your platform. This requires a C/C++ development kit and python v2.7.

Macadam is designed to be used as a module included into another project. To include macadam into your project:

npm install --save macadam

Using macadam

To use macadam, require the module. Capture and playback operations are illustrated below.

Capture

The macadam capture class is an event emitter that produces buffers containing video frames. Make sure you release the reference quickly (within ten frames or so) so that the frame data is garbage collected.

var macadam = require('macadam');

// First argument is the DeckLink device number.
// Set appropriate values from display mode and pixel format from those macadam provides.
var capture = new macadam.Capture(0, macadam.bmdModeHD1080i50, macadam.bmdFormat10BitYUV);

// If audio capture is required, call the following method on capture
// First param is the audio sample rate, second is bits per sample, third in number of channels
// Defaults are shown. BMD hardware only supports: 48kHz; 16 or 32 bits; 2, 8 or 16 channels.
capture.enableAudio(macadam.bmdAudioSampleRate48kHz, macadam.bmdAudioSampleType16bitInteger, 2);

capture.on('frame', function (videoData, audioData) {
  // Do something with each frame received.
  // videoData is a node.js Buffer, and may be null if only audio is provided
  // audioData is a node.js Buffer, or null is audio is not enabled/available
});

capture.on('error', function (err) {
  // Handle errors found during the capture.
});

capture.start(); // Start capture.

// ... eventually ...
capture.stop(); // Stop capture.

The ancillary data inputs of the card are not yet supported.

Playback

The playback event emitter works by sending a sequence of frame buffers and frame-sized chunks of interleaved audio data as node.js Buffer objects to a playback object. For smooth playback, build a few frames first and then keep adding frames as they are played. A played event is emitted each time playback of a frame is complete.

Take care not to hold on to frame buffer references so that they can be garbage collected.

var macadam = require('macadam');

// First argument is the DeckLink device number.
// Set appropriate values from display mode and pixel format from those macadam provides.
var playback = new macadam.Playback(0, macadam.bmdModeHD1080i50, macadam.bmdFormat10BitYUV);

// If you want to play audio alongside the video, enable audio
// First param is the audio sample rate, second is bits per sample, third in number of channels
// Defaults are shown. BMD hardware only supports: 48kHz; 16 or 32 bits; 2, 8 or 16 channels.
playback.enableAudio(macadam.bmdAudioSampleRate48kHz, macadam.bmdAudioSampleType16bitInteger, 2);

playback.frame( /* first frame */, /* opt frame of audio */);
playback.frame( /* second frame */, /* opt frame of audio */);
// Add more here to have a larger buffer to ensure smooth playback

playback.on('played', function (x) {
  // Use this callback to send next frame, or use an accurate timer. See note below
});

playback.on('error', function (err) {
  // Handle errors found during playback.
});

// start playback, typically after 4-10 frames have been accumulated
playback.start();

// ... eventually ...
playback.stop();

Ancillary data outputs of the card are not yet supported.

Note that experience shows that the played event is not a good way to clock the sending of frames to the video card. It provides an indication that the frame has played. It is best to send frames to the card regularly based on a clock, such as deriving a setTimeout interval from process.hrtime().

Check the DeckLink API version

To check the DeckLinkAPI version:

var macadam = require('macadam');
console.log(macadam.deckLinkVersion());

Modes and formats

The Blackmagic mode and format enumerations are available as constants, as in the examples shown above: macadam.bmdModeHD1080i50 and macadam.bmdFormat10BitYUV. For more information on the modes, see the Blackmagic DeckLink API documentation provided with the Blackmagic SDK. Note that not all cards support every mode and format.

A set of utility functions are provided that allow access to the mode functions. In summary, there are:

modeWidth, modeHeight, modeGrainDuration and modeInterlace: Extract parameters from a Blackmagic mode.
formatDepth, formatFourCC, formatSampling and formatColorimetry: Extract parameters from a Blackmagic format.

Status, support and further development

This is prototype software that is not yet suitable for production use. The software is being actively tested and developed.

A variant for the Linux platform is also available but still in an experimental stage.

Contributions can be made via pull requests and will be considered by the author on their merits. Enhancement requests and bug reports should be raised as github issues. For support, please contact Streampunk Media. For updates follow @StrmPunkd on Twitter.

License

The software links to the BlackMagic Desktop Video libraries. Include files and examples from which this code is derived include the BlackMagic License in their respective header files. The BlackMagic DeckLink SDK can be downloaded from https://www.blackmagicdesign.com/support.

dericed/macadam