GstSharp.Net.Base 1.28.10

GstSharp.Net

Modern .NET bindings for GStreamer 1.28, designed for NativeAOT from the start.

• .NET 10, IsAotCompatible=true on every shipping assembly.
• [LibraryImport] everywhere: interop stubs are produced at build time by the runtime source generator, not by reflection or IL emit.
• Zero reflection on the runtime path. Native types are mapped through a generated registry of function pointers, so trimming and AOT compilation keep the whole surface intact.
• Generated from .gir, by a generator that lives in this repository (generator/GstSharp.Generator). The generated C# is committed, so consumers never need Python, gapi, or xsltproc.
• Cross platform: Windows (both the MSVC and the MinGW flavor of the official GStreamer builds, plus MSYS2), macOS and Linux. The native library is located at startup by NativeLoader; no dllmap, no environment variables required.

Generated module set: Gst, GstBase, GstApp, GstVideo, GstAudio, GstPbutils, GstSdp, GstWebRTC, GstNet, GstRtsp, GstAllocators, GstTag, GstTranscoder, GstPlay, GstRtp, GstRtspServer, GES. An eighteenth module, GstController, is written by hand against the public module SPI and ships alongside them.

Packages

One version for the whole set, and every identifier starts with GstSharp.Net, so a single packageSourceMapping pattern covers all of them.

The analyzers ship inside GstSharp.Net rather than as a package of their own: they cannot get out of step with the binding that way, and no second package reports the same diagnostic twice. They are GST0001 (a wrapper that owns a reference and never releases it), GST0002 (a buffer mapping that is never released), GST0003 (a subclass that overrides an OnX vfunc without declaring the matching slot in its DefineSubclass call), GST0004 (the converse, a declared slot with no override behind it) and GST0005 (a CreateWrapper that throws away the SubclassCtorArgs it was handed, so the wrapper it builds is not the one the runtime asked for); see docs/analyzers.md. They travel along the package dependency, so a project that references only a module package — GstSharp.Net.Sdp, say — gets them too. Every module clears PrivateAssets on its reference to GstSharp.Net to say so, because the default would pack a dependency that asks for the analyzer assets to be left behind.

The packages target plain net10.0 and carry managed code only. GStreamer itself is not bundled: install it separately and let NativeLoader find it.

Installation

dotnet add package GstSharp.Net
dotnet add package GstSharp.Net.App     # and one per module you use

Where the packages come from

The set is published to nuget.org. The .nupkg files are also attached to every GitHub release for offline use. The copies on GitHub Packages exist for the project's own release plumbing; that feed requires authentication and is not the intended way to consume the bindings.

The GstSharp.Net* prefix is why every package identifier shares it: in a solution that pins feeds with packageSourceMapping, one pattern covers the whole set.

The native GStreamer

The packages contain managed code only. Install GStreamer itself:

Supported versions. The surface is generated from the 1.28.6 .gir files. The floor at run time is GStreamer 1.24: the struct layouts the ABI probes mirror have been stable since then. An entry point that GStreamer added after 1.24 is present in the managed surface and throws EntryPointNotFoundException against an older library — the missing export is the documented behavior, not a bug. CI runs the whole suite against four installations: Ubuntu 24.04 (1.24, the floor), the official Windows MSVC build (1.28.6), MSYS2's MinGW build, and Homebrew on macOS.

Getting started

using Gst;
using Gst.GLib;

GstSharp.Initialize();

// gst_parse_launch returns a GstElement; the cast goes through the type
// registry, which is what turns it into a Pipeline wrapper.
if (Global.ParseLaunch("playbin uri=file:///path/to/movie.mkv") is not Pipeline pipeline)
{
    Console.Error.WriteLine("that description is not a pipeline.");
    return 1;
}

// A pipeline this code built and stops is the one GObject wrapper a consumer
// disposes; see docs/ownership.md.
using (pipeline)
{
    // The bus wrapper is interned and shared with every other lookup of the
    // same bus, so it is not disposed here.
    Bus bus = pipeline.GetBus();

    pipeline.SetState(State.Playing);

    // A Message is a mini object: the wrapper owns a reference and has to be
    // released. GST0001 reports it when it is not.
    using Message? message = bus.TimedPopFiltered(
        ClockTime.None,
        MessageType.Eos | MessageType.Error);

    if (message?.Type == MessageType.Error)
    {
        (GException error, string? debug) = message.ParseError();
        Console.Error.WriteLine($"{message.SourceName}: {error.Message}");
        Console.Error.WriteLine($"debug: {debug}");
    }

    // Back to NULL before the pipeline is released: one that is still PLAYING
    // when its last reference goes away leaves its streaming threads running.
    pipeline.SetState(State.Null);
}

return 0;

GstSharp.Initialize() loads the native libraries, runs gst_init and fills the type registry. A module that is only ever named — in a cast, in a type test — never runs its own initialiser, so reach for the module entry point when that is all an application does with it: Gst.App.GstApp.Initialize(), Gst.Base.GstBase.Initialize(), and one next to every other module. The GType registry section explains the failure this avoids.

Ownership and lifetime

Read docs/ownership.md before writing anything that runs for longer than a second. The short version:

• MiniObject and Boxed wrappers (Buffer, Caps, Sample, Message, Structure, ...) own a reference and must be disposed. GST0001 enforces it.
• GObject wrappers (Element, Pipeline, Bus, Pad, ...) are interned and shared: normally do not dispose them. Disposal acts for every holder at once. The sanctioned exception is a pipeline this code created, after SetState(State.Null).
• A few calls consume their argument (AppSrc.PushBuffer, Element.SendEvent, BufferPool.SetConfig, WebRTCSessionDescription.New, ...). Dispose is idempotent, so a using around the argument stays correct.
• An application with no main loop should call GstSharp.DrainPendingReleases() periodically — once per poll of the bus is the natural place.

When the loader cannot find GStreamer

NativeLoader probes the registry, the documented environment variables, the known installation directories, PATH, and an application-bundled runtimes/<rid> tree. When none of that wins, say where to look:

GstSharp.Initialize(new GstSharpOptions
{
    NativeSearchPath = @"C:\gstreamer\1.0\msvc_x86_64\bin",
    WindowsFlavor = GstFlavor.Msvc,   // or GstFlavor.MinGW
});

And to find out what it did pick, which is the first thing to log in an application that ships to machines you do not own:

Console.WriteLine(NativeLoader.ResolvedDirectory);          // the directory that won
Console.WriteLine(NativeLoader.ResolvedFlavor);             // Msvc / MinGW, Windows only
Console.WriteLine(NativeLoader.ResolvedOrigin);             // which probe stage found it
Console.WriteLine(NativeLoader.ResolvedSourceDescription);  // that stage, in words
Console.WriteLine(NativeLoader.GetLoadedModulePath("Gst")); // the file actually mapped

One flavor and one directory are pinned for every module, so a process can never end up with half an MSVC and half a MinGW GStreamer.

Samples

The table below is the short index; docs/samples.md is the long-form companion, with the samples grouped by theme, the binding APIs each one exercises and what it deliberately leaves out.

PlaybinPlayer, AppSinkSpans, AppSrcPush and CustomMeta also take --native-path <directory>, --flavor msvc\|mingw and --timeout <seconds>; GstLaunch, GstTypefind, GstDeviceMonitor, GstDiscoverer and GstInspect take the first two. Four of those five ports add one option of their own that the C tool does not have, so that a path which normally needs a console signal or a person can be run unattended: GstLaunch --interrupt-after <seconds> drives its Ctrl+C path, GstDeviceMonitor --follow-for <seconds> bounds a hotplug run, GstTypefind --fail-on-unknown turns a file whose type was not found into a non-zero exit code, and GstDiscoverer --fail-on-error does the same for a URI that could not be discovered. GstInspect adds none: its page is diffed against the C tool's byte for byte, so it prints nothing the C tool does not.

GstTranscode takes no option of its own: it is <src-uri> <dst-uri> [<profile>], where the profile defaults to application/ogg:audio/x-vorbis. It needs the uritranscodebin and transcodebin elements of the transcode plugin of gst-plugins-bad at run time, which ship separately from the libgsttranscoder-1.0 library the module imports from; without them the sample says so and stops rather than reporting a transcoding failure.

GstPlay takes a playlist of URIs or paths and these options of its own: --playlist <file> to append the entries of a playlist file to it, --volume <0..1>, --audiosink <factory> and --videosink <factory>, --flags <spec> to write the initial flags of the playbin as +-joined nicks or a number, --visualization <name> beside --list-visualizations, --duration <seconds> to bound an unattended run, --wait-on-eos to keep the last frame up instead of moving on, --shuffle to reorder the playlist once before playback, and --interactive to read the keyboard (press k for the list of keys). --wait-on-eos needs one of --duration and --interactive, because on its own it would never end. Its header comment says which keys the C tool puts elsewhere and what it leaves out — --gapless and --instant-uri among them, both of which need a playbin driven directly. Cycling tracks goes through the index-based setters, which upstream deprecated in 1.26 and the generator therefore marks [Obsolete]; they are the only ones that exist on the 1.24 floor, so the sample calls them under a #pragma warning disable CS0618.

The official tutorials

samples/tutorials/ holds the GStreamer basic tutorials ported onto this binding, one runnable project per tutorial, with the upstream numbering kept:

The walkthrough text stays upstream; each file carries a header comment saying where the port differs from the C original and why — a polled bus instead of a GMainLoop, using instead of gst_*_unref, a typed event instead of g_signal_connect. samples/tutorials/README.md is the index and explains the options the tutorials do not have (--headless, BasicTutorial13 --keys and the per-tutorial bounds), which exist so that a tutorial can be run unattended.

dotnet run --project samples/tutorials/BasicTutorial02
dotnet run --project samples/tutorials/BasicTutorial03 -- <file-or-uri>

Properties and signals without a generated binding

Not everything is in the .gir files. Plugins add properties and signals that introspection never sees, and GStreamer publishes a good deal of its functionality as action signals, which are calls dressed up as signals. The by-name surface on Gst.GObject.Object reaches all of it, without reflection:

using Gst.GObject;

// A property no binding exposes, read and written by name.
using Value swapchain = sink.GetProperty("swapchain-handle");
nint handle = swapchain.GetPointer();

using Value sync = Value.CreateFor(false, GType.Boolean);
sink.SetProperty("sync", sync);

// An action signal is a call dressed up as a signal.
sink.EmitSignal("resize", 1920, 1080);

// A signal the .gir never mentioned, connected and disconnected by name.
ulong id = playbin.ConnectSignal("about-to-finish", (sender, args) => null);
playbin.RemoveHandler(id);

Arguments are validated against the signature the object declares before anything is emitted, and a mismatch names the expectation.

What the generator did not bind, and why, is listed per module and per reason in girs/skip-report.md. The gaps worth naming here:

• Subclassing is limited to an allowlist of base classes. A C# type can derive from one of twenty eight classes — Gst.Element, Gst.Bin, Gst.Pad, the GstBase sources, sinks, transforms, parsers and aggregators including AggregatorPad, the GstAudio sinks, sources, filters and codecs, the GstVideo sinks, filters and codecs, and the timeline elements, sources and clips of the editing services — override the vfuncs of the class and be called back through the native vtable. A type that also states how its wrapper is built can be registered with gst_element_register and made by gst_element_factory_make or named in a pipeline description. It can install properties, define signals and implement GstURIHandler, so gst_element_make_from_uri finds it. What is not there yet: construct properties, interfaces other than GstURIHandler, and defining a new interface from managed code. See docs/subclassing.md.
• Writing GValue-typed structures is incomplete. Reading is covered — Value.GetBoxed<T>() for a boxed value and Value.GetMiniObject<T>() for a caps, a tag list or a sample — and building a GValue for every fundamental type is in progress. A boxed value that is not a mini object still comes back from EmitSignal as an opaque handle rather than as a typed wrapper.
• scope="async" callbacks are not generated. The Gio asynchronous pattern is exposed as Task-returning methods instead, hand written per operation; see docs/gio-async.md.
• The byte and bit cursors are out of scope. GstByteReader, GstByteWriter, GstBitReader and GstBitWriter walk a block of memory the caller already owns, and .NET has that surface built in: Span<byte>, BinaryPrimitives (every width and endianness as a single inlined instruction), ArrayBufferWriter<byte> for the growing writer. The memory is already reached as a span — Gst.Buffer.Map and Gst.Base.Adapter.Map hand one out, Gst.Buffer.NewMemdup takes one back — and the masked 32 bit start code scan is bound on Gst.Base.Adapter.MaskedScanUint32. The C cursors add a bit level position with fixed width reads only — no Exp-Golomb, nothing codec aware. The 148 dropped methods are listed under GstBase in girs/skip-report.md. This is a decision, not a gap, and it does not change within 1.28.x.

Namespaces

The C# namespace of a module is its gir namespace under Gst: GstBase becomes Gst.Base, GstApp becomes Gst.App, GstWebRTC becomes Gst.WebRTC, and so on. GES is the exception: its gir namespace is already top level, so its C# namespace is GES, mirroring the gir rather than inventing a prefix the C library does not have.

Gst.GLib, Gst.GObject and Gst.Interop are the hand-written runtime, not generated from the GLib girs. Gst.Gio is a deliberately small hand-written subset of Gio — cancellables, sockets, TLS — covering what the GStreamer surface hands out and nothing else.

Status and versioning

Stable. From 1.28.1 on the public surface only grows: new members appear as the binding closes gaps, existing signatures stay. A behavioral bug — ownership, lifetime, a wrong contract — is fixed in a patch release and called out in the release notes. A change that would break compilation waits for the next GStreamer series.

1.28.1 itself is the one deliberate exception, taken in the first week of the series while nothing depended on the surface: it re-projected the types a value copy could not represent — the buffer metas, the static caps and pad templates — and repaired the shipped members that discarded or overran what the native call wrote. That window is closed. The compatibility promise above counts from 1.28.1, and 1.28.0 is unlisted for it.

The version is <gstreamer-major>.<gstreamer-minor>.<binding-patch>:

• major and minor track the GStreamer series the bindings are generated from. 1.28.x of this package is generated from GStreamer 1.28, and a move to GStreamer 1.30 makes the package 1.30.0.
• patch is the binding's own counter. It has nothing to do with the GStreamer patch release; 1.28.3 does not imply GStreamer 1.28.3, and the runtime floor stays 1.24 regardless.

Extending the binding

A hand-written binding module can live outside this repository. An assembly that references the GstSharp.Net package can register its own native library with the loader, hand its GType-to-wrapper table to TypeRegistry, and derive its wrappers through the protected constructors of Gst.GObject.Object, Gst.GObject.InitiallyUnowned, Gst.MiniObject and Gst.GObject.Boxed — with no InternalsVisibleTo from here. GstSharp.Net.Controller is that module written out: it binds all of libgstcontroller-1.0, it ships, and nothing grants it the internals of anything.

It attaches to the generated hierarchy too. Every generated wrapper class — Gst.Element, Gst.Object, Gst.ControlSource and the rest — carries the same protected constructor, so a module's classes derive from the wrapper of the nearest native ancestor and are shaped like the C types they stand for. That means the members of the generated ancestors are inherited and that generated API taking one of them takes your wrapper: Gst.Controller.InterpolationControlSource really is a Gst.ControlSource, and GES.TrackElement.SetControlSource accepts it, across three assemblies and still with no grant of internals anywhere.

Generator-backed modules are not supported. The generator is a tool of this repository, not a product, and the code it emits uses internals; a module is written by hand.

docs/modules.md is the guide: the three registration calls, the obligations that come with each wrapper base, how to attach to the generated hierarchy and what is still closed — everything about a generated class except its constructor — and the worked example, file by file.

Documentation

The API reference and these guides are published as a site at https://masa-iwm.github.io/GstSharp.Net/, built from main.

Repository layout

Building

dotnet build
dotnet test

A native GStreamer installation is only needed for the integration tests and the samples. See CONTRIBUTING.md for the generator commands and the quality gates.

License

LGPL-2.1-or-later. See LICENSE.

The bindings are generated from GStreamer's .gir files and embed their documentation text, which is LGPL licensed; the same license therefore applies to the generated sources.

What that means in practice — not legal advice, and not a substitute for reading the license or asking a lawyer:

• GStreamer is loaded dynamically, through [LibraryImport] against the shared libraries an installation provides. Nothing in these packages links GStreamer statically, including under NativeAOT: an AOT-published application is one native executable of managed origin that still resolves libgstreamer-1.0 at run time.
• A closed-source application may use these packages. The LGPL condition that matters is that the user can replace the LGPL parts, which dynamic loading satisfies: point the application at a different GStreamer installation and it uses that one.
• Changes to GstSharp.Net itself are LGPL and belong back here, because the generated sources carry GStreamer's own documentation text.
• The GStreamer installation is a separate question. Its plugins carry their own licenses — several of the "ugly" and "bad" sets are GPL or carry patent conditions — and shipping a runtime alongside an application means auditing what is in it.