How do I install macadam on MacOS Mojave?

After installing Node.js and Blackmagic Desktop Video software, run xcode-select --install and install the macOS SDK headers package as specified in the README to handle native addon compilation.

Macadam vs using the Blackmagic SDK directly?

Macadam provides a higher-level, promise-based JavaScript API that abstracts the low-level DeckLink SDK, making it easier for Node.js developers but with less direct control and potential performance overhead compared to C++ integrations.

How to capture video with audio using macadam?

Use the capture method with parameters like channels, sampleRate, and sampleType set, as shown in the README example, to asynchronously retrieve both video frames and audio packets in a single frame object.

Does macadam support external keying for live graphics?

Yes, on devices that support it, you can enable external keying by setting isExternal to true in playback options, with key levels adjustable via setLevel or ramp methods for smooth transitions.

How to handle timecode drop frame formats in macadam?

Timecode strings must use colons for non-drop frame (e.g., HH:MM:SS:FF) and semicolons for drop frame (e.g., HH:MM:SS;FF), as detailed in the timecode section, to ensure proper insertion and retrieval on supported hardware.

Open-Awesome

Macadam

Apache-2.0C++

Node.js bindings for asynchronous capture and playback with Blackmagic Design video devices.

GitHub

124 stars29 forks0 contributors

What is Macadam?

Macadam is a Node.js native addon that provides asynchronous bindings to Blackmagic Design capture and playback devices. It allows developers to read video/audio from capture cards and output to playback hardware using a simple JavaScript API, supporting features like keying, timecode, and device configuration.

Target Audience

Node.js developers building video applications that interface with Blackmagic hardware, such as live streaming systems, video processing pipelines, broadcast tools, or media servers.

Value Proposition

It offers a high-level, promise-based API that abstracts the low-level DeckLink SDK, enabling rapid development of cross-platform video applications without sacrificing performance or hardware capabilities.

Overview

Async node.js interface to Blackmagic Design capture and playback devices.

Use Cases

Best For

Building custom live video switching software with Node.js
Creating video capture applications for recording or streaming
Developing playback systems for video walls or broadcast output
Integrating Blackmagic hardware into Node.js media servers
Adding keying/graphics overlay capabilities to video workflows
Synchronizing multiple video sources with timecode

Not Ideal For

Projects using non-Blackmagic video capture or playback hardware
Teams needing GUI-based video tools without coding their own interface
Applications requiring Blackmagic USB3 device support on Linux
Real-time video processing systems where Node.js event loop overhead is a concern

Pros & Cons

Pros

Asynchronous Promise-Based API

Uses async/await patterns for straightforward capture and playback of video frames and audio packets, as demonstrated in the README examples with promise-based frame retrieval.

Cross-Platform Compatibility

Supports Linux, Windows, and macOS with Blackmagic Desktop Video software, enabling consistent development across major operating systems as stated in the installation prerequisites.

Professional Video Features

Includes keying support for graphics overlays with alpha control and comprehensive timecode handling, essential for broadcast and live production workflows detailed in the keying and timecode sections.

Extensive Device Configuration

Allows programmatic control over DeckLink device parameters via getDeviceConfig and setDeviceConfig, offering fine-grained hardware management beyond the Desktop Video Setup utility.

Cons

Complex Native Addon Setup

Requires Blackmagic SDK, node-gyp, a C/C++ development kit, and Python 2.7, making installation and compilation more involved than pure JavaScript modules, as noted in the prerequisites.

Hardware and Platform Limitations

Only works with Blackmagic devices, and USB3 devices are explicitly unsupported on Linux, restricting hardware flexibility and cross-vendor compatibility.

Experimental Asynchronous Features

Relies on Node.js experimental N-API features in older versions, which could lead to instability or breaking changes, as mentioned in the status section.

Frequently Asked Questions

Related Projects

ffplayout

Rust and ffmpeg based playout

Stars569

Forks141

Last commit18 hours ago

Sofie - TV Automation

The Sofie TV Studio Automation System, used in live TV news production by the Norwegian public service broadcaster NRK since September 2018

Stars427

Forks39

Last commit7 months ago

SPX - Graphics Controller

SPX is a graphics control client for live video productions and live streams using CasparCG, OBS, vMix, or similar software.

Stars416

Forks86

Last commit1 month ago

Open Playout Automation

Television broadcast automation system

Stars215

Forks40

Last commit2 months ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub