Decklink Tools

Decklink Tools

Context: $ARGUMENTS

Quick start

• List DeckLink devices: → Step 1 (decklink.py list-devices)
• List supported formats for a device: → Step 2 (decklink.py list-formats)
• Capture SDI/HDMI to a file: → Step 3 (decklink.py capture)
• Play a file out SDI/HDMI: → Step 4 (decklink.py play)
• Generate a test pattern out SDI/HDMI: → Step 5 (decklink.py signal-gen)
• Need the SDK headers for your own code? → Step 6 (decklink.py sdk-install)

When to use

• User has Blackmagic hardware (Mini Recorder, Mini Monitor, DeckLink 4K Pro, UltraStudio, etc.) plugged in and wants to capture or play SDI/HDMI.
• Need the exact device name ffmpeg expects (case-sensitive, quoted).
• Need to pick an SDI/HDMI mode by four-CC (Hp60, 4k60) or name.
• Generating continuous test bars on an SDI output for calibration.
• Use the companion decklink-docs skill to verify API / enum / option names.

Step 1 — List devices

DeckLink hardware is enumerated at the OS level by the Desktop Video driver. ffmpeg talks to it via the decklink indev/outdev.

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py list-devices

Under the hood this runs:

ffmpeg -hide_banner -f decklink -list_devices 1 -i dummy

Output lines look like [decklink @ ...] 'DeckLink Mini Recorder 4K'. The quoted string is the exact name to pass to -i or as output URL. Names are case-sensitive; spaces are significant.

Step 2 — List formats for one device

Display modes supported by a device depend on the hardware (HD-only vs 12G-SDI).

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py list-formats --device "DeckLink Mini Recorder 4K"

Under the hood:

ffmpeg -hide_banner -f decklink -list_formats 1 -i "DeckLink Mini Recorder 4K"

Output columns: mode index, four-CC, mode name, FPS. Use either the index (-format_code 23) or the four-CC (-format_code Hp60) — four-CCs are clearer and more portable.

Step 3 — Capture

Stream copy the DeckLink signal to a file without re-encoding (fastest path):

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py capture \
  --device "DeckLink Mini Recorder 4K" \
  --format Hp60 \
  --pixel uyvy422 \
  --out capture.mov

Expands to:

ffmpeg -f decklink -format_code Hp60 -raw_format uyvy422 \
       -i "DeckLink Mini Recorder 4K" \
       -c:v copy -c:a copy capture.mov

For 10-bit YUV (Rec.2020 HDR, film), pass --pixel v210. Width must be divisible by 48 for v210.

Re-encode during capture (useful when disk bandwidth is limited):

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py capture \
  --device "DeckLink Mini Recorder 4K" --format Hp60 \
  --encode prores_hq --out capture.mov

Encode presets: prores_proxy, prores_lt, prores_hq, h264_crf20, hevc_crf20, dnxhr_hq.

Step 4 — Playback

Play an existing file out SDI/HDMI via a DeckLink output card:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py play \
  --device "DeckLink Mini Monitor" \
  --in clip.mov \
  --format Hp60

Expands to:

ffmpeg -re -i clip.mov \
       -pix_fmt uyvy422 -vf scale=1920:1080,setsar=1 \
       -f decklink -format_code Hp60 "DeckLink Mini Monitor"

-re (read at native frame rate) is mandatory — without it ffmpeg feeds the DeckLink faster than the output clock and the card drops frames.

Step 5 — Signal generator (test pattern)

Generate continuous SMPTE bars + 1 kHz tone out SDI/HDMI:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py signal-gen \
  --device "DeckLink Mini Monitor" \
  --mode Hp60 \
  --pattern smptebars

Expands to:

ffmpeg -re \
  -f lavfi -i "smptebars=size=1920x1080:rate=60" \
  -f lavfi -i "sine=frequency=1000:sample_rate=48000" \
  -pix_fmt uyvy422 \
  -f decklink -format_code Hp60 "DeckLink Mini Monitor"

Patterns: smptebars, smptehdbars, testsrc, testsrc2, rgbtestsrc, color=black, color=gray.

Step 6 — SDK install (instructions only)

Writing your own C++ code against the DeckLink API needs the SDK headers, which live in a login-gated ZIP.

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py sdk-install

This prints — it does not download — the two links:

1. Desktop Video driver + runtime (no login): https://www.blackmagicdesign.com/support/family/capture-and-playback
2. Desktop Video SDK (free Blackmagic developer account required): https://www.blackmagicdesign.com/developer/product/capture-and-playback

Plus the standard install order: install the driver first, reboot, then unzip the SDK somewhere and point your build at <SDK>/Mac / Linux / Win. ffmpeg --enable-decklink --extra-cflags=-I/path/to/SDK/Linux/include on Linux.

Gotchas

• bmdcapture, BMDPlaybackSample, bmd_capture_tool are NOT official SDK sample names. bmdcapture / bmdplay come from the third-party github.com/lu-zero/bmdtools repo. Official sample directories are CapturePreview, LoopThroughPreview, SignalGenerator, StatusMonitor, DeviceList, TestPattern, 3DVideoFrames, StreamOperations, FrameServer, AudioMixer. Correct this if the user mentions those non-existent names.
• Device names are case-sensitive and contain spaces. Always quote: -i "DeckLink Mini Recorder 4K", never -i DeckLink-Mini-Recorder-4K.
• The decklink indev/outdev only exists if ffmpeg was built --enable-decklink. Homebrew ffmpeg does not enable it by default; you need a third-party tap or a source build with SDK headers present. Missing: Unknown input format: 'decklink'.
• The Desktop Video driver must be installed at runtime even when ffmpeg was built with the SDK. No libDeckLinkAPI.{so,dll,dylib} → ffmpeg errors at startup.
• v210 (bmdFormat10BitYUV) requires width divisible by 48. 1920 / 48 = 40, OK. Custom widths like 1936 will fail to open.
• -raw_format takes ffmpeg pix_fmt names, not SDK enum names. uyvy422 = bmdFormat8BitYUV, v210 = bmdFormat10BitYUV, argb = bmdFormat8BitARGB, bgra = bmdFormat8BitBGRA, r210 = bmdFormat10BitRGB.
• -format_code accepts four-CCs OR mode indexes. Four-CCs are 4 ASCII bytes; some are space-padded ('pal '). Trailing-space four-CCs are not shell-safe — use the index instead.
• Playback requires -re. Without native-rate read, the DeckLink card fills its hardware queue, underruns on switch-over, and emits visible glitches.
• Audio channels: DeckLink cards ship 2, 8, or 16 channels of embedded SDI audio. If you ask for 8-channel output but only have 2 tracks, ffmpeg pads silence; if you ask for 2 but receive 8, ffmpeg drops the extras silently. Match -channels to the source.
• -duplex_mode (full vs half). On cards with one connector that can do both input and output (DeckLink Studio 4K), you must set -duplex_mode full before using both directions simultaneously. Half duplex is default.
• Macs: Desktop Video installs libDeckLinkAPI.dylib into /Library/Frameworks/DeckLinkAPI.framework/. Ad-hoc ffmpeg builds need the framework on the rpath.
• Linux libgcc ABI mismatch: SDK samples compiled on one distro may fail on another with undefined reference to __cxa_*. Rebuild the samples on the target machine with the matching g++.

Examples

Example 1: "What DeckLink cards are plugged in?"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py list-devices

Example 2: "Record 1080p60 uncompressed from the Mini Recorder 4K"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py capture \
  --device "DeckLink Mini Recorder 4K" --format Hp60 --pixel uyvy422 \
  --out /tmp/grab.mov

Example 3: "Record 4K 60 HDR 10-bit from SDI to ProRes HQ"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py capture \
  --device "DeckLink 8K Pro" --format 4k60 --pixel v210 \
  --encode prores_hq --out hdr_grab.mov

Example 4: "Send SMPTE bars out my Mini Monitor for calibration"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py signal-gen \
  --device "DeckLink Mini Monitor" --mode Hp60 --pattern smptehdbars

Example 5: "Play back a ProRes master file out SDI at 29.97"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklink.py play \
  --device "DeckLink Mini Monitor" --in master.mov --format Hp29

Troubleshooting

Error: Unknown input format: 'decklink'

Cause: ffmpeg was not built --enable-decklink. Solution: Build from source with the SDK headers present, or install a decklink-enabled ffmpeg binary.

Error: Cannot find DeckLink device called 'DeckLink ...'

Cause: Exact name mismatch (extra space, wrong case) or driver not running. Solution: Run list-devices, copy-paste the exact string. Verify Desktop Video is installed and the card is lit.

Error: DeckLinkCaptureDelegate::VideoInputFrameArrived: DeckLink frame bad: 0x80000000

Cause: No incoming signal (unplugged cable, camera off, wrong format on sender). Solution: Use the StatusMonitor SDK sample, or run ffmpeg -f decklink -i "..." with -hide_banner and watch the first log line — it reports detected input format. Match -format_code to that.

Error: v210: width is not divisible by 48

Cause: Packed 10-bit YUV pixel layout requirement. Solution: Use -raw_format uyvy422 (8-bit) or scale first: -vf scale=1920:1080.

Frames drop during playback

Cause: Missing -re, or disk can't sustain raw-rate read. Solution: Add -re. If it's already there, pre-transcode the source to a codec decodable in real time (ProRes, DNxHR).

Error: Could not find any DeckLink card

Cause: Driver installed but kernel hasn't claimed the device, or Thunderbolt hub not powered. Solution: Reboot. Check Blackmagic Desktop Video Setup enumerates the card.

Reference docs

• For SDK interface names, enum values, and the full BMDDisplayMode table, invoke the decklink-docs skill (companion search + catalog).
• For ffmpeg decklink option reference: decklink-docs → search --query "..." --page ffmpeg-devices-decklink.