Module media_player 

The MediaPlayer contract: one API, interchangeable engines.

See docs/specs/media-player-controller.md.

This replaces PlayerBackend, which abstracts a device — load, then seek — rather than an intent. That distinction is not academic; it produced four shipped defects in one day:

• A start position was not expressible, so every caller sequenced load() + seek() itself and each raced the engine’s asynchronous load independently. Resume worked through one caller and silently failed through another (DR-241).
• Whether a stream could be seeked in place was decided above the engines, by a truth table in a command handler, for engines it does not own (DR-238).
• Nothing in the contract obliged an engine to report its own state, so a handler for mpv’s pause property sat unreachable and the play/pause control never moved (DR-239).

The contract below is written so each of those is a compile-time or conformance-time failure rather than a runtime surprise.

TRACES: UR-081 | DR-242

Structs

Capabilities

What an engine can do, so callers adapt without naming engines.

OpenRequest

A request to present an item.

PlaybackSnapshot

Everything the UI consumes, read as one coherent value.

Enums

Phase

What an engine is doing right now.

Traits

MediaPlayer

Anything that can present media.

Functions

duration_from_secs

Seconds reported by an engine, as a Duration, without trusting the number.