Stabilize DeckLink Linux support and require Desktop Video 15.x+

[xShirae]

• ## Summary

This PR stabilizes the Blackmagic DeckLink output plugin on Linux by improving runtime detection, hardening callback and teardown
behavior, tightening error handling, and narrowing Linux support to Blackmagic Desktop Video 15.x+.

The end result is a simpler and safer integration path:

• modern DeckLink runtime only on Linux
• clean failure behavior on unsupported drivers
• safer callback, cleanup, and long-running playback behavior
• clearer and less repetitive logging

Problem

We were seeing multiple reliability issues in the DeckLink integration on Linux:

• older Linux driver/runtime combinations were not reliably compatible with the DeckLink ABI path used by xStudio
• startup failures on legacy runtimes could cascade into unsafe cleanup and crashes
• callback registration and COM-style interface handling were fragile
• the code path still had leak/race risks even on the supported modern runtime
• unsupported-runtime logs were repetitive and hard to read

From testing:

• Blackmagic Desktop Video 15.3.1 worked
• 14.2.1 still failed at SetAudioCallback
• older runtimes such as 12.1.2 were clearly unsupported

Because the requirement is to support both audio and video output, “best effort” compatibility on older runtimes was not
sufficient.

What We Tried Before

Before adopting the final policy, we tried to preserve Linux backward compatibility.

1. Linux ABI fallback

We added a Linux fallback path to probe older DeckLink ABI/interface behavior when the modern output interface was unavailable.

2. Version-gated compatibility

We then narrowed that experiment to a specific compatibility window around 14.2.1 through 14.x, while rejecting anything older.

3. Focused diagnostics

We added HRESULT logging around:

• runtime/interface probing
• callback registration
• output enablement
• preroll/startup

That investigation showed a consistent pattern on 14.2.1:

• modern output interface query failed
• legacy output interface query succeeded
• video callback registration succeeded
• audio callback registration failed at SetAudioCallback

4. Minimal callback refactor

We also split the old mixed audio/video callback object into separate callback objects so the legacy path was not using one
combined object for both registrations.

Why We Reverted To Strict 15.x+ Support

After testing and narrowing the issue, we concluded that maintaining Linux 14.x compatibility was not a good tradeoff.

Reasons:

• 15.3.1 worked reliably
• 14.2.1 still did not provide a stable audio+video path
• supporting the legacy ABI was turning into ongoing ABI maintenance rather than a contained fix
• even after reducing crashes, we still could not prove that 14.x was a reliable supported runtime for the full DeckLink feature
  set
• the product requirement is not just “launch without crashing”; it is “use the Blackmagic card correctly with both audio and
  video”

So this PR makes the support policy explicit:

• Linux DeckLink support requires Blackmagic Desktop Video 15.x+
• older or unparsable runtimes are rejected early with a clear upgrade message

Code Changes

Runtime diagnostics

Added explicit DeckLink runtime detection and reporting, including:

• API version
• loaded runtime/library details
• selected output interface info
• stored last error for UI/status propagation

This made Linux driver/runtime mismatches diagnosable instead of opaque.

Callback/interface correctness

Improved COM-style callback behavior and then split callback responsibilities:

• AVOutputCallback is now video-only
• AudioOutputCallback is now audio-only

This removed the old mixed callback object and made registration/lifetime handling cleaner.

Startup and teardown hardening

Added explicit startup-state tracking for:

• video output enabled
• audio output enabled
• scheduled playback started

Cleanup now uses those states instead of assuming all startup stages completed successfully.

Strict Linux runtime policy

Linux runtime gating now:

• parses the detected DeckLink API version
• requires 15.0.0+
• rejects older or unparsable runtimes
• does not execute the old Linux v14.2.1 compatibility path

Supported-path robustness fixes

The supported modern path was then hardened further:

• callback entrypoints no longer throw through the DeckLink driver boundary
• callback unregister happens before output-interface release
• several per-frame COM/interface leaks were fixed
• HDR metadata access is now copied under lock to avoid races
• mutex usage in the video callback path was improved with RAII-based locking

Logging cleanup

Reduced noisy duplicate logs by:

• removing repeated unsupported-runtime messages
• removing raw stderr echoes from the DeckLink init failure path
• trimming the plugin-level follow-up warning
• suppressing low-level Linux compatibility fallback banners that were no longer meaningful once 14.x was unsupported

User-Facing Behavior

On Linux with Desktop Video 15.x+

• DeckLink initializes normally
• the modern DeckLink output path is used
• audio/video output remains supported

On Linux with older Desktop Video runtimes

• xStudio stays up
• the DeckLink plugin disables itself cleanly
• logs/UI clearly tell the user to upgrade Blackmagic Desktop Video drivers to 15.x+

Rationale

In short:

• we first tried compatibility
• we instrumented and narrowed the problem
• we verified the modern runtime works
• we concluded legacy Linux support was not dependable enough
• we finalized on a strict 15.x+ policy and hardened the supported path

Testing Notes

Validated during investigation:

• 15.3.1 initializes successfully
• 14.2.1 reaches runtime probing but fails in the legacy path
• older runtimes are not viable for full support

Expected behavior after this PR:

• 15.x+ works normally
• older Linux runtimes fail cleanly with an upgrade message, without attempting unsupported DeckLink execution paths

› don't say "we" but "I" instead

• ## Summary

This PR stabilizes the Blackmagic DeckLink output plugin on Linux by improving runtime detection, hardening callback and teardown
behavior, tightening error handling, and narrowing Linux support to Blackmagic Desktop Video 15.x+.

The end result is a simpler and safer integration path:

• modern DeckLink runtime only on Linux
• clean failure behavior on unsupported drivers
• safer callback, cleanup, and long-running playback behavior
• clearer and less repetitive logging

Problem

I was seeing multiple reliability issues in the DeckLink integration on Linux:

• older Linux driver/runtime combinations were not reliably compatible with the DeckLink ABI path used by xStudio
• startup failures on legacy runtimes could cascade into unsafe cleanup and crashes
• callback registration and COM-style interface handling were fragile
• the code path still had leak/race risks even on the supported modern runtime
• unsupported-runtime logs were repetitive and hard to read

From testing:

• Blackmagic Desktop Video 15.3.1 worked
• 14.2.1 still failed at SetAudioCallback
• older runtimes such as 12.1.2 were clearly unsupported

Because the requirement is to support both audio and video output, “best effort” compatibility on older runtimes was not
sufficient.

What I Tried Before

Before adopting the final policy, I tried to preserve Linux backward compatibility.

1. Linux ABI fallback

I added a Linux fallback path to probe older DeckLink ABI/interface behavior when the modern output interface was unavailable.

2. Version-gated compatibility

I then narrowed that experiment to a specific compatibility window around 14.2.1 through 14.x, while rejecting anything older.

3. Focused diagnostics

I added HRESULT logging around:

• runtime/interface probing
• callback registration
• output enablement
• preroll/startup

That investigation showed a consistent pattern on 14.2.1:

• modern output interface query failed
• legacy output interface query succeeded
• video callback registration succeeded
• audio callback registration failed at SetAudioCallback

4. Minimal callback refactor

I also split the old mixed audio/video callback object into separate callback objects so the legacy path was not using one
combined object for both registrations.

Why I Reverted To Strict 15.x+ Support

After testing and narrowing the issue, I concluded that maintaining Linux 14.x compatibility was not a good tradeoff.

Reasons:

• 15.3.1 worked reliably
• 14.2.1 still did not provide a stable audio+video path
• supporting the legacy ABI was turning into ongoing ABI maintenance rather than a contained fix
• even after reducing crashes, I still could not prove that 14.x was a reliable supported runtime for the full DeckLink feature
  set
• the product requirement is not just “launch without crashing”; it is “use the Blackmagic card correctly with both audio and
  video”

So this PR makes the support policy explicit:

• Linux DeckLink support requires Blackmagic Desktop Video 15.x+
• older or unparsable runtimes are rejected early with a clear upgrade message

Code Changes

Runtime diagnostics

I added explicit DeckLink runtime detection and reporting, including:

• API version
• loaded runtime/library details
• selected output interface info
• stored last error for UI/status propagation

This made Linux driver/runtime mismatches diagnosable instead of opaque.

Callback/interface correctness

I improved COM-style callback behavior and then split callback responsibilities:

• AVOutputCallback is now video-only
• AudioOutputCallback is now audio-only

This removed the old mixed callback object and made registration/lifetime handling cleaner.

Startup and teardown hardening

I added explicit startup-state tracking for:

• video output enabled
• audio output enabled
• scheduled playback started

Cleanup now uses those states instead of assuming all startup stages completed successfully.

Strict Linux runtime policy

Linux runtime gating now:

• parses the detected DeckLink API version
• requires 15.0.0+
• rejects older or unparsable runtimes
• does not execute the old Linux v14.2.1 compatibility path

Supported-path robustness fixes

I then hardened the supported modern path further:

• callback entrypoints no longer throw through the DeckLink driver boundary
• callback unregister happens before output-interface release
• several per-frame COM/interface leaks were fixed
• HDR metadata access is now copied under lock to avoid races
• mutex usage in the video callback path was improved with RAII-based locking

Logging cleanup

I reduced noisy duplicate logs by:

• removing repeated unsupported-runtime messages
• removing raw stderr echoes from the DeckLink init failure path
• trimming the plugin-level follow-up warning
• suppressing low-level Linux compatibility fallback banners that were no longer meaningful once 14.x was unsupported

User-Facing Behavior

On Linux with Desktop Video 15.x+

• DeckLink initializes normally
• the modern DeckLink output path is used
• audio/video output remains supported

On Linux with older Desktop Video runtimes

• xStudio stays up
• the DeckLink plugin disables itself cleanly
• logs/UI clearly tell the user to upgrade Blackmagic Desktop Video drivers to 15.x+

Rationale

This PR intentionally favors a known-good, supportable Linux DeckLink integration over continued investment in a legacy ABI path
that never reached reliable audio+video operation.

In short:

• I first tried compatibility
• I instrumented and narrowed the problem
• I verified the modern runtime works
• I concluded legacy Linux support was not dependable enough
• I finalized on a strict 15.x+ policy and hardened the supported path

Testing Notes

Validated during investigation:

• 15.3.1 initializes successfully
• 14.2.1 reaches runtime probing but fails in the legacy path
• older runtimes are not viable for full support

Expected behavior after this PR:

• 15.x+ works normally
• older Linux runtimes fail cleanly with an upgrade message, without attempting unsupported DeckLink execution paths

[linux-foundation-easycla]

• ✅ login: xShirae / name: xShirae (312d71f, 326793f, b5bc09f)
• ❌ The email address for the commit (00beffe, 36472d2, 7e2e173, 9077af4, 90c6c4b, b9dd0b5, cc03487, e5362f9, f343876) is not linked to the GitHub account, preventing the EasyCLA check. Consult this Help Article and GitHub Help to resolve. (To view the commit's email address, add .patch at the end of this PR page's URL.) For further assistance with EasyCLA, please submit a support request ticket.