Embedding a native media engine on desktop

A C media engine exposes a handle, a property bag, a command channel and an event stream. The JVM-side job is almost entirely ordering and thread ownership: what must be set before initialize, what must exist before the first load, and which thread may touch a handle. Get those wrong and the failures are late, rare, and blame the wrong code.

Model used throughout: one handle per media item (so two exist at once during a transition), one event-pump thread per handle, and one application thread that owns all handle mutation.

Traps

Pin the output driver explicitly, on every branch, before initialize. The engine chooses its output driver during initialize. Left unset, it auto-probes — and in a windowless JVM process an auto-probe can land on something you never intended (here: a terminal-graphics driver, which stopped the whole process during ordinary audio playback). Creating a render context afterwards does not retroactively change a driver that initialize already chose. Treat a failure to pin as fatal: refusing to create a player is recoverable, a hard native stop is not.