A Player is one named unit of equipment: a lone speaker, a TV with its built-in speakers, a TV with a receiver. The spec selects the unit’s devices out of what the hardware operators publish, with the same CEL selectors a hand-written ResourceClaim would use. Between runs, the operator holds one claim on the unit’s display for the idle screen. It claims the other devices only while a Play runs on it.

The resource is namespaced, and everything a Player becomes is created in its namespace: the claims, the playback pod, and the Play that names it, so RBAC on the namespace covers the set.

apiVersion: media.liken.sh/v1alpha1
kind: Player
metadata:
  name: studio
  namespace: media
spec:
  zone: studio
  displayName: Studio Lab
  display:
    class: display
    displayName: Portable Screen
  render:
    class: gpu-render
  sinks:
    - class: audio-output
      displayName: Built-in Speakers
  remotes:
    - name: studio-gamepad
      displayName: Studio Controller
  idle:
    fadeAfterSeconds: 600

The class names here are the cluster’s own vocabulary: consumer DeviceClass objects are yours to create, and each hardware operator’s manual gives the YAML for its class.

A Player is one named unit of equipment. A Play names a Player to run media on it, and the media operator turns the Player into device claims: the display’s claim stands between runs, for the idle screen, and the other devices are claimed only while a Play runs.

spec

The devices that form the unit, each selected from what a hardware operator publishes. All of a Player’s devices must be reachable from one machine, because a Play becomes one pod and the scheduler places that pod on the machine that owns every claimed device. A Player whose devices span machines produces Plays that stay Pending. The spec must select a display or at least one sink; render alone plays nothing.

spec.display

The display this Player shows video on. Omit it for an audio-only Player.

spec.display.parameters

Opaque configuration for the driver that prepares the device, carried onto the claim unread. The display operator’s manual documents its parameters, such as mode and brightness.

spec.sinks[]

The audio outputs this Player plays sound through.

spec.sinks[].parameters

Opaque configuration for the driver that prepares the device, carried onto the claim unread. The audio operator’s manual documents its parameters, such as codec.

spec.render

The GPU render node the player program decodes and draws with. Omit it only for an audio-only Player; mpv needs a GPU to put video on a display.

spec.control

The panel’s DDC/CI control device, an opt-in. The idle pod holds it, and its sidecar darkens the panel after idle.offAfterSeconds and lights it on a press. A panel that refuses DDC/CI publishes no control device, so omit this there.

spec.control.parameters

Opaque driver configuration for the control selection, passed through on the claim.

spec.remotes[]

The controllers this unit owns, each naming a Remote in the same namespace. The Play’s pod builds one translator sidecar per entry.

spec.idle

This unit’s idle screen policy. Each field overrides the default MediaPreferences on its own.

status

What plays on this Player now, written only by the media operator. It is derived from the Plays that name the Player, so it is empty until one does.

On the bus

The players tree describes the equipment, with or without a running Play. See the media bus for the rules every topic follows.

status

What a screen would show about one unit: its name, what it is doing, the Play it runs, and its parts with the presence of each. The operator is the only writer, so an idle pod that just started draws the live state the broker already holds, with no request to the operator.

{
  "displayName": "Studio Lab",
  "activity": "Playing",
  "play": {"name": "dune", "title": "Dune"},
  "components": [
    {"name": "Portable Screen", "kind": "display"},
    {"name": "Built-in Speakers", "kind": "sink"},
    {"name": "Studio Controller", "kind": "remote", "connected": true}
  ]
}

activity is the same word the Kubernetes status carries. play is present while a run starts or plays: name is the object a person finds with kubectl, and title is the one line a screen draws. A component’s kind is display, sink, or remote, and only a remote carries connected, because a wired screen reports no presence.

volume

The unit’s listening level and its muted flag:

{"level": 40, "muted": false}

Both fields are always written, so a reader never needs a default for a missing key. The level runs 0 to 100, and 100 is unity, the player’s own default and the cap. Every pod for the unit subscribes and applies what it reads, so the unit plays at the one level the topic holds. The operator writes it when it seeds a unit or applies a Play’s starting volume, and the pod that handles a volume or mute press writes the result back. A published level outside 0 to 100 is clamped to the range.

panel

What the idle sidecar last actuated on the unit’s screen:

{"state": "On"}

The states are the four the Player status carries: On, BacklightOff, Off, and Unresponsive. The sidecar holds no API credentials, so the operator folds this topic into status.panel.

commands

The operator’s channel to the Player’s idle pod. It carries {"action": "re-present"} when a Play ends, and the idle sidecar recreates the idle surface. A controller never sends it, and it carries none of the media actions a Play’s commands topic accepts.