The media bus

The resources declare what should exist. The components exchange reports, commands, button events, and state through one MQTT broker. The bus has a defined interface, like the CRDs. This page gives the rules every topic follows and lists every topic under the media operator’s tree, with its writer, its readers, and its payload. Each resource page links here for the rules and gives the payload shapes for its own topics.

Two operators meet on the broker. The media operator, its playback pods, each Remote’s pod, and each idle pod connect to it. The library operator runs its own tree on the same broker. Your program can connect too. A phone app, a Home Assistant instance, and a library application all join the same way, with a plain MQTT client and no Kubernetes credentials.

The broker is deploy/bus.yaml: one Mosquitto Deployment with its Service and ConfigMap, all named bus, beside the operator’s Deployment and never inside it. The two are separate so the operator restarts without dropping a message: a button press reaches mpv while the operator is down. The broker holds no storage volume, so a broker restart loses only the retained set. Each connected program republishes the retained state it owns when its session reconnects, and the next report from each running Play refills the rest within seconds.

The topic base

Every topic extends one base. The media operator’s base is liken/media by default, and the library operator’s is liken/library. Each operator stores its base as one string and passes it to every pod it creates. A whole tree moves together when a cluster chooses another base. The pages in this reference write topics without the base.

Retained state and events

State is retained and events are not. The broker retains the current value for a state topic and sends it to new subscribers. Event topics deliver individual button presses, commands, and requests to move focus without retaining them.

An empty retained payload clears a topic. The writer of a retained topic clears it that way when the object it described is gone, and a reader treats an empty payload as a cleared value, not as a live message. The media operator ignores an empty payload on a status, an availability, a panel, or a volume topic for that reason. It publishes those clears itself, and reading one back as a signal would act on a run or a unit that no longer exists.

An operator clears the topics of an object it owns on a finalizer, so the object is never gone from the API server while its topics still stand on the broker. The media operator’s finalizer on a Play is media.liken.sh/bus-topics. A sweep on every pass is the backstop behind it: it clears the topics of any run the pass’s own list of Plays does not hold, which is what finds a run whose clear the broker never received.

The topic names the object

The topic identifies the object; the payload does not. A Play’s namespace and name are segments of its topic path, while its report body contains only playback numbers. Parse the topic path to identify which object a message belongs to.

Availability

Retained state outlives the pod that wrote it, so a reader needs a signal that the writer is gone. The playback pod and the Remote’s pod each name an availability topic in their tree as the MQTT Last Will, with offline as the payload, and publish online there once connected. Both messages are retained. When a pod dies without a clean disconnect, the broker publishes the will, so retained state a dead pod left behind does not read as live. A reader that folds state from one of these trees reads the availability topic beside it.

The playback pod adds a space and its own pod UID after the word, and it puts the same UID on each report. A run’s new pod has the old pod’s name, and the broker can publish the old pod’s Last Will after the new pod is online, so the UID is how a reader tells the two pods apart.

The trees

Two operators publish trees on the broker. Each tree’s page lists its topics, and the resource pages give the payloads.

No device operator connects to the bus. The media operator writes a unit’s asks for its level, its power, and its input into the Receiver or the Sink that serves the unit, and reads back what the device reports there.

The media tree

Every topic under liken/media. The writer column names every program that publishes on the topic, the clear included. The readers column names every program that subscribes. The payload column links to the section of the resource page that gives the shape.

The players commands topic has one writer. The playback pod publishes play-next when a person takes the up-next offer on the scrubber, and the client that wrote the Play reads it and creates the next Play. It publishes home when a person presses home during a film, just before the Play ends, and the client under the film reads that ask as a press of the home key. It publishes power the same way when a person presses power during a film, and power-off when a person presses a TV remote’s Power Off Function. The client holds that ask until the Player’s status reads Idle, and then answers it the way it answers the same press between films.

“The playback pod” in this table is its command sidecar, the one container that connects to the bus. “The idle pod” is the idle screen client the media operator ships. A delegate’s client, under another controller , reads and writes the same players and remotes topics from status.idle.bus.

What the operator reads

The operator subscribes to eleven filters, one per retained or event kind it folds into a status or a decision:

Most presses never pass through the operator. A key event travels from the Remote’s pod to the playback pod or the idle client directly, gated on the retained focus mark, so a controller keeps working while the operator is down. The volume keys, the power asks, and the input asks are the exceptions, because a device operator acts on them through the Receiver or the Sink. They do nothing while no operator holds the lease.