decklink-docs

name	decklink-docs
description	Look up Blackmagic DeckLink SDK docs at blackmagicdesign.com/developer: DeckLink C++ / COM-style API (DeckLinkAPI.h, DeckLinkAPI.idl), Desktop Video SDK (driver + runtime), DeckLink Arduino SDK. Core interfaces: IDeckLink, IDeckLinkInput, IDeckLinkOutput, IDeckLinkDisplayMode, IDeckLinkConfiguration, IDeckLinkNotification, IDeckLinkProfileAttributes. BMDPixelFormat (8BitYUV/10BitYUV/ARGB/BGRA/10BitRGB/r210/v210), BMDDisplayMode (SD/HD/2K/UHD/4K/8K). Relationship to ffmpeg decklink demuxer/muxer. Use when the user asks to look up a DeckLink API, check supported pixel formats or display modes, verify an IDeckLinkInput or IDeckLinkOutput method, or find Blackmagic SDK documentation.
argument-hint	[query]

Decklink Docs

Context: $ARGUMENTS

Quick start

• Find an API / interface / BMD enum: → Step 2 (search --query <term>)
• Read one full section: → Step 3 (section --page <name> --id <anchor>)
• Grab the whole page: → Step 4 (fetch --page <name>)
• Prime the cache offline: → Step 5 (index)
• Verify the ffmpeg decklink device options: → search on page ffmpeg-devices

When to use

• User asks "what does IDeckLinkInput::StartStreams return?" or "what pixel formats does a Mini Recorder accept?"
• Need to verify an interface / method / enum exists before recommending C++ / COM code.
• Need the exact ffmpeg -f decklink option list (the ffmpeg decklink demuxer / muxer docs).
• Need to cite the canonical Blackmagic SDK URL in a response.
• Before writing any non-trivial DeckLink integration, check the current doc for the interface you're using.

---

Step 1 — Know the page catalog

The script only works against a fixed list of known Blackmagic / related doc pages. Get the list:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py list-pages

The catalog groups into four areas:

Page family	What's covered
blackmagic-developer / blackmagic-capture-playback	Landing pages. The SDK ZIP is login-gated; URLs are catalog stubs.
ffmpeg-devices-decklink / ffmpeg-devices	The ffmpeg decklink demuxer + muxer (options, examples).
decklink-sdk-readme-*	Third-party mirrors of SDK sample names + API index (informational only).
bmdtools-github	Third-party bmdtools (the tool that ships bmdcapture / bmdplay).

Read references/catalog.md for the full page list with descriptions and login-gated notes.

---

Step 2 — Search first (default workflow)

When the user names an interface, enum, method, or option, search across all pages:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py search --query "IDeckLinkInput" --limit 5

Scope to a page for less noise:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py search --query "list_formats" --page ffmpeg-devices-decklink

Output format per hit:

--- <page>:<line> — <nearest heading>
<canonical URL with anchor>
<snippet with ±3 lines of context>

First run downloads the page (~1–2s). Subsequent runs hit the local cache (~/.cache/decklink-docs/) — instant.

Use --format json for machine-parseable output when chaining.

---

Step 3 — Read one section in full

When a search hit lands on an interface / option and you want the whole block:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py section --page ffmpeg-devices-decklink --id decklink

--id accepts either the anchor id printed in search results as [§xxxx] or a heading keyword.

---

Step 4 — Fetch a whole page

Rarely needed — usually overkill. Use when you need the entire page text:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py fetch --page ffmpeg-devices-decklink

Pair with --format json for structured handoff.

---

Step 5 — Prime the cache (optional)

For reliable offline lookups or before a burst of queries:

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py index

Fetches every known page, stores text-extracted versions in ~/.cache/decklink-docs/. Some Blackmagic developer pages may fail with 403 when unauthenticated — the script keeps going and reports failures.

Override cache location: export DECKLINK_DOCS_CACHE=/path/to/dir. Clear: uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py clear-cache.

---

Gotchas

• The Blackmagic SDK download itself is login-gated. https://www.blackmagicdesign.com/developer/product/capture-and-playback renders a product page only; the SDK ZIP with DeckLinkAPI.h / DeckLinkAPI.idl + Samples/ tree requires free account + terms acceptance. The script catalogs these URLs but cannot fetch the SDK contents directly. Tell the user to register once.
• bmdcapture / BMDPlaybackSample are NOT official SDK sample names. bmdcapture ships with third-party bmdtools (github.com/lu-zero/bmdtools). The actual official SDK Samples/ are: CapturePreview, LoopThroughPreview, SignalGenerator, StatusMonitor, DeviceList, TestPattern, 3DVideoFrames, StreamOperations, FrameServer, AudioMixer.
• The DeckLink API is COM-style on all platforms, not just Windows. Use CreateDeckLinkIteratorInstance() on macOS/Linux — the SDK includes a cross-platform shim so QueryInterface / AddRef / Release work the same way.
• Release order matters. COM-style reference counting: every interface obtained via QueryInterface must be Release()-d. Leaking an IDeckLinkDisplayMode across frames crashes the driver.
• ffmpeg must be built --enable-decklink and the runtime driver (libDeckLinkAPI.so / DeckLinkAPI.dll / DeckLinkAPI.dylib in /Library/Frameworks) must be installed. Missing either produces Unknown input format: 'decklink'.
• Pixel format mapping from SDK → ffmpeg: bmdFormat8BitYUV = uyvy422, bmdFormat10BitYUV = v210, bmdFormat10BitRGB = r210, bmdFormat8BitARGB = argb, bmdFormat8BitBGRA = bgra. Never mix SDK enum names with ffmpeg pixel-format names.

---

Examples

Example 1 — "What options does ffmpeg's decklink demuxer take?"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py section --page ffmpeg-devices-decklink --id decklink

Example 2 — "Which BMDPixelFormat values exist?"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py search --query "BMDPixelFormat" --limit 5

Example 3 — "What's the official SDK sample for a preview window?"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py search --query "CapturePreview" --limit 5

(Correct answer: Samples/CapturePreview/ — not bmdcapture. See Gotchas.)

Example 4 — "How do I list DeckLink devices from ffmpeg?"

uv run ${CLAUDE_SKILL_DIR}/scripts/decklinkdocs.py search --query "list_devices" --page ffmpeg-devices-decklink

Cite the command: ffmpeg -f decklink -list_devices 1 -i dummy.

---

Troubleshooting

Error: unknown page: foo

Cause: Name isn't in the catalog. Solution: list-pages to see valid names.

Error: HTTPError: 403 when fetching a Blackmagic dev URL

Cause: That page is behind the developer login wall. Solution: Use the general landing / ffmpeg-side pages; register a free Blackmagic developer account to download the actual SDK ZIP.

Error: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]

Cause: System cert store out of date. Solution: Update certifi or run Python's Install Certificates.command. Do NOT disable SSL verification.

Search returns zero hits

Cause: Term doesn't exist on the catalog's pages (most SDK internals are inside the login-gated ZIP, not on the web). Solution: Drop --page to search all; if still empty, the term lives in the SDK header files and requires downloading the SDK.

Results look truncated

Cause: HTML → text extraction flattens tables. Solution: Open the canonical URL printed in the hit header for the authoritative view.