Player

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 keeps one claim on the unit’s display for the idle screen. It claims the other devices only while a Play runs on the unit.

A Player name is at most 32 characters, because media-operator and library-operator build the names of the objects they create from it, and Kubernetes limits some of those names to 63 characters.

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. The media operator retains the display claim between playback runs for the idle screen and claims the other devices 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.remotes[]

The controllers this unit owns, each naming a Remote in the same namespace. Each Remote runs a pod of its own, and the Play’s command sidecar reads the events every entry publishes.

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.

status.receiver

The receiver that this unit’s video goes into, matched from the machine the unit draws on and the monitor id of its screen. Absent for a unit that plays straight into its panel.

status.screen

The last screen the idle claim resolved to. The operator keeps it while the panel is away, so it can still read the screen’s Display and say why the idle pod waits. Absent until the claim has resolved once.

status.sinks[]

The Sink each spec.sinks selection resolved to, in spec order. The operator writes the list from an allocated playback claim and keeps it after the Play retires, the way it keeps status.screen. A tap through these names still needs a running Play.

status.conditions[]

The unit’s conditions. There is one, Screen, and it is absent until the idle claim has resolved once. True with reason Present means the screen’s Display reports a panel on its connector. False with reason PanelAway means the Display reports no panel there: the monitor shows another input, the idle claim has deallocated, and the idle pod stays Pending until the panel returns. This is expected, and an alert on Pending pods can read this reason to stay quiet. False with any other reason carries the Display’s own reason through. Unknown with reason NoDisplay means no Display carries the remembered monitor id, and Unknown with reason NotReported means the Display carries no Connected condition. The message is the Display’s own, and lastTransitionTime moves only when the status does.

status.idle

What draws this unit’s idle screen, and everything the operator that draws it needs. A delegate wires its client from this block alone, and it sets MEDIA_PLAYER_NAME on that client to the Player’s metadata.name, the value every focus mark holds. The block is absent for a Player that drives no screen and where the cluster names no display-draw class. A delegate reads this block and never the spec, because the spec may inherit its controller from the default MediaPreferences, and only the media operator resolves the tiers.

status.idle.bus

The bus facts a delegate’s client reads. With the two windows above, this block holds everything that a delegate’s client needs. It is present under every controller but media.liken.sh/none.

status.idle.bus.remotes[]

The unit’s controllers, one entry each, in spec.remotes order. That position is the index a focus moment carries, and it is the order the status topic lists the parts in. A unit with no controllers lists none.

Events

The operator and media-api post Kubernetes Events on the Player. kubectl describe player prints them. The API server deletes an Event one hour after its last write, so the conditions and the logs hold the facts after that.

On the bus

The players tree describes the equipment, with or without a running Play. The media bus gives the rules every topic follows and lists every writer and reader of each.

status

What a screen would show about one unit: its name, what it is doing, the Play it runs, and its parts with the link and the battery level of each. It also states where a power press goes. 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. The operator republishes only when the payload changes, and it clears the topic with an empty payload when the Player is deleted.

{
  "displayName": "Studio Lab",
  "activity": "Playing",
  "play": {"name": "evening-film", "title": "An Evening Film",
           "displayAlive": {"status": "False", "reason": "Restarting",
                            "message": "the display restarted 2 times: Error (exit code 1)"}},
  "components": [
    {"name": "Portable Screen", "kind": "display"},
    {"name": "Built-in Speakers", "kind": "sink"},
    {"name": "Studio Controller", "kind": "remote", "connected": true,
     "battery": 62, "focused": true}
  ],
  "power": "room"
}

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 has no link that can go down. battery is the charge the controller’s Peripheral reports, from 0 to 100, and a device that reports none omits the key. focused appears on the one remote whose focus mark names this Player, and the idle screen draws a small hexagon beside that controller in its parts list. Every other component omits the key.

power is room while the unit’s screen is wired through a Receiver: a power press is then an ask on the power topic, and the equipment operator turns the room off or on. It is screen while the screen is wired to no Receiver: the client handles a power press itself and lowers its shade, and it ignores wake and sleep on the power topic. A client reads the field at each press, so a Receiver that is wired or removed changes where the next press goes with no pod restart. The operator omits the field for a unit it has not matched against the Receivers yet: after the operator starts or the Player is created, until the operator’s first pass reaches the unit. That pass can take seconds on a busy API server. A client keeps the mode it last read through such a message. A client that has read no mode treats a non-empty power topic as room, the rule an operator that predates the field follows.

The field reads screen for a wired unit while the unit’s idle claim is unallocated and its screen does not resolve, for example after a restart that finds the claim with no allocation. It reads room again from the pass after the claim is allocated. A short gap in a screen that already resolved keeps room for up to 90 seconds.

A client that draws the idle screen must read this field to decide where a power press goes. The power topic in status.idle.bus.powerTopic is set for every unit, so a client that reads the topic’s presence as the sign of a Receiver treats every unit as room. Upgrade library-operator together with this operator, because an older media browser follows that rule. When this operator is upgraded, the idle pod of each unit with no Receiver is replaced once, because its environment gains the power topic.

play.displayAlive is the run’s DisplayAlive condition with its status, reason, and message, and the key is absent while the run reports none. The operator derives it from the playback pod, so a client reads a crashed display off the topic it already holds for the unit and sends no request to the API server. A client that draws the unit’s state can show the message while status is False. It needs no repair of its own: once the display has restarted more than twice in one run, the operator ends the run, and this topic reads Idle as it does after any film.

volume

The unit’s listening level, its muted flag, and who draws the volume indicator:

{"level": 0.63, "muted": false}
{"level": 0.63, "muted": false, "indicator": "receiver"}

The level is a fraction of the device’s max, from 0.0 to 1.0, so a screen draws one scale for every unit. level and muted are always written, so a reader never needs a default for either key.

indicator is absent unless the device that sets the level now is a Receiver whose spec.volume.indicator is Receiver. That receiver shows its own volume overlay on the TV, so the field is "receiver", and each screen tracks the level and the muted flag and draws no bar. An absent field means the screens draw the bar. When the unit falls back to its sinks, the field is absent again.

The operator is the only writer. It sets the room’s level through the device that sets it: the Receiver the unit’s screen is wired into, while its Reachable condition is True, and otherwise every Sink in the Player’s status.sinks. A press of KEY_VOLUMEUP or KEY_VOLUMEDOWN, from a remote whose focus mark names this Player, moves a target one step of the device’s spec.volume.step. A held key moves it once for each repeat. KEY_MUTE toggles the mute, and KEY_UNMUTE clears it. The target never goes past the device’s spec.volume.max. The operator writes the target into the device’s status.session.volumeAsk, at most once every 100 ms, and the device’s operator applies it.

The operator publishes here:

• the target, as soon as a press moves it, so the indicator moves at bus speed;
• the level the device reports while no target is pending, such as a turn of a receiver’s own knob;
• the level the device reports when it did not report the target within one second, as when a receiver’s own limit is below the target;
• each unit’s level once a broker session’s retained values have had time to arrive, after the operator starts and after the broker restarts, unless the broker already holds that level;
• the level again when only indicator changes, so the retained message holds the current value.

When a unit has several sinks, each one steps in its own units, and the topic carries the first one in spec.sinks order. mpv plays at unity and sets no level of its own.

A client reads status for the name, the activity, and the parts, and volume for the level. A retained message that the broker delivers when the client subscribes sets the level and draws nothing. Each live message draws the indicator, except a message whose indicator is "receiver", and a message that differs from the last one only in indicator. Each of those sets the level and draws nothing. A client publishes no level here, and it handles no volume key: the operator reads the keys from the remote’s own events topic.

volume/commands

The asks for the unit’s level from a program that is not a remote, one segment below volume. They are not retained, because an ask is an event. The operator treats each message the same as a press:

A message with no step and no mute does nothing, and the operator’s log says so.

panel

The desire the idle screen client states for the unit’s screen:

{"desire": "off"}

The two desires are on and off. The client holds no API credentials and writes no hardware, so the operator reads this topic and applies or lifts spec.override on the screen’s Display.

A client that starts reads the retained desire before it states one, and it states a desire only when a press, a starting Play, or the off window changes the panel. A client that restarts in a dark room keeps the room dark. On a reconnect, a client states again the desire it holds, so a broker that restarted holds the desire again. The operator reads no desire as no statement: it writes no override, and the session on a receiver keeps the awake flag it carries. What the panel actually shows comes back the other way, from the Display’s observed state into status.panel. The operator clears the topic with an empty payload when the unit’s controller becomes media.liken.sh/none, so a restarted operator does not read the last desire of a client that no longer runs.

commands

The commands around the Player’s idle screen. They are not retained (why ), and a controller never sends one directly. A client publishes nothing here.

One program writes here. The playback pod’s command sidecar publishes play-next when a person takes the up-next offer on the scrubber, and its request is the Play’s own spec.next.request, byte for byte. The client that wrote the Play reads that ask and creates the next Play. The same sidecar publishes home when a person presses home during a film, just before the Play ends, and the client reads that ask as a press of the home key. It publishes power when a person presses power during a film, also just before the Play ends. The client holds that ask until this Player’s status reads Idle, and then answers it as a power press between films: in the power mode room, it publishes the toggle on the power topic, and in the mode screen, it lowers the shade. The toggle waits for Idle so that the equipment operator reads the room after the film ended. A client that reads no Idle within 10 seconds drops the ask. The sidecar publishes power-off in place of power for KEY_SLEEP, the name the kernel gives a TV remote’s Power Off Function, and the client answers it the way it answers a press of KEY_SLEEP: off on the power topic in the mode room, or the shade in the mode screen.

power

The room’s power, for a unit whose screen is wired through a Receiver. The operator names the topic in status.idle.bus.powerTopic for every unit, so a delegate’s pod stays the same when a Receiver is wired or removed. The status topic’s power field says whether the topic is in use: room while a Receiver is wired, and screen while none is. Each message is an ask, so none is retained.

The idle screen client publishes a power press between films here, in the power mode room. The operator writes each ask into the Receiver’s status.session.powerAsk, and the equipment operator answers it:

The kernel’s rc-cec keymap gives a TV remote’s Power Off Function and Power On Function the names KEY_SLEEP and KEY_WAKEUP. HDMI-CEC 1.3a, CEC 13.13.3, says each one puts the device in the state it names and keeps it there when a person presses it again, so neither is a toggle.

The operator publishes two asks for the screen here, when the room’s TV speaks over HDMI-CEC. The equipment operator’s CEC node workload writes each ask into the Television’s status.screenAsk, and the operator relays each new one once. It relays nothing for an ask that the Television already held when the operator started, and nothing for a unit whose screen is wired through no Receiver. A client in the power mode screen ignores both asks.

Each program ignores the actions it does not answer, so a client that reads its own ask come back changes nothing.