Skip to main content

## Module media_player

Source
Expand description

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.