Broiler.Media.Video.Windows 0.1.0-preview.13

Broiler.Media

Broiler.Media is the decode-first media component for Broiler. It owns image, audio, and video decoding, format probing, and codec selection, behind small abstraction assemblies with one concrete implementation assembly per media kind. Rendering, windowing, networking, and HTML media-element behaviour deliberately live outside this component.

Preview release. Publishing selects the next unused preview. Public names, XML documentation, and the MediaLimits/pixel-format contracts are not frozen yet and may change before 1.0. See the roadmap for what is still open.

Installation

Preview packages need an explicit prerelease opt-in:

dotnet add package Broiler.Media.All --prerelease

Broiler.Media.All is a dependencies-only meta-package covering all eight runtime assemblies, including the Windows video contracts and Media Foundation backend. To take only what you need, reference the individual packages instead — for example, image decoding alone:

dotnet add package Broiler.Media.Image.Managed --prerelease

The Windows-only video backend can also be referenced individually:

dotnet add package Broiler.Media.Video.MediaFoundation --prerelease

All packages target net10.0 and can be built on either host. Media Foundation playback requires Windows; its public APIs carry Windows platform annotations.

Each Media Foundation engine owns a dedicated COM thread. Native notifications and output lifecycle callbacks are dispatched asynchronously; implementations that touch UI state must marshal that work to their UI dispatcher. Disposing a session cancels pending output work and releases the native engine without waiting for application output callbacks to finish.

Assemblies

Each runtime assembly ships as its own NuGet package; applications opt into the media kinds and implementations they need. Broiler.Media is the base, not an everything-bundle.

One additional package ships no assembly of its own:

Dependency direction

Broiler.Media.Audio.Managed          -> Broiler.Media.Audio -> Broiler.Media
Broiler.Media.Video.MediaFoundation  -> Broiler.Media.Video -> Broiler.Media
Broiler.Media.Video.MediaFoundation  -> Broiler.Media.Video.Windows -> Broiler.Media.Video
Broiler.Media.Image.Managed          -> Broiler.Media.Image -> Broiler.Media

Broiler.Graphics                     -> Broiler.Media.Image          (abstraction only)
Broiler.Graphics.Windows             -> Broiler.Media.Video.Windows  (implements the borrowed HWND contract)

The abstraction assemblies are platform-neutral, safe-code, trimming- and AOT-friendly, and reference no implementation, no Graphics/HTML, and no native/Media Foundation package.

Supported formats

Additional audio codecs (MP3/AAC/Vorbis/Opus/FLAC) and non-Media-Foundation video providers are future work; the stack reports a deterministic capability error for formats it does not support rather than a misleading placeholder.

Selecting and using a codec

Codec selection is explicit — there is no process-wide mutable Current singleton and no module-initializer side effects. The application composition root builds one immutable catalog and reuses it:

var catalog = new MediaCodecCatalog(ManagedImageCodecs.CreateCodecs());   // or audio/video codecs
using var input = new MediaInput(stream, new MediaSourceHints(mimeType: "image/png"));
MediaCodecMatch? match = await catalog.SelectAsync(MediaKind.Image, input);
if (match?.Codec is ImageCodec codec)
    ImageSequence decoded = await codec.DecodeAsync(input);

Selection is content-probe first: MIME type, file extension, and URL are hints only.

Consumers register the codec set at their own composition root:

• Graphics decodes images through an injected catalog via Broiler.Graphics.BImageCodecs.Use(...) (Graphics references only Broiler.Media.Image, never the implementation).
• Browser/app playback (the <audio>/<video> playback clock, transport, and element state machine) lives in the Broiler HTML/application component — never in this one.

Security and reliability

All media is untrusted input. Decoders enforce configurable MediaLimits (encoded byte count, image/video dimensions and pixel/frame counts, audio channels/sample-rate/duration, probe bytes and time, queued/decoded memory) and use checked arithmetic for dimensions, strides, and allocation sizes. Malformed data produces a bounded MediaException carrying a MediaError (codec id and byte offset where safe) — never unbounded allocation, hangs, silent partial success, or arbitrary exception leakage. See ADR 0002 for buffer ownership and limits.

Repository layout

src/                     runtime assemblies, one directory per package
src/tests/               one self-hosted test runner executable per assembly
eng/                     vendored packaging metadata and package icon
docs/                    roadmap and architecture decision records
Broiler.Media.slnx       solution over every project in src/ and src/tests/

The repository is standalone and has no Graphics submodule or package dependency. The application supplies the borrowed HWND through IHwndVideoOutput.

WIC and Media Foundation declarations are shared through the Broiler.Native.Windows package, currently 0.1.0-preview.3. Codec behavior and Media error mapping remain here. NuGet.config restores Native packages from the Broiler-Platform GitHub Packages feed and other dependencies from NuGet.org. A sibling Native checkout does not replace these package references.

For local restore, set NuGetPackageSourceCredentials_github to Username=YOUR_GITHUB_USER;Password=YOUR_TOKEN;ValidAuthenticationTypes=Basic, using a personal access token (classic) with read:packages. Keep credentials out of the repository. CI and publishing supply this variable from GITHUB_TOKEN. In the GitHub package settings for both Broiler.Native.Windows and its dependency Broiler.Native, grant Broiler-Platform/Broiler.Media read access under Manage Actions access. Workflow packages: read permission alone does not grant access to another repository's private packages. See GitHub's NuGet authentication documentation.

The referenced Native versions are also published on NuGet.org, so consumers using only NuGet.org can restore Media. When bumping the Native reference, publish that Native version to NuGet.org first; selecting the Media publish target does not publish its dependencies or change the restore feed.

Building and testing

git clone https://github.com/Broiler-Platform/Broiler.Media.git

The solution uses Debug and Release configurations.

dotnet build Broiler.Media.slnx -c Release

All runtime libraries and test runners build in both configurations. The test script runs the Media Foundation suite only on Windows.

Tests are self-hosted console runners rather than a test framework, so there is nothing for dotnet test to discover. After building, run every suite the configuration enables (pass the same configuration used for the build):

./eng/run-tests.sh Release

Or run one directly:

dotnet run --project src/tests/Broiler.Media.Image.Managed.Tests -c Release

To produce the packages locally:

pwsh -File eng/pack.ps1

Continuous integration and releases

CI runs the six portable suites on Linux and Windows, plus Media Foundation on Windows, and packs all nine packages. Publish selects the next preview unused on both NuGet.org and GitHub Packages, reuses CI, verifies consumer restore from the selected destination, and publishes the resulting artifacts. Manual runs default to a dry run.

See CI, packages, and releases for dependency management, feed credentials, version selection, and release tags.

Packaging

Packages are published per assembly with lockstep versioning, Apache-2.0 licensing, symbol packages (.snupkg), and SourceLink. The meta-package contains dependencies only and has no symbol package. Shared metadata is vendored from eng/Broiler.Packaging.props; repository overrides, including any preview floor, live in Directory.Build.props. All runtime packages target net10.0.

Design records

• Current roadmap
• ADR index

License

Apache-2.0. See LICENSE.