media-operator

1package main23// An album is one item. The presentation block declares an item's shape,4// the way a video item's hint does: a directory item marked as an album5// becomes one written timeline, and a file item passes through as itself.6// The expansion runs in the shim, because the playback pod is the one7// process that mounts the media, so it is the one process that can read an8// album's files.910import (11	"encoding/json"12	"fmt"13	"os"14	"path/filepath"1516	"github.com/liken-sh/media-operator/edl"17)1819// The two block values that mark an album. An item needs both, because the20// music type alone is a standalone track, and the hint names the shape the21// way movie and series name a video's.22const (23	presentationTypeMusic = "music"24	presentationHintAlbum = "album"25)2627// Where the shim writes an album's timeline. It is the volume the playback28// pod already shares between mpv and the command sidecar, so mpv loads the29// timeline and the sidecar reads it back for the album's cover. It is a30// variable rather than a constant so a test writes under its own directory.31var albumTimelineDir = ipcMountPath3233// expandItems turns the resolved playlist into the entries mpv loads. An34// album directory becomes the one timeline written for it, and every other35// item is the path the resolver already settled.36func expandItems(items []string, blocks []json.RawMessage) ([]string, error) {37	entries := make([]string, len(items))38	for index, item := range items {39		entries[index] = item40		if !isAlbum(presentationAt(blocks, index)) {41			continue42		}43		timeline, err := writeAlbumTimeline(item, index)44		if err != nil {45			return nil, err46		}47		entries[index] = timeline48	}49	return entries, nil50}5152// writeAlbumTimeline reads one album folder and writes its timeline. An53// album with no audio files fails the run, because a spec that marks a54// folder as an album and points at an empty one states a wrong fact, and55// silence would hide it.56func writeAlbumTimeline(dir string, index int) (string, error) {57	files, err := edl.AlbumFiles(dir)58	if err != nil {59		return "", fmt.Errorf("read the album %q: %w", dir, err)60	}61	if len(files) == 0 {62		return "", fmt.Errorf("the album %q holds no audio files", dir)63	}64	path := filepath.Join(albumTimelineDir, fmt.Sprintf("album-%d.edl", index+1))65	if err := os.WriteFile(path, []byte(edl.Timeline(files)), 0o644); err != nil {66		return "", fmt.Errorf("write the timeline for %q: %w", dir, err)67	}68	return path, nil69}7071// isAlbum reads one block as the mark of an album: the music type and the72// album hint together.73func isAlbum(presentation Presentation) bool {74	return presentation.Type == presentationTypeMusic && presentation.Hint == presentationHintAlbum75}7677// allMusic says whether every item of the run is music. The answer decides78// --vid=no, and the flag is global to the run, so one film in the list must79// keep video on for the whole of it.80func allMusic(blocks []json.RawMessage, items int) bool {81	if items == 0 {82		return false83	}84	for index := range items {85		if presentationAt(blocks, index).Type != presentationTypeMusic {86			return false87		}88	}89	return true90}9192// presentationAt reads one item's block. An item the pod baked no block for93// reads as an empty block, so a Play that declares nothing keeps the94// player's own defaults.95func presentationAt(blocks []json.RawMessage, index int) Presentation {96	var presentation Presentation97	if index < 0 || index >= len(blocks) {98		return presentation99	}100	if err := json.Unmarshal(blocks[index], &presentation); err != nil {101		return Presentation{}102	}103	return presentation104}

1package main23// The wire types are hand-written, the way liken and the sibling4// operators write theirs. The Kubernetes API is HTTPS that serves5// JSON, and importing client-go for a dozen structs brings informers,6// work queues, and a release cadence this program does not use. Each7// type carries only the fields this operator reads or writes; the8// API server fills in the rest.910import "encoding/json"1112// The group this operator serves, and the two Kubernetes groups it13// writes into: claims live under resource.k8s.io and pods under the14// core group, because the objects a Play becomes are ordinary15// Kubernetes objects any tool can read.16const (17	mediaAPIVersion = "media.liken.sh/v1alpha1"18	claimAPIVersion = "resource.k8s.io/v1"19	podAPIVersion   = "v1"20)2122// ObjectMeta carries what this operator reads or writes: name and23// namespace for the URL, resourceVersion for the conditional write, uid24// with ownerReferences for garbage collection, and labels so a watch25// selects the operator's own playback pods.26//27// Annotations carry the template hash the operator stamps on a standing28// claim and a standing pod, which is how a pass tells a live object from29// the object it would build now. deletionTimestamp is set by the API30// server on an object that is on its way out, and a standing pair with31// one set is left alone until the delete completes.32type ObjectMeta struct {33	Name              string            `json:"name,omitempty"`34	Namespace         string            `json:"namespace,omitempty"`35	UID               string            `json:"uid,omitempty"`36	ResourceVersion   string            `json:"resourceVersion,omitempty"`37	Labels            map[string]string `json:"labels,omitempty"`38	Annotations       map[string]string `json:"annotations,omitempty"`39	DeletionTimestamp string            `json:"deletionTimestamp,omitempty"`40	OwnerReferences   []OwnerReference  `json:"ownerReferences,omitempty"`41}4243// An ownerReference ties an object's life to its owner's: the44// garbage collector deletes the owned object when the owner goes,45// which is this operator's whole teardown. Controller is true46// because exactly one thing manages each pod and claim; there is no47// blockOwnerDeletion, because nothing here needs the owner to wait.48type OwnerReference struct {49	APIVersion string `json:"apiVersion"`50	Kind       string `json:"kind"`51	Name       string `json:"name"`52	UID        string `json:"uid"`53	Controller bool   `json:"controller"`54}5556// A list's own resourceVersion is the revision of the whole57// collection, which is what a watch resumes from.58type ListMeta struct {59	ResourceVersion string `json:"resourceVersion,omitempty"`60}6162// A Player is equipment, not a running thing. It holds no claims of63// its own. The operator reads the spec and writes the status: the64// spec is the equipment a person declared, and the status is what65// plays on it now.66type Player struct {67	APIVersion string       `json:"apiVersion,omitempty"`68	Kind       string       `json:"kind,omitempty"`69	Metadata   ObjectMeta   `json:"metadata"`70	Spec       PlayerSpec   `json:"spec"`71	Status     PlayerStatus `json:"status"`72}7374// The status the operator writes onto a Player: whether it plays75// anything now, and the name of the Play that does. Both are76// omitempty, so an idle Player with no activity word yet shows blank77// rather than a zero.78type PlayerStatus struct {79	Activity string `json:"activity,omitempty"`80	Play     string `json:"play,omitempty"`8182	// Panel is what the screen's Display last observed, empty83	// until a Display carries an observation.84	Panel string `json:"panel,omitempty"`8586	// Idle is the resolved idle screen controller and, where a87	// controller draws, the standing claim a delegate references and the88	// requests that claim carries. It is nil for a Player that drives no89	// screen and for a cluster that names no display-draw class.90	Idle *PlayerIdleStatus `json:"idle,omitempty"`91}9293// PlayerIdleStatus is what a delegate wires its client from. Controller94// is the resolved name, always set. Claim is the standing claim in the95// Player's namespace, which the delegate's pod references by name.96// Requests are the claim's request names in claim order, one per97// resources.claims entry the delegate's container states.98// FadeAfterSeconds and OffAfterSeconds are the resolved windows, always99// written, because zero is a policy and an absent field is not one.100// Under media.liken.sh/none the block carries the controller alone.101// standing claim in the Player's namespace, which the delegate's pod102// references by name. Requests are the claim's request names in claim103// order, one per resources.claims entry the delegate's container states.104// FadeAfterSeconds and OffAfterSeconds are the two resolved windows, and105// both are always written, because zero is a policy and an absent field106// is not one. Under media.liken.sh/none the block carries the controller107// alone.108type PlayerIdleStatus struct {109	Controller string   `json:"controller"`110	Claim      string   `json:"claim,omitempty"`111	Requests   []string `json:"requests,omitempty"`112113	// The two windows the operator resolved, in seconds. Zero on the114	// fade means the screen never fades on its own, and zero on the off115	// window leaves the panel lit. Neither has omitempty, so a client116	// reads a number for each.117	FadeAfterSeconds int64 `json:"fadeAfterSeconds"`118	OffAfterSeconds  int64 `json:"offAfterSeconds"`119120	// Bus is what a delegate's client reads to join the unit on the121	// bus. It is present under every controller but122	// media.liken.sh/none.123	Bus *PlayerIdleBus `json:"bus,omitempty"`124}125126// PlayerIdleBus names the broker and every topic a delegate's client127// reads or writes. The broker and the topic base are this operator's128// configuration, so the status carries the built topics and a client129// derives none. VolumeTopic is empty for a unit with no sinks, which is130// the speaker gate: the client subscribes to no level, draws none, and131// publishes none. Remotes has one entry per spec.remotes entry, in spec132// order, because that position is the index a focus moment carries.133type PlayerIdleBus struct {134	Address       string             `json:"address"`135	StatusTopic   string             `json:"statusTopic"`136	VolumeTopic   string             `json:"volumeTopic,omitempty"`137	CommandsTopic string             `json:"commandsTopic"`138	PanelTopic    string             `json:"panelTopic"`139	Remotes       []PlayerIdleRemote `json:"remotes,omitempty"`140}141142// PlayerIdleRemote is one of the unit's controllers as a client reads143// it: the topic its presses arrive on and the topic its focus mark is144// on. The client gates every press on the mark naming this Player, and145// the cycle topic is the focus topic plus /cycle.146type PlayerIdleRemote struct {147	Events string `json:"events"`148	Focus  string `json:"focus"`149}150151// The three panel states, each folded from the Display's152// observed values and not from what the media layer asked for.153const (154	panelOn           = "On"155	panelBacklightOff = "BacklightOff"156	panelOff          = "Off"157)158159// A Player's activity is the coarse state a person scans for: it160// plays a Play now, a Play is starting on it, or it is free. The161// Play name beside it says which run, so the two columns together162// read as one sentence.163const (164	playerPlaying  = "Playing"165	playerStarting = "Starting"166	playerIdle     = "Idle"167)168169type PlayerList struct {170	Metadata ListMeta `json:"metadata"`171	Items    []Player `json:"items"`172}173174// The three device roles. Display and render are single because one175// pod drives one screen through one GPU; sinks is a list because a176// unit plays through however many outputs it has. The CRD requires a177// display or at least one sink.178//179// Remotes names the controllers the unit owns. Each entry names a180// Remote in the same namespace, and the Play's command sidecar reads181// the events topic of each one, so a unit's controllers belong to its182// spec beside its display and its sinks.183type PlayerSpec struct {184	Zone string `json:"zone,omitempty"`185186	// The human name of this unit, the one the idle screen and later187	// ambient surfaces show in place of the object name. It is the188	// household's word for the unit, such as Studio Lab. Unset, the idle189	// screen falls back to the Player's object name.190	DisplayName string `json:"displayName,omitempty"`191192	Display *PlayerDevice  `json:"display,omitempty"`193	Sinks   []PlayerDevice `json:"sinks,omitempty"`194	Render  *PlayerDevice  `json:"render,omitempty"`195	Remotes []PlayerRemote `json:"remotes,omitempty"`196197	// The per-Player override of the audio and subtitle language preferences.198	// A nil list, or an empty Subtitles, means this Player states nothing, so199	// resolution reads the default MediaPreferences instead.200	AudioLanguages    []string `json:"audioLanguages,omitempty"`201	SubtitleLanguages []string `json:"subtitleLanguages,omitempty"`202	Subtitles         string   `json:"subtitles,omitempty"`203204	// Idle is this unit's idle screen policy. Resolution reads it field205	// by field over the default MediaPreferences, so a Player states206	// only what differs from the household.207	Idle *IdlePolicy `json:"idle,omitempty"`208}209210// IdlePolicy is what the idle screen does while nothing plays. The same211// block is the override on a Player and the default on the household's212// MediaPreferences, so the two tiers resolve field by field.213type IdlePolicy struct {214	// Image is the container image the idle screen runs. The image215	// starts with its own entrypoint and reads the unit's state off the216	// bus. Empty defers to the next tier.217	// A tier that states none runs the idle client at the operator's218	// own version.219	Image string `json:"image,omitempty"`220221	// FadeAfterSeconds is the quiet stretch before the idle screen222	// fades to black. Zero disables the automatic fade. A pointer,223	// because zero and absent differ: absent defers to the next tier.224	FadeAfterSeconds *int64 `json:"fadeAfterSeconds,omitempty"`225226	// OffAfterSeconds is the quiet stretch before the panel itself227	// goes dark. Zero or absent means it never does. A pointer for the228	// same reason the fade window is one.229	OffAfterSeconds *int64 `json:"offAfterSeconds,omitempty"`230231	// OffMode is which override the operator applies at the off232	// window, the backlight or the panel's power. Empty defers to the233	// next tier.234	OffMode string `json:"offMode,omitempty"`235236	// Controller names the operator that draws this unit's idle237	// screen, a domain-qualified name the way a GatewayClass names its238	// controllerName. Empty defers to the next tier, and where no tier239	// states one the built-in is media.liken.sh/idle-screen, this240	// operator's own name.241	Controller string `json:"controller,omitempty"`242}243244// The two ways a panel goes dark, and the two override blocks they245// become. A backlight at zero still answers DDC. Power off stops246// some panels from answering DDC at all, so a Player states it only247// for a panel the drill proved wakes.248const (249	offModeBacklight = "backlight"250	offModePower     = "power"251)252253// One controller the Player owns. Name is the Remote in the same254// namespace. A controller maps one way on every unit, as a device255// does under hwdb, so the entry carries no Keymap of its own.256type PlayerRemote struct {257	Name string `json:"name"`258259	// The human name of this controller, the one the idle screen shows in260	// its parts list, such as Studio Dualsense Controller. Unset, the idle261	// screen falls back to Name, the Remote this entry references.262	DisplayName string `json:"displayName,omitempty"`263}264265// One device selection. The three fields become a DeviceClass name,266// a CEL selector, and an opaque config block on the claim.267type PlayerDevice struct {268	Class string `json:"class"`269270	// The human name of this selection, the one the idle screen shows in271	// its parts list, such as Portable Screen or Built-in Speakers. Unset,272	// the idle screen falls back to the DeviceClass name, which says what273	// the selection is.274	DisplayName string `json:"displayName,omitempty"`275276	Selector   string            `json:"selector,omitempty"`277	Parameters *DeviceParameters `json:"parameters,omitempty"`278}279280// Values is raw JSON because the driver defines the parameters and281// this operator carries them onto the claim unread.282type DeviceParameters struct {283	Driver string          `json:"driver"`284	Values json.RawMessage `json:"values,omitempty"`285}286287// A Play is one run of media on a Player, with a lifecycle analogous288// to a Job: it runs once to completion, and it stays for its status289// until its ttlSecondsAfterFinished passes or a person deletes it.290type Play struct {291	APIVersion string     `json:"apiVersion,omitempty"`292	Kind       string     `json:"kind,omitempty"`293	Metadata   ObjectMeta `json:"metadata"`294	Spec       PlaySpec   `json:"spec"`295	Status     PlayStatus `json:"status"`296}297298// A Play names the players it runs on and the items to play in order,299// and Start is where in the first item the run begins. Players is a300// list of one today, because the carriage layer will let one Play301// reach several players in sync, and a list that grows a second302// element changes no field name when it does.303type PlaySpec struct {304	Players []string   `json:"players"`305	Items   []PlayItem `json:"items"`306	Start   string     `json:"start,omitempty"`307	// The seconds one trickplay tile covers, as a Go duration like 10s.308	// Jellyfin writes no manifest beside the sheets, and the last sheet is309	// padded, so the tile count cannot be read back. The Play declares the310	// interval, and it defaults to 10s when this is empty.311	TrickplayInterval string `json:"trickplayInterval,omitempty"`312313	// How long a Finished Play stands before the operator deletes it, in314	// seconds. The field is a pointer because zero and absent mean315	// different things: zero deletes the Play on the pass that sees it316	// finished, and absent takes defaultTTLSecondsAfterFinished. A plain317	// int64 would read an unset field as zero and delete every Play at318	// once.319	//320	// The window is the Play's own affair and not operator configuration,321	// because whoever creates a Play knows how long the record is worth322	// keeping: a library app sets the window its continue-watching feature323	// reads, and two apps on one cluster choose differently.324	TTLSecondsAfterFinished *int64 `json:"ttlSecondsAfterFinished,omitempty"`325326	// The per-Play override of the language preferences, the most specific tier.327	// A nil list, or an empty Subtitles, means this Play states nothing, so328	// resolution reads the Player next.329	AudioLanguages    []string `json:"audioLanguages,omitempty"`330	SubtitleLanguages []string `json:"subtitleLanguages,omitempty"`331	Subtitles         string   `json:"subtitles,omitempty"`332333	// The level this run starts at. The operator writes it through to334	// the unit's volume topic before it creates the pod, so the335	// override becomes the Player's state and everything after it is336	// the ordinary path. Absent, the run starts at whatever the topic337	// already holds.338	Volume *PlayVolume `json:"volume,omitempty"`339}340341// PlayVolume is a Play's starting level, its muted flag, or both.342// Each field is a pointer because absent and zero differ: an absent343// level carries nothing and leaves the unit where it stands, and a344// level of zero is silence the Play asked for.345type PlayVolume struct {346	Level *int  `json:"level,omitempty"`347	Muted *bool `json:"muted,omitempty"`348}349350// A PlayItem is one entry in the list: the media URI and an optional351// Presentation. The block is optional because a loose file needs only352// its URI, and the display falls back to what mpv reads from the file.353type PlayItem struct {354	URI          string        `json:"uri"`355	Presentation *Presentation `json:"presentation,omitempty"`356}357358// A Presentation declares what mpv cannot read from the file, so the359// display renders an item the way the library that fed liken describes360// it, not the way a container's tags happen to read.361//362// It carries the text fields and two art references, the logo and the363// trickplay directory. The resolver rewrites each the way it rewrites the364// media URI, so an nfs reference or a claim reference shares the media's365// mount and an https reference stays a URL.366type Presentation struct {367	Type         string `json:"type,omitempty"`368	Hint         string `json:"hint,omitempty"`369	Title        string `json:"title,omitempty"`370	Series       string `json:"series,omitempty"`371	Season       int    `json:"season,omitempty"`372	Episode      int    `json:"episode,omitempty"`373	EpisodeTitle string `json:"episodeTitle,omitempty"`374	Year         int    `json:"year,omitempty"`375	Date         string `json:"date,omitempty"`376	Logo         string `json:"logo,omitempty"`377378	// The two music text fields. An album states them so the display draws379	// the words the Play resolved, and the display reads no tags of its380	// own.381	Artist string `json:"artist,omitempty"`382	Album  string `json:"album,omitempty"`383384	// A reference to the item's cover image, resolved the way the logo is.385	// It is the first tier of the art the music layout draws, and the386	// picture inside the file and a cover beside it follow.387	Art string `json:"art,omitempty"`388389	// A reference to the item's X.trickplay directory, resolved the way the390	// logo is. The display shows a tile from its sprite sheets on the scrub391	// cursor.392	Trickplay string `json:"trickplay,omitempty"`393}394395// The status the operator alone writes: the phase, the activity396// word, the paused flag, the item counting from 1, the playhead, the397// pod's name, and the message that says why when a word is not398// enough. Every field is omitempty so a column with nothing to say399// shows blank in kubectl rather than a zero.400type PlayStatus struct {401	Phase    string `json:"phase,omitempty"`402	Activity string `json:"activity,omitempty"`403	Paused   bool   `json:"paused,omitempty"`404	Item     int    `json:"item,omitempty"`405	Position string `json:"position,omitempty"`406	Duration string `json:"duration,omitempty"`407	Pod      string `json:"pod,omitempty"`408	Message  string `json:"message,omitempty"`409410	// When the operator first read this run's phase as Finished, in RFC411	// 3339. The time-to-live after finishing counts from here and not from412	// the Play's creation, so the window measures the end of the film. It413	// lives on the status rather than in the operator's memory, so an414	// operator that restarts reads the clock back from the API server.415	FinishedAt string `json:"finishedAt,omitempty"`416417	// The preferences this run resolved, the console-parity record of what the418	// three tiers settled on.419	AudioLanguages    []string `json:"audioLanguages,omitempty"`420	SubtitleLanguages []string `json:"subtitleLanguages,omitempty"`421	Subtitles         string   `json:"subtitles,omitempty"`422423	// The language of the audio track and the subtitle track mpv selected, so a424	// code that matched no track shows plainly.425	AudioLanguage    string `json:"audioLanguage,omitempty"`426	SubtitleLanguage string `json:"subtitleLanguage,omitempty"`427}428429// The four phases, in the words Jobs and Pods use so nobody learns a430// new vocabulary. Finished and Failed are terminal: a phase moves431// forward only.432const (433	phasePending  = "Pending"434	phaseRunning  = "Running"435	phaseFinished = "Finished"436	phaseFailed   = "Failed"437)438439// The activity is the one word a person reads to know what the Play440// is doing right now. The phase is the lifecycle, which never goes441// backward; the activity folds the paused flag into that lifecycle,442// so a paused run reads Paused where the phase still reads Running.443const (444	activityStarting = "Starting"445	activityPlaying  = "Playing"446	activityPaused   = "Paused"447	activityFinished = "Finished"448	activityFailed   = "Failed"449)450451// playActivity is the phase and the paused flag folded into one452// word. A Play with no phase yet has no activity either, so an453// unwritten status stays blank.454func playActivity(phase string, paused bool) string {455	switch phase {456	case phasePending:457		return activityStarting458	case phaseRunning:459		if paused {460			return activityPaused461		}462		return activityPlaying463	case phaseFinished:464		return activityFinished465	case phaseFailed:466		return activityFailed467	}468	return ""469}470471// A Play in a terminal phase gets no further reconcile. Its pod and472// claim stay for reading until the Play is deleted, and the garbage473// collector tears them down then.474func terminalPhase(phase string) bool {475	return phase == phaseFinished || phase == phaseFailed476}477478// finishedPhase reports the one terminal phase the pass acts on. Only a479// Finished Play is done, so the pass skips it. A Failed Play resumes, so the480// pass reconciles it. terminalPhase still counts both, for the focus rule481// that a crashed run holds no controller.482func finishedPhase(phase string) bool {483	return phase == phaseFinished484}485486type PlayList struct {487	Metadata ListMeta `json:"metadata"`488	Items    []Play   `json:"items"`489}490491// The three subtitle modes a preference tier may state.492const (493	subtitlesOn   = "on"494	subtitlesOff  = "off"495	subtitlesAuto = "auto"496)497498// mediaPreferencesName is the one name a MediaPreferences may take. The CRD499// pins it with a CEL rule, so a second default is rejected at apply, and this500// operator reads the singleton by this name.501const mediaPreferencesName = "default"502503// MediaPreferences is the cluster-scoped household default for audio and504// subtitle languages, the lowest of the three tiers a Play resolves.505type MediaPreferences struct {506	APIVersion string               `json:"apiVersion,omitempty"`507	Kind       string               `json:"kind,omitempty"`508	Metadata   ObjectMeta           `json:"metadata"`509	Spec       MediaPreferencesSpec `json:"spec"`510}511512// MediaPreferencesSpec holds the default language fields. Resolution reads513// each field only when no more specific tier states it.514type MediaPreferencesSpec struct {515	AudioLanguages    []string `json:"audioLanguages,omitempty"`516	SubtitleLanguages []string `json:"subtitleLanguages,omitempty"`517	Subtitles         string   `json:"subtitles,omitempty"`518519	// The household wall-clock zone, an IANA name like America/New_York. One520	// per cluster, with no per-Play or per-Player override. The player pod521	// reads it as TZ, so the display clock shows local time.522	TimeZone string `json:"timeZone,omitempty"`523524	// Idle is the household default idle screen policy, read for each525	// field a Player's own block leaves unset.526	Idle *IdlePolicy `json:"idle,omitempty"`527}528529type MediaPreferencesList struct {530	Metadata ListMeta           `json:"metadata"`531	Items    []MediaPreferences `json:"items"`532}533534// A Remote is one physical controller: the device it is and, where535// its model needs one, the Keymap for its model. The operator reads the536// spec to build the standing pod and to hand each Play's command537// sidecar its topics, and writes the status to report which unit the538// controller drives now.539type Remote struct {540	APIVersion string       `json:"apiVersion,omitempty"`541	Kind       string       `json:"kind,omitempty"`542	Metadata   ObjectMeta   `json:"metadata"`543	Spec       RemoteSpec   `json:"spec"`544	Status     RemoteStatus `json:"status"`545}546547// RemoteStatus is what the operator reports on a Remote. Player is the548// Player the controller's retained focus mark names, so kubectl answers549// which unit a press reaches without a read of the bus. It is empty while550// no Player in the namespace lists the Remote.551//552// Unbound is the gap: every code the controller declares that its553// Keymap does not bind. It is empty when the Keymap binds every554// declared code, and absent while no standing pod has reported.555//556// Peripheral names the bluetooth-operator's Peripheral for the device557// this Remote's standing claim allocated. The name is the device's558// address in the lowercase dashed form, which is the device name the559// allocation result carries. It is empty while the claim carries no560// allocation, and for a controller some other driver publishes. The561// Peripheral is where a person reads the controller's link and its562// charge.563type RemoteStatus struct {564	Player     string        `json:"player,omitempty"`565	Peripheral string        `json:"peripheral,omitempty"`566	Unbound    []UnboundCode `json:"unbound,omitempty"`567}568569// UnboundCode is one code the controller declares and the Keymap570// leaves unbound: the raw evdev code, its name where the kernel gives571// it one, and which event type carries it.572type UnboundCode struct {573	Code uint16 `json:"code"`574	Name string `json:"name,omitempty"`575	Type string `json:"type"`576}577578// A Remote holds its device selector and the Keymap for its model,579// and it names no player. A Player names the Remotes it owns through580// spec.remotes, so the unit that owns a controller is the one that581// lists it.582//583// Discovery is the teaching mode: the standing pod keeps every node584// the claim delivered and logs each event the way a Keymap names it.585// Turning it on or off replaces the standing pod.586type RemoteSpec struct {587	Device    RemoteDevice `json:"device"`588	Keymap    string       `json:"keymap,omitempty"`589	Discovery bool         `json:"discovery,omitempty"`590}591592// The controller is selected the way a Player's display is, by a593// DeviceClass and a CEL expression. There is no parameters field,594// because nothing prepares an input device the way a codec prepares595// a sink.596type RemoteDevice struct {597	Class    string `json:"class"`598	Selector string `json:"selector,omitempty"`599}600601type RemoteList struct {602	Metadata ListMeta `json:"metadata"`603	Items    []Remote `json:"items"`604}605606// A Keymap is one controller model's table from its odd controls to607// the kernel key names they should report, written once per model and608// shared by every Remote of that model. A model whose kernel names are609// already right needs no Keymap at all.610type Keymap struct {611	APIVersion string     `json:"apiVersion,omitempty"`612	Kind       string     `json:"kind,omitempty"`613	Metadata   ObjectMeta `json:"metadata"`614	Spec       KeymapSpec `json:"spec"`615}616617// Buttons and axes are separate lists because they bind differently:618// a button is a press, and an axis entry names a direction as well.619// The CRD requires at least one entry across the two.620type KeymapSpec struct {621	Buttons []KeymapButton `json:"buttons,omitempty"`622	Axes    []KeymapAxis   `json:"axes,omitempty"`623}624625// KeymapList is the cluster-scoped collection the operator lists and626// watches, so a Keymap edit wakes the loop that recompiles and627// republishes it.628type KeymapList struct {629	Metadata ListMeta `json:"metadata"`630	Items    []Keymap `json:"items"`631}632633// A KeymapRepeat makes a row repeat while the control is held. The634// standing remote pod publishes the press, waits the delay, then635// publishes value 2 every interval until the release. The delay and636// the interval are durations, like 400ms or 1s, and each takes a637// default when it is empty. A control with no block reports only what638// the kernel reports.639type KeymapRepeat struct {640	Delay    string `json:"delay,omitempty"`641	Interval string `json:"interval,omitempty"`642}643644// Press is the control, an evdev key name out of buttonCodes. Key is645// the KEY_* name the controller reports instead, or none to drop the646// control. Both sides are the kernel's names, the way an hwdb entry is647// written.648type KeymapButton struct {649	Press  string        `json:"press"`650	Key    string        `json:"key"`651	Repeat *KeymapRepeat `json:"repeat,omitempty"`652}653654// An axis entry adds the value, because a hat axis reports -1 and 1655// as its two presses and 0 as the release: one axis is two rows.656type KeymapAxis struct {657	Axis   string        `json:"axis"`658	Value  int           `json:"value"`659	Key    string        `json:"key"`660	Repeat *KeymapRepeat `json:"repeat,omitempty"`661}662663// A ResourceClaim is the request for hardware. The operator664// writes only the spec. The scheduler writes the allocation into the665// status, and the pass reads it for one question: which screen the666// idle pod's draw request took.667type ResourceClaim struct {668	APIVersion string               `json:"apiVersion,omitempty"`669	Kind       string               `json:"kind,omitempty"`670	Metadata   ObjectMeta           `json:"metadata"`671	Spec       ResourceClaimSpec    `json:"spec"`672	Status     *ResourceClaimStatus `json:"status,omitempty"`673}674675type ResourceClaimSpec struct {676	Devices DeviceClaim `json:"devices"`677}678679// Requests name the devices by role and config carries driver680// parameters for them. Both are claim-level, so one claim covers the681// whole player.682type DeviceClaim struct {683	Requests []DeviceRequest            `json:"requests,omitempty"`684	Config   []DeviceClaimConfiguration `json:"config,omitempty"`685686	// Constraints tie named requests to one another, so two requests687	// allocate against the same piece of equipment.688	Constraints []DeviceConstraint `json:"constraints,omitempty"`689}690691// One constraint: the requests it covers, and the attribute whose692// value every one of those devices must share.693type DeviceConstraint struct {694	Requests       []string `json:"requests,omitempty"`695	MatchAttribute string   `json:"matchAttribute,omitempty"`696}697698// The request name is the role the pod refers to, and exactly is699// DRA's one-of that holds a plain request.700type DeviceRequest struct {701	Name    string              `json:"name"`702	Exactly *ExactDeviceRequest `json:"exactly,omitempty"`703}704705// ExactCount with count 1 asks for one device, no more offered and706// no fewer accepted. The selector list is omitted when the class707// alone chooses the device.708type ExactDeviceRequest struct {709	DeviceClassName string             `json:"deviceClassName"`710	AllocationMode  string             `json:"allocationMode,omitempty"`711	Count           int                `json:"count,omitempty"`712	Selectors       []DeviceSelector   `json:"selectors,omitempty"`713	Tolerations     []DeviceToleration `json:"tolerations,omitempty"`714}715716// A selector is a CEL expression over device.attributes, the same717// expression a hand-written claim would carry.718type DeviceSelector struct {719	CEL *CELDeviceSelector `json:"cel,omitempty"`720}721722type CELDeviceSelector struct {723	Expression string `json:"expression"`724}725726// A device taint evicts the pod that holds the device. A toleration727// with tolerationSeconds is how long the play survives an unplugged728// cable.729type DeviceToleration struct {730	Key               string `json:"key,omitempty"`731	Operator          string `json:"operator,omitempty"`732	Effect            string `json:"effect,omitempty"`733	TolerationSeconds *int64 `json:"tolerationSeconds,omitempty"`734}735736// An opaque config block reaches the driver unread by the scheduler,737// and requests names which of the claim's requests it applies to.738type DeviceClaimConfiguration struct {739	Requests []string                   `json:"requests,omitempty"`740	Opaque   *OpaqueDeviceConfiguration `json:"opaque,omitempty"`741}742743type OpaqueDeviceConfiguration struct {744	Driver     string          `json:"driver"`745	Parameters json.RawMessage `json:"parameters"`746}747748// The playback pod. The operator writes its spec once and reads its749// status every pass, because the pod's phase is where the Play's750// phase comes from.751type Pod struct {752	APIVersion string     `json:"apiVersion,omitempty"`753	Kind       string     `json:"kind,omitempty"`754	Metadata   ObjectMeta `json:"metadata"`755	Spec       PodSpec    `json:"spec"`756	Status     PodStatus  `json:"status"`757}758759// PodList is the pod collection ListPlaybackPods returns. Its760// resourceVersion is where the pod watch begins.761type PodList struct {762	Metadata ListMeta `json:"metadata"`763	Items    []Pod    `json:"items"`764}765766// The pod spec's few fields: restartPolicy Never because the pod's767// end is the play's end, and the short grace period because mpv768// exits promptly on SIGTERM.769//770// initContainers is where a native sidecar goes: an init container771// with restartPolicy Always starts before the ordinary containers,772// runs beside them, and restarts alone, without ending the pod.773type PodSpec struct {774	RestartPolicy                 string             `json:"restartPolicy,omitempty"`775	TerminationGracePeriodSeconds *int64             `json:"terminationGracePeriodSeconds,omitempty"`776	ResourceClaims                []PodResourceClaim `json:"resourceClaims,omitempty"`777	InitContainers                []Container        `json:"initContainers,omitempty"`778	Containers                    []Container        `json:"containers"`779	Volumes                       []Volume           `json:"volumes,omitempty"`780}781782// A pod names a claim once, and its containers refer to that name783// request by request, which is what keeps a device out of a784// container that must not hold it.785type PodResourceClaim struct {786	Name              string `json:"name"`787	ResourceClaimName string `json:"resourceClaimName,omitempty"`788}789790// Command replaces the image's entrypoint, which is how one image791// runs the playback pod's two roles. RestartPolicy is set only on an792// init container, where Always is what makes it a sidecar.793type Container struct {794	Name          string               `json:"name"`795	Image         string               `json:"image"`796	Command       []string             `json:"command,omitempty"`797	Args          []string             `json:"args,omitempty"`798	Env           []EnvVar             `json:"env,omitempty"`799	Resources     ResourceRequirements `json:"resources"`800	VolumeMounts  []VolumeMount        `json:"volumeMounts,omitempty"`801	RestartPolicy string               `json:"restartPolicy,omitempty"`802}803804// resources.claims is how a container holds one of the pod's805// claims, and request narrows it to one role inside that claim.806type ResourceRequirements struct {807	Claims []ContainerClaim `json:"claims,omitempty"`808}809810type ContainerClaim struct {811	Name    string `json:"name"`812	Request string `json:"request,omitempty"`813}814815type EnvVar struct {816	Name  string `json:"name"`817	Value string `json:"value,omitempty"`818}819820type VolumeMount struct {821	Name      string `json:"name"`822	MountPath string `json:"mountPath"`823	ReadOnly  bool   `json:"readOnly,omitempty"`824}825826// An inline NFS volume needs no PersistentVolume and no CSI driver.827// The kubelet mounts it with the kernel's NFS client, through the828// mount helper liken's image carries.829type Volume struct {830	Name                  string                             `json:"name"`831	NFS                   *NFSVolumeSource                   `json:"nfs,omitempty"`832	PersistentVolumeClaim *PersistentVolumeClaimVolumeSource `json:"persistentVolumeClaim,omitempty"`833	EmptyDir              *EmptyDirVolumeSource              `json:"emptyDir,omitempty"`834}835836type NFSVolumeSource struct {837	Server   string `json:"server"`838	Path     string `json:"path"`839	ReadOnly bool   `json:"readOnly,omitempty"`840}841842// A claim volume names a PersistentVolumeClaim in the pod's namespace.843// The kubelet resolves the claim when it starts the pod, so the operator844// reads no claim and no PersistentVolume, and its RBAC gains no rule.845// Read-only here and on the mount, because a player never writes to a846// library.847type PersistentVolumeClaimVolumeSource struct {848	ClaimName string `json:"claimName"`849	ReadOnly  bool   `json:"readOnly,omitempty"`850}851852// An emptyDir is a directory the kubelet creates with the pod and853// deletes with it, which is all two containers need to share one854// socket.855//856// SizeLimit caps the volume. The IPC volume leaves it empty, so it marshals as857// {}. The art volume sets it, so a runaway decode cannot fill the node disk.858type EmptyDirVolumeSource struct {859	SizeLimit string `json:"sizeLimit,omitempty"`860}861862// The pod status fields the phase derivation reads. The container's863// terminated state is the specific half of a failure message,864// because it carries the exit code.865type PodStatus struct {866	Phase             string            `json:"phase,omitempty"`867	Reason            string            `json:"reason,omitempty"`868	Message           string            `json:"message,omitempty"`869	Conditions        []PodCondition    `json:"conditions,omitempty"`870	ContainerStatuses []ContainerStatus `json:"containerStatuses,omitempty"`871}872873// The scheduler explains a pod it cannot place on the PodScheduled874// condition, not in the pod's message, so a hold like a claim that875// does not exist is only readable here.876type PodCondition struct {877	Type    string `json:"type"`878	Status  string `json:"status"`879	Message string `json:"message,omitempty"`880}881882type ContainerStatus struct {883	Name  string         `json:"name"`884	State ContainerState `json:"state"`885}886887type ContainerState struct {888	Terminated *ContainerStateTerminated `json:"terminated,omitempty"`889}890891type ContainerStateTerminated struct {892	ExitCode int    `json:"exitCode"`893	Reason   string `json:"reason,omitempty"`894	Message  string `json:"message,omitempty"`895}896897// The pod phases Kubernetes reports, named here so the derivation898// reads as the mapping it is.899const (900	podPending   = "Pending"901	podRunning   = "Running"902	podSucceeded = "Succeeded"903	podFailed    = "Failed"904)

1package main23// This is a Kubernetes client written straight against the HTTP API,4// following liken's own (kubernetes/apiclient.go) and the audio5// operator's, for the same reason: the API is HTTPS that serves6// JSON, and client-go would bring informers, work queues, and7// generated types this program does not use.8//9// Every pod already holds what it needs to reach the API server.10// Kubernetes injects two environment variables that name the11// server's in-cluster address, and the kubelet mounts a CA12// certificate and a ServiceAccount token at a known path. Those five13// values are the whole of an in-cluster config.1415import (16	"bytes"17	"crypto/tls"18	"crypto/x509"19	"encoding/json"20	"errors"21	"fmt"22	"io"23	"net"24	"net/http"25	"os"26	"time"27)2829// serviceAccountDir is a variable so a test points it at a directory30// it controls.31var serviceAccountDir = "/var/run/secrets/kubernetes.io/serviceaccount"3233// These two answers are values, not failures. An absent object is34// the normal state the caller answers by creating it, and a conflict35// is the normal state under optimistic concurrency that the caller36// answers by reading again.37var (38	ErrNotFound = errors.New("not found")39	ErrConflict = errors.New("conflict: something else wrote this object first")40)4142type Client struct {43	base        string44	http        *http.Client45	credentials string46}4748// NewClient builds a client from its three parts. InClusterClient49// reads them from the pod's environment; a test hands in an50// httptest server's base and no credentials.51func NewClient(base string, httpClient *http.Client, credentials string) *Client {52	return &Client{base: base, http: httpClient, credentials: credentials}53}5455func InClusterClient() (*Client, error) {56	host, port := os.Getenv("KUBERNETES_SERVICE_HOST"), os.Getenv("KUBERNETES_SERVICE_PORT")57	if host == "" || port == "" {58		return nil, fmt.Errorf("not running in a cluster: KUBERNETES_SERVICE_HOST unset")59	}6061	// The client trusts the cluster's own CA and not the system62	// store, so it accepts this API server and no other server that63	// answers on the address.64	caPEM, err := os.ReadFile(serviceAccountDir + "/ca.crt")65	if err != nil {66		return nil, fmt.Errorf("reading service account CA: %w", err)67	}68	roots := x509.NewCertPool()69	if !roots.AppendCertsFromPEM(caPEM) {70		return nil, fmt.Errorf("service account CA contains no certificates")71	}7273	return NewClient("https://"+host+":"+port, &http.Client{74		Transport: &http.Transport{75			TLSClientConfig: &tls.Config{RootCAs: roots},76			// Each timeout bounds the same failure: a server that77			// stops answering without sending anything. There is no78			// overall client timeout, because the watch is a request79			// whose response never ends, and a whole-request80			// deadline would cut the stream on schedule.81			DialContext: (&net.Dialer{82				Timeout:   5 * time.Second,83				KeepAlive: 10 * time.Second,84			}).DialContext,85			ResponseHeaderTimeout: 10 * time.Second,86			IdleConnTimeout:       30 * time.Second,87		},88	}, serviceAccountDir), nil89}9091// The two content types this client sends. A body is JSON,92// except an apply, which the API server reads as a partial object93// under the caller's field manager. The apply media type is named for94// YAML and accepts JSON, because YAML is its superset.95const (96	jsonContentType  = "application/json"97	applyContentType = "application/apply-patch+yaml"98)99100// Do sends one request and hands back the open response, which is101// what the watch needs and what RequestJSON is built on.102func (c *Client) Do(method, path string, body []byte) (*http.Response, error) {103	return c.send(method, path, jsonContentType, body)104}105106func (c *Client) send(method, path, contentType string, body []byte) (*http.Response, error) {107	var reader io.Reader108	if body != nil {109		reader = bytes.NewReader(body)110	}111	req, err := http.NewRequest(method, c.base+path, reader)112	if err != nil {113		return nil, err114	}115	// The token is read from disk on every request. The mounted116	// token is short-lived and the kubelet refreshes the file as117	// each one nears expiry, so a client that held one in memory118	// would start getting 401s.119	if c.credentials != "" {120		token, err := os.ReadFile(c.credentials + "/token")121		if err != nil {122			return nil, fmt.Errorf("reading service account token: %w", err)123		}124		req.Header.Set("Authorization", "Bearer "+string(token))125	}126	req.Header.Set("Accept", "application/json")127	if body != nil {128		req.Header.Set("Content-Type", contentType)129	}130	return c.http.Do(req)131}132133// RequestJSON sends one request and decodes the answer, turning134// every non-2xx status into an error that carries the server's own135// message.136func (c *Client) RequestJSON(method, path string, body []byte, out any) error {137	return c.requestJSON(method, path, jsonContentType, body, out)138}139140func (c *Client) requestJSON(method, path, contentType string, body []byte, out any) error {141	resp, err := c.send(method, path, contentType, body)142	if err != nil {143		return err144	}145	defer drain(resp.Body)146147	if resp.StatusCode == http.StatusNotFound {148		return ErrNotFound149	}150	if resp.StatusCode == http.StatusConflict {151		return ErrConflict152	}153	if resp.StatusCode < 200 || resp.StatusCode > 299 {154		message, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))155		return fmt.Errorf("%s %s: %s: %s", method, path, resp.Status, message)156	}157	if out == nil {158		return nil159	}160	return json.NewDecoder(resp.Body).Decode(out)161}162163// drain reads whatever the caller left in the body, then closes it.164// Go returns a connection to its pool only when the body reaches165// EOF, so an early close costs a fresh connection and TLS handshake,166// and reaches the server as a hang-up on a request it answered.167const maxDrain = 4 << 20168169func drain(body io.ReadCloser) {170	_, _ = io.Copy(io.Discard, io.LimitReader(body, maxDrain))171	_ = body.Close()172}173174// The collection paths. Plays are listed and watched across every175// namespace and read back per namespace, and the two Kubernetes176// kinds this operator writes live under their own groups' paths.177const (178	playsPath       = "/apis/" + mediaAPIVersion + "/plays"179	playersPath     = "/apis/" + mediaAPIVersion + "/players"180	remotesAllPath  = "/apis/" + mediaAPIVersion + "/remotes"181	keymapsPath     = "/apis/" + mediaAPIVersion + "/keymaps"182	mediaPrefsPath  = "/apis/" + mediaAPIVersion + "/mediapreferences"183	mediaPrefix     = "/apis/" + mediaAPIVersion + "/namespaces/"184	claimPrefix     = "/apis/" + claimAPIVersion + "/namespaces/"185	slicesPath      = "/apis/" + claimAPIVersion + "/resourceslices"186	displaysPath    = "/apis/" + displayAPIVersion + "/displays"187	peripheralsPath = "/apis/" + peripheralAPIVersion + "/peripherals"188	podPrefix       = "/api/v1/namespaces/"189	podsAllPath     = "/api/v1/pods"190)191192// playbackPodsQuery narrows a pod list or a pod watch to the operator's own193// playback pods, by the label buildPod stamps on each one.194const playbackPodsQuery = "labelSelector=" + playbackLabelKey + "%3D" + playbackLabelValue195196func playPath(namespace, name string) string {197	return mediaPrefix + namespace + "/plays/" + name198}199200func playerPath(namespace, name string) string {201	return mediaPrefix + namespace + "/players/" + name202}203204func remotesPath(namespace string) string {205	return mediaPrefix + namespace + "/remotes"206}207208func remotePath(namespace, name string) string {209	return remotesPath(namespace) + "/" + name210}211212// keymapPath reads one Keymap by name. A Keymap is cluster-scoped, so213// the path carries no namespace, the way a StorageClass path carries214// none.215func keymapPath(name string) string {216	return keymapsPath + "/" + name217}218219func claimsPath(namespace string) string {220	return claimPrefix + namespace + "/resourceclaims"221}222223func podsPath(namespace string) string {224	return podPrefix + namespace + "/pods"225}226227// ListPlays answers a whole pass with one request, and the list's228// resourceVersion is where a watch resumes from.229func ListPlays(c *Client) (*PlayList, error) {230	list := &PlayList{}231	if err := c.RequestJSON(http.MethodGet, playsPath, nil, list); err != nil {232		return nil, err233	}234	return list, nil235}236237func GetPlay(c *Client, namespace, name string) (*Play, error) {238	play := &Play{}239	if err := c.RequestJSON(http.MethodGet, playPath(namespace, name), nil, play); err != nil {240		return nil, err241	}242	return play, nil243}244245// DeletePlay removes one Play once its window after finishing has passed.246// It is the one object a person created that this operator deletes, and it247// deletes it only in that one state. An already-absent Play is success,248// because a person may delete a Finished Play before its window ends.249func DeletePlay(c *Client, namespace, name string) error {250	err := c.RequestJSON(http.MethodDelete, playPath(namespace, name), nil, nil)251	if errors.Is(err, ErrNotFound) {252		return nil253	}254	return err255}256257// ListPlayers answers a pass with one request across every258// namespace, the same shape as ListPlays, because a Player's status259// is derived from the Plays that name it and the pass already holds260// every Play.261func ListPlayers(c *Client) (*PlayerList, error) {262	list := &PlayerList{}263	if err := c.RequestJSON(http.MethodGet, playersPath, nil, list); err != nil {264		return nil, err265	}266	return list, nil267}268269// PutPlayerStatus writes the Player's status subresource, the one270// write path this operator has onto a Player.271func PutPlayerStatus(c *Client, player *Player) (*Player, error) {272	body, err := json.Marshal(player)273	if err != nil {274		return nil, err275	}276	written := &Player{}277	path := playerPath(player.Metadata.Namespace, player.Metadata.Name) + "/status"278	if err := c.RequestJSON(http.MethodPut, path, body, written); err != nil {279		return nil, err280	}281	return written, nil282}283284func GetPlayer(c *Client, namespace, name string) (*Player, error) {285	player := &Player{}286	if err := c.RequestJSON(http.MethodGet, playerPath(namespace, name), nil, player); err != nil {287		return nil, err288	}289	return player, nil290}291292// PutPlayStatus writes through the status subresource, which is its293// own write path: this request can never touch a spec. The294// resourceVersion in the body is what makes the write conditional.295func PutPlayStatus(c *Client, play *Play) (*Play, error) {296	body, err := json.Marshal(play)297	if err != nil {298		return nil, err299	}300	written := &Play{}301	path := playPath(play.Metadata.Namespace, play.Metadata.Name) + "/status"302	if err := c.RequestJSON(http.MethodPut, path, body, written); err != nil {303		return nil, err304	}305	return written, nil306}307308// GetRemote reads one Remote by name in a namespace, the name a309// Player's spec.remotes entry carries.310func GetRemote(c *Client, namespace, name string) (*Remote, error) {311	remote := &Remote{}312	if err := c.RequestJSON(http.MethodGet, remotePath(namespace, name), nil, remote); err != nil {313		return nil, err314	}315	return remote, nil316}317318// PutRemoteStatus writes the Remote's status subresource, the one write319// path this operator has onto a Remote. The subresource split keeps it320// from ever rewriting the device selector a person declared.321func PutRemoteStatus(c *Client, remote *Remote) (*Remote, error) {322	body, err := json.Marshal(remote)323	if err != nil {324		return nil, err325	}326	written := &Remote{}327	path := remotePath(remote.Metadata.Namespace, remote.Metadata.Name) + "/status"328	if err := c.RequestJSON(http.MethodPut, path, body, written); err != nil {329		return nil, err330	}331	return written, nil332}333334// ListAllRemotes reads every Remote in the cluster in one request, the335// same shape as ListPlays, because the operator reconciles a standing336// pod for each Remote whatever namespace it lives in, and the list's337// resourceVersion is where the remotes watch resumes from.338func ListAllRemotes(c *Client) (*RemoteList, error) {339	list := &RemoteList{}340	if err := c.RequestJSON(http.MethodGet, remotesAllPath, nil, list); err != nil {341		return nil, err342	}343	return list, nil344}345346func GetKeymap(c *Client, name string) (*Keymap, error) {347	keymap := &Keymap{}348	if err := c.RequestJSON(http.MethodGet, keymapPath(name), nil, keymap); err != nil {349		return nil, err350	}351	return keymap, nil352}353354// ListKeymaps reads every Keymap in the cluster in one request, because355// the operator compiles and publishes each one on every pass, and the356// list's resourceVersion is where the keymaps watch resumes from.357func ListKeymaps(c *Client) (*KeymapList, error) {358	list := &KeymapList{}359	if err := c.RequestJSON(http.MethodGet, keymapsPath, nil, list); err != nil {360		return nil, err361	}362	return list, nil363}364365// GetMediaPreferences reads the household default by name. MediaPreferences is366// cluster-scoped, so the path carries no namespace. A missing default is367// ErrNotFound, which the resolver reads as a skipped tier.368func GetMediaPreferences(c *Client, name string) (*MediaPreferences, error) {369	prefs := &MediaPreferences{}370	if err := c.RequestJSON(http.MethodGet, mediaPrefsPath+"/"+name, nil, prefs); err != nil {371		return nil, err372	}373	return prefs, nil374}375376// ListMediaPreferences reads every MediaPreferences in one request. The list's377// resourceVersion is where the watch resumes from.378func ListMediaPreferences(c *Client) (*MediaPreferencesList, error) {379	list := &MediaPreferencesList{}380	if err := c.RequestJSON(http.MethodGet, mediaPrefsPath, nil, list); err != nil {381		return nil, err382	}383	return list, nil384}385386func GetResourceClaim(c *Client, namespace, name string) (*ResourceClaim, error) {387	claim := &ResourceClaim{}388	if err := c.RequestJSON(http.MethodGet, claimsPath(namespace)+"/"+name, nil, claim); err != nil {389		return nil, err390	}391	return claim, nil392}393394func CreateResourceClaim(c *Client, claim *ResourceClaim) (*ResourceClaim, error) {395	body, err := json.Marshal(claim)396	if err != nil {397		return nil, err398	}399	created := &ResourceClaim{}400	if err := c.RequestJSON(http.MethodPost, claimsPath(claim.Metadata.Namespace), body, created); err != nil {401		return nil, err402	}403	return created, nil404}405406// ListPlaybackPods reads the operator's playback pods across every407// namespace. The list's resourceVersion is where the pod watch begins.408func ListPlaybackPods(c *Client) (*PodList, error) {409	list := &PodList{}410	if err := c.RequestJSON(http.MethodGet, podsAllPath+"?"+playbackPodsQuery, nil, list); err != nil {411		return nil, err412	}413	return list, nil414}415416func GetPod(c *Client, namespace, name string) (*Pod, error) {417	pod := &Pod{}418	if err := c.RequestJSON(http.MethodGet, podsPath(namespace)+"/"+name, nil, pod); err != nil {419		return nil, err420	}421	return pod, nil422}423424func CreatePod(c *Client, pod *Pod) (*Pod, error) {425	body, err := json.Marshal(pod)426	if err != nil {427		return nil, err428	}429	created := &Pod{}430	if err := c.RequestJSON(http.MethodPost, podsPath(pod.Metadata.Namespace), body, created); err != nil {431		return nil, err432	}433	return created, nil434}435436// DeletePod removes one playback pod. An already-absent pod is437// success, because the graceful recreate deletes the pod before it438// creates the replacement, and a delete that races another pass must439// not fail.440func DeletePod(c *Client, namespace, name string) error {441	err := c.RequestJSON(http.MethodDelete, podsPath(namespace)+"/"+name, nil, nil)442	if errors.Is(err, ErrNotFound) {443		return nil444	}445	return err446}447448// Every driver's slices in one request. The operator reads449// them for the attributes of the devices its own claims hold, so one450// list a pass answers every unit.451func ListResourceSlices(c *Client) (*ResourceSliceList, error) {452	list := &ResourceSliceList{}453	if err := c.RequestJSON(http.MethodGet, slicesPath, nil, list); err != nil {454		return nil, err455	}456	return list, nil457}458459// A Display is cluster-scoped, so the path carries no460// namespace. A screen whose cluster runs no display-operator answers461// ErrNotFound, and the panel then stays lit.462func GetDisplay(c *Client, name string) (*Display, error) {463	display := &Display{}464	if err := c.RequestJSON(http.MethodGet, displaysPath+"/"+name, nil, display); err != nil {465		return nil, err466	}467	return display, nil468}469470// ListPeripherals reads every bonded device the bluetooth-operator471// publishes. A Peripheral is cluster-scoped, so the path carries no472// namespace, and the list's resourceVersion is where the peripherals473// watch resumes from.474func ListPeripherals(c *Client) (*PeripheralList, error) {475	list := &PeripheralList{}476	if err := c.RequestJSON(http.MethodGet, peripheralsPath, nil, list); err != nil {477		return nil, err478	}479	return list, nil480}481482// ApplyDisplayOverride writes spec.override and nothing else,483// under this operator's own field manager. A nil override applies an484// empty spec, and the API server then removes the block this manager485// owns, which is how the panel comes back.486func ApplyDisplayOverride(c *Client, name string, override *DisplayOverride) error {487	body, err := json.Marshal(&displayApply{488		APIVersion: displayAPIVersion,489		Kind:       "Display",490		Metadata:   ObjectMeta{Name: name},491		Spec:       DisplaySpec{Override: override},492	})493	if err != nil {494		return err495	}496	path := displaysPath + "/" + name + "?fieldManager=" + displayFieldManager497	return c.requestJSON(http.MethodPatch, path, applyContentType, body, nil)498}499500// DeleteResourceClaim removes one playback claim. The operator deletes501// a claim only when a Player reshaped it, so the recreate builds the502// claim the current Player produces. An already-absent claim is503// success.504func DeleteResourceClaim(c *Client, namespace, name string) error {505	err := c.RequestJSON(http.MethodDelete, claimsPath(namespace)+"/"+name, nil, nil)506	if errors.Is(err, ErrNotFound) {507		return nil508	}509	return err510}

1package main23// The bridge decodes the art the display cannot. overlay-add takes raw bgra,4// and mpv's Lua has no image decoder. So the display asks the bridge for a5// logo at a pixel size. The bridge reads the file, scales it, writes the bgra6// to the volume it shares with mpv, and answers with the path and the size.7// The scaler is a small bilinear resampler on the standard library, so the8// decoder needs no dependency and no cgo.910import (11	"encoding/json"12	"fmt"13	"image"14	_ "image/jpeg"15	_ "image/png"16	"io"17	"math"18	"net/http"19	"os"20	"path/filepath"21	"strconv"22	"strings"23)2425// One decoded logo, ready for overlay-add: the file the bridge wrote, and the26// size mpv needs to read it back.27type artBlob struct {28	path   string29	width  int30	height int31	stride int32}3334// One parsed art request. timeMs carries the scrub time for a trickplay35// request, and stays zero for every other kind, which needs only the box.36// The box is the bounds the logo, the cover, or the tile must fit inside.37type artRequest struct {38	kind   string39	timeMs int40	width  int41	height int42}4344// parseArtRequest reads a client-message as a request for art. The first45// argument names the request, so the bridge drops another script's broadcast.46// The rest depends on the kind: a logo and a cover carry a box, and a47// trickplay carries a time and a box.48func parseArtRequest(args []string) (artRequest, bool) {49	if len(args) < 4 || args[0] != artRequestMessage {50		return artRequest{}, false51	}52	switch args[1] {53	case artKindLogo, artKindAlbum:54		w, h, ok := parseBox(args[2], args[3])55		if !ok {56			return artRequest{}, false57		}58		return artRequest{kind: args[1], width: w, height: h}, true59	case artKindTrickplay:60		if len(args) < 5 {61			return artRequest{}, false62		}63		timeMs, err := strconv.Atoi(args[2])64		if err != nil || timeMs < 0 {65			return artRequest{}, false66		}67		w, h, ok := parseBox(args[3], args[4])68		if !ok {69			return artRequest{}, false70		}71		return artRequest{kind: artKindTrickplay, timeMs: timeMs, width: w, height: h}, true72	}73	return artRequest{}, false74}7576// parseBox reads a width and a height from two arguments. A value that is not77// a positive number fails the request, so a bad box decodes nothing.78func parseBox(widthArg, heightArg string) (w, h int, ok bool) {79	w, err := strconv.Atoi(widthArg)80	if err != nil || w <= 0 {81		return 0, 0, false82	}83	h, err = strconv.Atoi(heightArg)84	if err != nil || h <= 0 {85		return 0, 0, false86	}87	return w, h, true88}8990// serveArt answers one art request. It dispatches by kind, the logo to91// serveLogo, the trickplay tile to serveTrickplay, and the playing album's92// cover to serveAlbum.93func (c *commander) serveArt(args []string) {94	request, ok := parseArtRequest(args)95	if !ok {96		return97	}98	switch request.kind {99	case artKindLogo:100		c.serveLogo(request)101	case artKindTrickplay:102		c.serveTrickplay(request)103	case artKindAlbum:104		c.serveAlbum(request)105	}106}107108// serveLogo decodes the current item's logo to the box the display asks for,109// caches the blob by size, and replies. A size already decoded for the current110// item replies from the cache and decodes nothing.111func (c *commander) serveLogo(request artRequest) {112	kind, w, h := request.kind, request.width, request.height113	key := kind + ":" + strconv.Itoa(w) + "x" + strconv.Itoa(h)114	c.artMutex.Lock()115	item := c.artItem116	if blob, cached := c.artCache[key]; cached {117		c.artMutex.Unlock()118		c.replyArt(kind, blob)119		return120	}121	block := c.blockForItem(item)122	c.artMutex.Unlock()123124	logo := logoOf(block)125	if logo == "" {126		return127	}128129	blob, err := c.decodeLogo(item, logo, w, h)130	if err != nil {131		fmt.Fprintf(os.Stderr, "command: logo %q: %v\n", logo, err)132		return133	}134135	c.artMutex.Lock()136	if item != c.artItem {137		// The item swapped while the decode ran. Drop this blob, so the last138		// item's art does not stay on the shared volume.139		c.artMutex.Unlock()140		os.Remove(blob.path)141		return142	}143	if c.artCache == nil {144		c.artCache = map[string]artBlob{}145	}146	c.artCache[key] = blob147	c.artMutex.Unlock()148149	c.replyArt(kind, blob)150}151152// decodeLogo reads one logo, scales it into the box, and writes the bgra to153// the shared volume. An https logo is fetched. Any other value is a path the154// resolver rewrote under the media mount.155func (c *commander) decodeLogo(item int, logo string, w, h int) (artBlob, error) {156	reader, err := openArt(logo)157	if err != nil {158		return artBlob{}, err159	}160	defer reader.Close()161162	pixels, outW, outH, stride, err := scaleToBGRA(reader, w, h)163	if err != nil {164		return artBlob{}, err165	}166167	path := filepath.Join(c.artDir, fmt.Sprintf("logo-%d-%dx%d.bgra", item, w, h))168	if err := os.WriteFile(path, pixels, 0o644); err != nil {169		return artBlob{}, err170	}171	return artBlob{path: path, width: outW, height: outH, stride: stride}, nil172}173174// openArt opens a logo for reading. An https logo is a network fetch. Any175// other value is a file the pod mounts.176func openArt(logo string) (io.ReadCloser, error) {177	if strings.HasPrefix(logo, "https://") {178		response, err := http.Get(logo)179		if err != nil {180			return nil, err181		}182		if response.StatusCode != http.StatusOK {183			response.Body.Close()184			return nil, fmt.Errorf("fetch returned %s", response.Status)185		}186		return response.Body, nil187	}188	return os.Open(logo)189}190191// replyArt hands the display one ready blob over the mpv socket. The display192// registers artReplyMessage and places the blob with overlay-add.193func (c *commander) replyArt(kind string, blob artBlob) {194	c.command([]any{195		"script-message-to", displayClientName, artReplyMessage,196		kind, blob.path,197		strconv.Itoa(blob.width), strconv.Itoa(blob.height), strconv.Itoa(blob.stride),198	})199}200201// logoOf reads the logo path from one presentation block. An empty block, or202// one with no logo, has none.203func logoOf(block []byte) string {204	var presentation Presentation205	if err := json.Unmarshal(block, &presentation); err != nil {206		return ""207	}208	return presentation.Logo209}210211// scaleToBGRA decodes an image and scales it to fit within boxW by boxH,212// keeping the aspect ratio. It returns premultiplied bgra with stride 4*w, the213// one format overlay-add reads. Go's image package returns alpha-premultiplied214// color, and blending in that space keeps a transparent edge clean.215func scaleToBGRA(reader io.Reader, boxW, boxH int) (pixels []byte, w, h, stride int, err error) {216	source, _, err := image.Decode(reader)217	if err != nil {218		return nil, 0, 0, 0, err219	}220	return scaleRegionToBGRA(source, source.Bounds(), boxW, boxH)221}222223// scaleRegionToBGRA scales one rectangle of a decoded image to fit within boxW224// by boxH, keeping the aspect ratio. It returns premultiplied bgra with stride225// 4*w, the one format overlay-add reads. A logo passes the image's full bounds.226// A trickplay passes one cell of a sprite sheet, so the crop and the scale are227// one step.228func scaleRegionToBGRA(source image.Image, region image.Rectangle, boxW, boxH int) (pixels []byte, w, h, stride int, err error) {229	sw, sh := region.Dx(), region.Dy()230	if sw <= 0 || sh <= 0 {231		return nil, 0, 0, 0, fmt.Errorf("the image has no pixels")232	}233234	scale := math.Min(float64(boxW)/float64(sw), float64(boxH)/float64(sh))235	outW := max(1, int(math.Round(float64(sw)*scale)))236	outH := max(1, int(math.Round(float64(sh)*scale)))237	stride = 4 * outW238	pixels = make([]byte, stride*outH)239240	for y := 0; y < outH; y++ {241		// The half-pixel offset samples each output pixel at its own center,242		// so the scaled image does not drift half a pixel.243		fy := (float64(y)+0.5)/scale - 0.5244		for x := 0; x < outW; x++ {245			fx := (float64(x)+0.5)/scale - 0.5246			r, g, b, a := sampleBilinear(source, region, fx, fy)247			offset := y*stride + x*4248			pixels[offset+0] = b249			pixels[offset+1] = g250			pixels[offset+2] = r251			pixels[offset+3] = a252		}253	}254	return pixels, outW, outH, stride, nil255}256257// sampleBilinear reads the four source pixels around (fx, fy) and blends them,258// so a scaled edge is smooth. The coordinates are in the source's own pixels,259// measured from its bounds origin.260func sampleBilinear(source image.Image, bounds image.Rectangle, fx, fy float64) (r, g, b, a byte) {261	x0 := int(math.Floor(fx))262	y0 := int(math.Floor(fy))263	dx := fx - float64(x0)264	dy := fy - float64(y0)265266	r00, g00, b00, a00 := sampleClamped(source, bounds, x0, y0)267	r10, g10, b10, a10 := sampleClamped(source, bounds, x0+1, y0)268	r01, g01, b01, a01 := sampleClamped(source, bounds, x0, y0+1)269	r11, g11, b11, a11 := sampleClamped(source, bounds, x0+1, y0+1)270271	blend := func(v00, v10, v01, v11 float64) byte {272		top := v00 + (v10-v00)*dx273		bottom := v01 + (v11-v01)*dx274		value := top + (bottom-top)*dy275		// Go returns each channel in 0..65535, so the high byte is the 8-bit276		// value overlay-add reads.277		return byte(uint32(value+0.5) >> 8)278	}279	return blend(r00, r10, r01, r11),280		blend(g00, g10, g01, g11),281		blend(b00, b10, b01, b11),282		blend(a00, a10, a01, a11)283}284285// sampleClamped reads one source pixel. It clamps to the edge for a coordinate286// the blend reaches past the image. The channels are the alpha-premultiplied287// values the image package gives, each 0..65535.288func sampleClamped(source image.Image, bounds image.Rectangle, x, y int) (r, g, b, a float64) {289	if x < 0 {290		x = 0291	}292	if x > bounds.Dx()-1 {293		x = bounds.Dx() - 1294	}295	if y < 0 {296		y = 0297	}298	if y > bounds.Dy()-1 {299		y = bounds.Dy() - 1300	}301	ri, gi, bi, ai := source.At(bounds.Min.X+x, bounds.Min.Y+y).RGBA()302	return float64(ri), float64(gi), float64(bi), float64(ai)303}

1package main23// serve-art runs the bridge's decode side on its own, against a plain mpv IPC4// socket. The pod runs the whole command sidecar, which also reports to the5// bus. A person iterating on the display locally wants the decode half with no6// cluster and no bus. So this mode dials a socket, reads the same presentation7// blocks the pod passes, and runs the same decode and serve code the sidecar8// runs. The local screenshots then show art decoded the way the pod decodes it.910import (11	"context"12	"fmt"13	"os"14	"os/signal"15	"syscall"16)1718// serve-art reads two variables on top of the presentation blocks. It reads a19// socket path, because a local mpv serves its socket somewhere other than the20// pod's fixed path. It reads an art directory, because a local run has no21// mounted volume. Both take a default, so the mode runs with neither set.22const (23	mpvSocketVariable = "MEDIA_MPV_SOCKET"24	artDirVariable    = "MEDIA_ART_DIR"25)2627// runArtServe dials the socket and runs the decode side with a report sender28// that publishes nothing. The item tracking and the logo decode then run as29// they do in the pod, with no bus.30func runArtServe() {31	socket := os.Getenv(mpvSocketVariable)32	if socket == "" {33		socket = mpvSocketPath34	}35	artDir := os.Getenv(artDirVariable)36	if artDir == "" {37		artDir = artMountPath38	}3940	cmd := &commander{41		presentations: parsePresentations(os.Getenv(presentationsVariable)),42		artDir:        artDir,43	}4445	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)46	defer stop()4748	conn, err := dialMPV(ctx, socket)49	if err != nil {50		fmt.Fprintf(os.Stderr, "serve-art: %v\n", err)51		return52	}53	defer conn.Close()54	defer context.AfterFunc(ctx, func() { conn.Close() })()5556	cmd.drive(ctx, conn, func(playReport) error { return nil })57}

1package main23// The base table, the layer under every Keymap. Linux splits input in4// two: the kernel and udev's hwdb normalise a device, so a scancode5// becomes KEY_VOLUMEUP, and each program binds those names to what6// they mean there. The base is this operator's half of the first7// layer. Every KEY_* code passes as itself with no row, so a Remote8// with no Keymap already works. The base binds only what the kernel9// cannot name as a key: the hat axes become the arrows, because a10// d-pad is not a button, and the south and east face buttons become11// enter and back, because every console reads them that way. Nothing12// else in the base binds a button.1314import "fmt"1516// The hat repeat cadence. A gamepad never autorepeats in the kernel,17// so the standing pod synthesises the repeat, and 400ms then 250ms is18// the cadence a person expects from a keyboard's arrows.19var baseHatRepeat = KeymapRepeat{Delay: "400ms", Interval: "250ms"}2021// The base itself, written as a Keymap so it compiles through the22// same path a cluster's Keymap does. This is the one place the23// project states what a controller means before anybody writes a24// row.25var baseKeymap = &Keymap{26	Metadata: ObjectMeta{Name: "base"},27	Spec: KeymapSpec{28		Buttons: []KeymapButton{29			{Press: "BTN_SOUTH", Key: "KEY_ENTER"},30			{Press: "BTN_EAST", Key: "KEY_BACK"},31		},32		Axes: []KeymapAxis{33			{Axis: "ABS_HAT0Y", Value: -1, Key: "KEY_UP", Repeat: &baseHatRepeat},34			{Axis: "ABS_HAT0Y", Value: 1, Key: "KEY_DOWN", Repeat: &baseHatRepeat},35			{Axis: "ABS_HAT0X", Value: -1, Key: "KEY_LEFT", Repeat: &baseHatRepeat},36			{Axis: "ABS_HAT0X", Value: 1, Key: "KEY_RIGHT", Repeat: &baseHatRepeat},37		},38	},39}4041// baseKeys is the compiled base. A failure here panics at start,42// because the rows are compiled into the binary: a name this build43// cannot resolve is a fault in this file and not in a cluster's44// object.45var baseKeys = mustCompileBase()4647func mustCompileBase() []compiledBinding {48	rows, err := compileRows(baseKeymap)49	if err != nil {50		panic(fmt.Sprintf("the base key table does not compile: %v", err))51	}52	return rows53}5455// compileTable is the whole fold: the base first, then the Remote's56// Keymap over it, one row replacing the base row for the same57// control. A Remote with no Keymap gets the base alone. The order is58// stable, because the operator compares the published payload against59// the last one it wrote.60func compileTable(keymap *Keymap) ([]compiledBinding, error) {61	table := make([]compiledBinding, len(baseKeys))62	copy(table, baseKeys)63	if keymap == nil {64		return table, nil65	}66	rows, err := compileRows(keymap)67	if err != nil {68		return nil, err69	}70	for _, row := range rows {71		if index := indexOfControl(table, row); index >= 0 {72			table[index] = row73			continue74		}75		table = append(table, row)76	}77	return table, nil78}7980// indexOfControl finds the row that names the same control. A button81// row always carries value 1, and an axis row carries the direction,82// so the three fields together are the control's identity.83func indexOfControl(table []compiledBinding, row compiledBinding) int {84	for index, held := range table {85		if held.EventType == row.EventType && held.Code == row.Code && held.Value == row.Value {86			return index87		}88	}89	return -190}9192// lookupKey is the match the standing pod runs on every event. The93// value is normalised for a key and exact for an axis: a key's row94// states the press, and the release and the autorepeat carry the same95// meaning under the same name, while a hat's two directions are two96// rows on one code.97func lookupKey(table []compiledBinding, event inputEvent) (compiledBinding, bool) {98	value := event.Value99	if event.Type == evKey {100		value = 1101	}102	for _, row := range table {103		if row.EventType == event.Type && row.Code == event.Code && row.Value == value {104			return row, true105		}106	}107	return compiledBinding{}, false108}

1package main23// The bus client is one live TCP connection to the broker, with a4// reader, a single writer, and a keepalive timer, and it reconnects5// with backoff whenever any of the three fails. Every mode of this6// operator that speaks to the broker holds one Bus and lets it manage7// the connection, so no caller writes the socket directly.8//9// All writes go through one goroutine and one channel, because two10// goroutines writing one TCP connection would interleave their bytes11// and corrupt a packet. A publish or a subscribe from any goroutine12// enqueues a finished frame, and the writer sends it.1314import (15	"bufio"16	"context"17	"net"18	"sort"19	"sync"20	"time"21)2223// The keepalive the client asks the broker for, and the queue the24// writer drains. The client sends a PINGREQ once the connection has25// been idle longer than half the keepalive, so the broker never26// reaches the keepalive without hearing from the client. The queue is27// bounded, and a publish that would overflow it is dropped, which is28// correct at QoS 0.29const (30	busKeepalive  = 3031	busQueueDepth = 6432)3334// The reconnect backoff bounds. The client waits busMinBackoff after35// the first failure and doubles the wait up to busMaxBackoff, so a36// broker that is down does not become a tight reconnect loop. Both are37// variables so a test drives a reconnect in milliseconds.38var (39	busMinBackoff = time.Second40	busMaxBackoff = 30 * time.Second41)4243// busHandler receives one inbound message's topic and payload. The Bus44// calls it on the reader goroutine, so a handler that blocks holds up45// every later message on the connection.46type busHandler func(topic string, payload []byte)4748// busWill is the MQTT Last Will the client names at connect time. The49// broker publishes it on any disconnect the client does not make50// cleanly, which is how a killed pod's status is marked offline.51type busWill struct {52	Topic    string53	Payload  []byte54	Retained bool55}5657// Bus holds the connection's parts and the state that outlives one58// connection: the remembered subscriptions and the packet identifier59// counter. out is the current connection's write queue, or nil while60// disconnected, and the mutex guards both it and the fields around it.61type Bus struct {62	clientID  string63	will      *busWill64	onConnect func(*Bus)65	handler   busHandler66	dial      func(context.Context) (net.Conn, error)6768	mutex    sync.Mutex69	filters  map[string]struct{}70	out      chan []byte71	packetID uint1672}7374// newBus builds a client that dials the address over TCP. The address,75// the client identifier, the will, the connect callback, and the76// inbound handler are fixed for the client's life; the connection they77// drive is not.78func newBus(address, clientID string, will *busWill, onConnect func(*Bus), handler busHandler) *Bus {79	bus := &Bus{80		clientID:  clientID,81		will:      will,82		onConnect: onConnect,83		handler:   handler,84		filters:   map[string]struct{}{},85	}86	bus.dial = func(ctx context.Context) (net.Conn, error) {87		dialer := &net.Dialer{}88		return dialer.DialContext(ctx, "tcp", address)89	}90	return bus91}9293// Run holds the connection open until ctx ends. It dials, connects,94// and serves one session, then waits a backoff and dials again. A95// session that reached a CONNACK resets the backoff to its floor, so a96// connection that drops after an hour reconnects at once, while a97// broker that never answers is retried ever more slowly.98func (b *Bus) Run(ctx context.Context) {99	backoff := busMinBackoff100	for ctx.Err() == nil {101		connected := b.runSession(ctx)102		if ctx.Err() != nil {103			return104		}105		if connected {106			backoff = busMinBackoff107		}108		select {109		case <-ctx.Done():110			return111		case <-time.After(backoff):112		}113		if !connected {114			backoff *= 2115			if backoff > busMaxBackoff {116				backoff = busMaxBackoff117			}118		}119	}120}121122// runSession dials, completes the CONNECT handshake, and serves the123// connection until its reader or writer fails. It returns whether the124// handshake reached a CONNACK, which is what tells Run to reset the125// backoff.126func (b *Bus) runSession(parent context.Context) (connected bool) {127	conn, err := b.dial(parent)128	if err != nil {129		return false130	}131	defer conn.Close()132133	if _, err := conn.Write(encodeConnect(b.clientID, busKeepalive, b.will)); err != nil {134		return false135	}136	reader := bufio.NewReader(conn)137	first, body, err := readPacket(reader)138	if err != nil || first&0xF0 != mqttConnack {139		return false140	}141	if err := parseConnack(body); err != nil {142		return false143	}144145	ctx, cancel := context.WithCancel(parent)146	defer cancel()147	// The reader blocks in Read until the broker writes or the148	// connection closes. Closing the connection when the session ends149	// is what unblocks a reader waiting on a silent broker.150	defer context.AfterFunc(ctx, func() { conn.Close() })()151152	out := make(chan []byte, busQueueDepth)153	b.mutex.Lock()154	b.out = out155	b.mutex.Unlock()156	defer func() {157		b.mutex.Lock()158		b.out = nil159		b.mutex.Unlock()160	}()161162	var writing sync.WaitGroup163	writing.Add(1)164	go func() {165		defer writing.Done()166		// A write failure ends the session, so the reader stops too.167		defer cancel()168		b.writeLoop(ctx, conn, out)169	}()170171	// The remembered subscriptions go out first, so the broker is172	// delivering again before onConnect re-publishes any retained173	// state.174	b.resubscribe(out)175	if b.onConnect != nil {176		b.onConnect(b)177	}178179	b.readLoop(reader)180	cancel()181	writing.Wait()182	return true183}184185// writeLoop is the one goroutine that writes the connection. It sends186// each queued frame and, when no frame has gone out for half the187// keepalive, sends a PINGREQ so the broker hears from the client188// before the keepalive elapses.189func (b *Bus) writeLoop(ctx context.Context, conn net.Conn, out <-chan []byte) {190	idle := time.Duration(busKeepalive) * time.Second / 2191	ticker := time.NewTicker(idle)192	defer ticker.Stop()193	last := time.Now()194	for {195		select {196		case <-ctx.Done():197			return198		case frame := <-out:199			if _, err := conn.Write(frame); err != nil {200				return201			}202			last = time.Now()203		case <-ticker.C:204			if time.Since(last) >= idle {205				if _, err := conn.Write(encodePingreq()); err != nil {206					return207				}208				last = time.Now()209			}210		}211	}212}213214// readLoop reads whole packets and delivers each inbound PUBLISH to the215// handler. A SUBACK and a PINGRESP are read and dropped: the client216// asks for QoS 0, so a SUBACK carries nothing to act on, and a217// PINGRESP only proves the broker is alive, which a successful read218// already shows. Any read error ends the loop and the session.219func (b *Bus) readLoop(reader *bufio.Reader) {220	for {221		first, body, err := readPacket(reader)222		if err != nil {223			return224		}225		if first&0xF0 == mqttPublish {226			topic, payload, ok := parsePublish(body)227			if ok && b.handler != nil {228				b.handler(topic, payload)229			}230		}231	}232}233234// Publish enqueues a QoS 0 PUBLISH from any goroutine. While the client235// is disconnected the queue does not exist and the publish is dropped,236// which is correct at QoS 0: a caller re-publishes its retained state237// from onConnect, so the broker holds the current value again within238// the reconnect.239func (b *Bus) Publish(topic string, payload []byte, retained bool) {240	b.mutex.Lock()241	out := b.out242	b.mutex.Unlock()243	if out == nil {244		return245	}246	select {247	case out <- encodePublish(topic, payload, retained):248	default:249	}250}251252// Subscribe remembers the filter and sends it if the client is253// connected. The remembered set is what runSession re-sends on every254// reconnect, so a subscription outlives the connection it was made on.255func (b *Bus) Subscribe(filter string) {256	b.mutex.Lock()257	b.filters[filter] = struct{}{}258	out := b.out259	frame := encodeSubscribe(b.nextPacketID(), filter)260	b.mutex.Unlock()261	if out == nil {262		return263	}264	select {265	case out <- frame:266	default:267	}268}269270// resubscribe sends every remembered filter on a fresh connection. The271// filters go out in sorted order so the frames a reconnect writes are272// the same every time, which keeps a test deterministic.273func (b *Bus) resubscribe(out chan<- []byte) {274	b.mutex.Lock()275	filters := make([]string, 0, len(b.filters))276	for filter := range b.filters {277		filters = append(filters, filter)278	}279	frames := make([][]byte, 0, len(filters))280	sort.Strings(filters)281	for _, filter := range filters {282		frames = append(frames, encodeSubscribe(b.nextPacketID(), filter))283	}284	b.mutex.Unlock()285	for _, frame := range frames {286		select {287		case out <- frame:288		default:289		}290	}291}292293// nextPacketID hands out the identifier a SUBSCRIBE carries and its294// SUBACK echoes. It skips zero, which the protocol reserves. The caller295// holds the mutex.296func (b *Bus) nextPacketID() uint16 {297	b.packetID++298	if b.packetID == 0 {299		b.packetID = 1300	}301	return b.packetID302}

1package main23// This file writes the manifest the design says nobody should have4// to write again: one claim that holds the whole player, request by5// request, with the parameter blocks a person wrote by hand in the6// days of the demo.78import (9	"encoding/json"10	"errors"11	"strconv"12	"strings"13)1415// The request names are the roles, and they are the names the16// container's resources.claims refer to. One claim with named17// requests beats one claim per device because the set allocates as a18// unit: the scheduler finds one machine that satisfies every request,19// or the pod parks Pending with one story to read.20//21// A remote's request is named for the Remote it claims, behind a22// prefix no player role starts with. The standing remote pod's claim23// uses the name, because that pod holds the controller now.24const (25	screenRequest       = "screen"26	renderRequest       = "render"27	audioRequestPrefix  = "audio"28	remoteRequestPrefix = "remote-"29)3031// remoteDisconnectedTaint is the taint the hardware operator sets when a32// controller disconnects. The standing remote reader pod tolerates it33// forever, because a controller sleeps whenever a person puts it down and34// the reader must wait for it. The playback claim tolerates no disconnect35// taint at all, so a display or a speaker that leaves evicts the playback36// pod, and the operator recreates it at the film's place.37const (38	remoteDisconnectedTaint = "bluetooth.liken.sh/disconnected"39)4041func remoteRequestName(remote string) string {42	return remoteRequestPrefix + remote43}4445// tolerateForever names the taint's effect, NoExecute, and has no46// tolerationSeconds. The effect must be stated: the device taint47// eviction controller applies a toleration only when the toleration's48// own effect is NoExecute, and a toleration with no effect tolerates49// the taint for scheduling alone, so the pod schedules and is evicted50// at once. The missing seconds are what keep a sleeping controller51// from evicting the pod later, because a controller sleeps whenever a52// person puts it down and the reader must wait for it.53func tolerateForever(taint string) []DeviceToleration {54	return []DeviceToleration{{55		Key:      taint,56		Operator: "Exists",57		Effect:   "NoExecute",58	}}59}6061// claimName is the Play's name plus its job, so a person reading62// either object finds the other.63func claimName(play string) string {64	return play + "-devices"65}6667// playOwner is the ownerReference that makes deleting the Play the68// whole teardown: the garbage collector deletes the claim and the pod69// the Play owns. The operator deletes a pod or a claim itself only to70// recreate a running Play's pod after its Player reshaped it.71func playOwner(play *Play) OwnerReference {72	return OwnerReference{73		APIVersion: mediaAPIVersion,74		Kind:       "Play",75		Name:       play.Metadata.Name,76		UID:        play.Metadata.UID,77		Controller: true,78	}79}8081// buildClaim turns one Player into one claim, requests in role order:82// screen, sinks, render. A Player without a display or without a render83// node yields a claim without that request, and the player program84// plays without one, which is what an audio-only unit is.85//86// The playback claim holds the player's own devices and no controller.87// A Remote reconciles into its own standing pod, which holds the88// controller's claim, so a controller on one machine and a display on89// another still pair.90func buildClaim(play *Play, player *Player) *ResourceClaim {91	claim := &ResourceClaim{92		APIVersion: claimAPIVersion,93		Kind:       "ResourceClaim",94		Metadata: ObjectMeta{95			Name:            claimName(play.Metadata.Name),96			Namespace:       play.Metadata.Namespace,97			OwnerReferences: []OwnerReference{playOwner(play)},98		},99	}100	if player.Spec.Display != nil {101		claim.add(screenRequest, *player.Spec.Display, nil)102	}103	for index, sink := range player.Spec.Sinks {104		claim.add(audioRequestPrefix+strconv.Itoa(index), sink, nil)105	}106	if player.Spec.Render != nil {107		// The render node takes no toleration, because a GPU does not108		// come and go while the machine runs.109		claim.add(renderRequest, *player.Spec.Render, nil)110	}111	return claim112}113114// add turns one device into a request and, when the Player states115// parameters for it, one opaque config block aimed at that request116// alone, so a codec never lands on a screen.117func (c *ResourceClaim) add(name string, device PlayerDevice, tolerations []DeviceToleration) {118	request := DeviceRequest{119		Name: name,120		Exactly: &ExactDeviceRequest{121			DeviceClassName: device.Class,122			// ExactCount with a count of one, because a role is one123			// piece of equipment.124			AllocationMode: "ExactCount",125			Count:          1,126		},127	}128	// An empty selector omits the list rather than sending an empty129	// expression, because a class that already names one kind of130	// device needs no CEL, and the API server refuses an expression131	// with nothing in it.132	if device.Selector != "" {133		request.Exactly.Selectors = []DeviceSelector{{CEL: &CELDeviceSelector{Expression: device.Selector}}}134	}135	request.Exactly.Tolerations = tolerations136	c.Spec.Devices.Requests = append(c.Spec.Devices.Requests, request)137138	if device.Parameters == nil {139		return140	}141	// The parameters travel as the Player wrote them. This operator142	// never reads a driver's vocabulary; the driver validates its143	// own block at the allocation.144	values := device.Parameters.Values145	if len(values) == 0 {146		values = json.RawMessage("{}")147	}148	c.Spec.Devices.Config = append(c.Spec.Devices.Config, DeviceClaimConfiguration{149		Requests: []string{name},150		Opaque: &OpaqueDeviceConfiguration{151			Driver:     device.Parameters.Driver,152			Parameters: values,153		},154	})155}156157// claimRequests lists the request names in claim order, which is what158// the container's resources.claims list repeats. The playback claim159// holds the player's roles alone, so every request is the player160// container's.161func claimRequests(claim *ResourceClaim) []string {162	names := make([]string, 0, len(claim.Spec.Devices.Requests))163	for _, request := range claim.Spec.Devices.Requests {164		names = append(names, request.Name)165	}166	return names167}168169// claimHasSink reports whether this claim requests a speaker. The170// claim carries one request per sink the Player states, and none for171// a Player that states no sink, so it is the speaker gate the pod172// builder reads without holding the Player.173func claimHasSink(claim *ResourceClaim) bool {174	for _, request := range claim.Spec.Devices.Requests {175		if strings.HasPrefix(request.Name, audioRequestPrefix) {176			return true177		}178	}179	return false180}181182// ensureClaim creates the playback claim when none exists and keeps an183// existing one. A 409 on the create is success, because another pass,184// or another copy of this operator, created the same claim first. The185// graceful recreate deletes a claim a Player reshaped before it calls186// this, so ensureClaim never updates a claim in place.187func ensureClaim(c *Client, claim *ResourceClaim) error {188	_, err := GetResourceClaim(c, claim.Metadata.Namespace, claim.Metadata.Name)189	if err == nil {190		return nil191	}192	if !errors.Is(err, ErrNotFound) {193		return err194	}195	if _, err := CreateResourceClaim(c, claim); err != nil && !errors.Is(err, ErrConflict) {196		return err197	}198	return nil199}200201// claimDiverged reports whether the claim the current Player produces202// differs from the one in the cluster. An absent claim counts as203// diverged, so the recreate creates it.204func (o *operator) claimDiverged(desired *ResourceClaim) (bool, error) {205	current, err := GetResourceClaim(o.client, desired.Metadata.Namespace, desired.Metadata.Name)206	if errors.Is(err, ErrNotFound) {207		return true, nil208	}209	if err != nil {210		return false, err211	}212	same, err := sameClaimSpec(current.Spec, desired.Spec)213	if err != nil {214		return false, err215	}216	return !same, nil217}218219// sameClaimSpec compares two claim specs by their marshaled form. It220// reads only the fields this operator's own types model, because the221// client drops every field it does not know when it reads the stored222// claim, so a field the API server adds does not read as a change.223func sameClaimSpec(current, desired ResourceClaimSpec) (bool, error) {224	was, err := json.Marshal(current)225	if err != nil {226		return false, err227	}228	wants, err := json.Marshal(desired)229	if err != nil {230		return false, err231	}232	return string(was) == string(wants), nil233}

1package main23// A controller declares every code it can report in its nodes'4// capability bitmaps, readable the moment a node opens and complete5// with no button pressed. The standing pod publishes that declared set6// retained, this desk folds it in, and the reconcile pass reports the7// gap, the declared controls the compiled table maps to nothing, on the8// Remote's status. The gap is derived on every pass and never9// accumulated, so erasing the status loses nothing.1011import (12	"slices"13	"sync"14)1516// remoteCodes is the document the standing pod publishes retained at17// every node open: the key codes and the hat axes its nodes declare.18// It carries numbers alone, because the names are the API and the19// numbers are the wire.20type remoteCodes struct {21	Keys []uint16 `json:"keys,omitempty"`22	Axes []uint16 `json:"axes,omitempty"`23}2425// codesDesk is the boundary between the codes topic and the reconcile26// loop, shaped like the report desk beside it: the bus thread folds27// messages in, and the pass reads one answer out.28type codesDesk struct {29	mutex    sync.Mutex30	declared map[string]remoteCodes31	online   map[string]bool32	wake     chan<- struct{}33}3435func newCodesDesk(wake chan<- struct{}) *codesDesk {36	return &codesDesk{37		declared: map[string]remoteCodes{},38		online:   map[string]bool{},39		wake:     wake,40	}41}4243// setCodes folds one controller's document in. A document that differs44// from the one held wakes the loop; a repeat, which every reconnect45// delivers, wakes nothing.46func (c *codesDesk) setCodes(key string, codes remoteCodes) {47	c.mutex.Lock()48	previous, had := c.declared[key]49	c.declared[key] = codes50	c.mutex.Unlock()51	if !had || !sameCodes(previous, codes) {52		poke(c.wake)53	}54}5556// clear drops one controller's document. The pod publishes the empty57// retained payload when its controller's nodes vanish, so the desk58// holds nothing for a controller that slept.59func (c *codesDesk) clear(key string) {60	c.mutex.Lock()61	_, had := c.declared[key]62	delete(c.declared, key)63	c.mutex.Unlock()64	if had {65		poke(c.wake)66	}67}6869// setAvailability records whether the standing pod that reports one70// controller is up, from the availability topic the pod names as its71// Last Will.72func (c *codesDesk) setAvailability(key string, online bool) {73	c.mutex.Lock()74	previous, had := c.online[key]75	c.online[key] = online76	c.mutex.Unlock()77	if !had || previous != online {78		poke(c.wake)79	}80}8182// codesFor returns what one controller declares, and whether the desk83// holds an answer. A controller whose pod is offline declares nothing,84// because a retained document outlives the pod that wrote it.85func (c *codesDesk) codesFor(key string) (remoteCodes, bool) {86	c.mutex.Lock()87	defer c.mutex.Unlock()88	codes, held := c.declared[key]89	if !held {90		return remoteCodes{}, false91	}92	if online, heard := c.online[key]; heard && !online {93		return remoteCodes{}, false94	}95	return codes, true96}9798// retain shrinks the desk to the Remotes the cluster still holds, so a99// long-running operator keeps no entry for a deleted Remote.100func (c *codesDesk) retain(live map[string]bool) {101	c.mutex.Lock()102	defer c.mutex.Unlock()103	for key := range c.declared {104		if !live[key] {105			delete(c.declared, key)106		}107	}108	for key := range c.online {109		if !live[key] {110			delete(c.online, key)111		}112	}113}114115func sameCodes(current, arriving remoteCodes) bool {116	return slices.Equal(current.Keys, arriving.Keys) &&117		slices.Equal(current.Axes, arriving.Axes)118}119120// The two words status.unbound uses for an entry's event type.121const (122	unboundKey  = "key"123	unboundAxis = "abs"124)125126// unboundCodes is the gap the status reports: every declared control127// the table maps to nothing. A key code passes as itself, so it is128// unbound only where a row drops it with none or the kernel gives it129// no name at all. A hat axis is unbound where no row of it names a130// key, which the base makes rare. The gap is by code, so a row on one131// direction of a hat binds the whole axis. It is derived on every132// pass, so it empties as the table grows.133func unboundCodes(declared remoteCodes, table []compiledBinding) []UnboundCode {134	dropped := map[uint16]bool{}135	named := map[uint16]bool{}136	for _, row := range table {137		switch row.EventType {138		case evKey:139			if row.Key == keyNone {140				dropped[row.Code] = true141			}142		case evAbs:143			if row.Key != keyNone {144				named[row.Code] = true145			}146		}147	}148	var unbound []UnboundCode149	for _, code := range declared.Keys {150		if !dropped[code] && keyCodeNames[code] != "" {151			continue152		}153		unbound = append(unbound, UnboundCode{154			Code: code, Name: keyCodeNames[code], Type: unboundKey})155	}156	for _, code := range declared.Axes {157		if named[code] {158			continue159		}160		unbound = append(unbound, UnboundCode{161			Code: code, Name: axisCodeNames[code], Type: unboundAxis})162	}163	return unbound164}

1package main23// The command sidecar is the playback pod's one owner of mpv's IPC4// socket, a native sidecar beside mpv. It subscribes to the Play's5// commands topic, writes each named command to mpv through the JSON IPC6// socket on the emptyDir the two containers share, and reads mpv's7// property changes back off the same socket to publish the status and8// availability. It holds no API credentials and reaches the control9// plane only through the operator's subscription to the bus.10//11// The sidecar reads two kinds of input. It reads the events topic of12// each controller the unit names, gated on the focus mark, and binds13// the kernel's key names itself in keybindings.go. And it reads the14// commands topic, which stays the surface any other program publishes15// to, so it answers a phone or a Home Assistant integration the same16// way it answers a gamepad. The report carries no API object: the Play17// it belongs to is named by the topic, not by the body.1819import (20	"context"21	"encoding/json"22	"fmt"23	"image"24	"math"25	"net"26	"os"27	"os/signal"28	"sync"29	"syscall"30	"time"31)3233// reportInterval is the ceiling on how often the command sidecar34// publishes a position while it advances. mpv sends a time-pos event35// several times a second, and one report is a small QoS 0 message, so36// the bus carries a live position at one report a second. The Play37// resource does not move that fast: the operator wakes its reconcile38// loop only on a pause or an item change, and a bare position advance39// waits for the backstop tick. So the bus is the live plane and the40// resource is the throttled one, and a consumer that wants a smooth41// position reads the bus.42var reportInterval = 1 * time.Second4344// busFlushGrace is how long the command sidecar holds the bus open45// after it publishes the two closing messages, so the writer goroutine46// drains them before the process exits. The messages are QoS 0 and47// carry no ack, so this window is the only signal the sidecar has that48// they left. The empty status is the one that needs the window: the49// Last Will publishes offline on an unclean exit, but nothing except50// this publish clears the retained report a finished Play would51// otherwise leave.52var busFlushGrace = 500 * time.Millisecond5354// commander holds the command sidecar's two sides: the connection to55// mpv that both the reporter and the command handler write, and the56// last-known report the connect callback re-publishes on a reconnect.57// Two goroutines write mpv's socket, so mpvMutex serializes them: a58// command and an observe request must not interleave their bytes. One59// goroutine reads the last report and another writes it, so reportMutex60// covers that pair.61type commander struct {62	statusTopic       string63	availabilityTopic string64	commandsTopic     string6566	// The unit's volume topic, empty for a Player with no sinks.67	// Empty is the speaker gate: the sidecar subscribes to no level,68	// applies none, and answers no volume press.69	volumeTopic string7071	// The unit's controllers, keyed by the events topic each one72	// publishes on, and the Player this Play runs on, which is the value73	// a mark must hold for a press to act. A pod for a Play whose Player74	// names no Remote holds none of this and answers no press.75	remotes    map[string]playRemote76	playerName string7778	// The last mark each controller's focus topic delivered, keyed by79	// that controller's events topic. It takes a lock of its own,80	// because a press reads it while the bus reader writes it.81	focusMu sync.Mutex82	marks   map[string]string8384	bus *Bus8586	// The items' presentation blocks in playlist order, baked into the87	// pod. Index i is item i's block text, which the sidecar forwards to88	// the display as the playlist reaches each item.89	presentations []json.RawMessage9091	mpvMutex sync.Mutex92	mpv      net.Conn9394	reportMutex sync.Mutex95	lastReport  playReport96	haveReport  bool9798	// The last state the volume topic delivered, and whether one99	// arrived at all. A press computes from this and never from what100	// mpv reports, which keeps a held button from becoming its own101	// echo. The bus reader writes it and a press reads it, so it102	// takes a lock of its own.103	volumeMutex sync.Mutex104	volume      volumeState105	haveVolume  bool106107	// volumeCaughtUp marks that this bus session has already108	// delivered a level. The first message of a session is the109	// broker's retained catch-up, a restore and not a press, so it110	// applies silently and the display draws no indicator at pod111	// start. Every message after it signals the display.112	volumeCaughtUp bool113114	// ended is set once any of the three endings has happened. It is held115	// rather than sent and forgotten, so every later report of this run116	// carries the mark too and a reconnect re-publishes it. It sits under117	// reportMutex because the ending arrives on the message goroutine or118	// on the run's own goroutine, and the reporter reads it on each send.119	ended bool120121	// Where the bridge writes decoded bgra. It is the shared art volume in the122	// pod, and a local directory under the harness.123	artDir string124125	// artItem is the item the shared art volume holds art for. artCache maps a126	// decoded size to its blob. Both sit under artMutex, because the reporter127	// goroutine swaps the item while the art goroutine reads and writes the128	// cache.129	artMutex sync.Mutex130	artItem  int131	artCache map[string]artBlob132133	// The one decoded sheet the bridge holds. A scrub within one sheet crops134	// every tile from this image, so it reads no new file.135	trickSheet    image.Image136	trickSheetKey string137138	// The last tile written for the current item. A request that maps to the139	// same tile replies with this blob and crops nothing, so the overlay does140	// not churn.141	trickHave bool142	trickItem int143	trickIdx  int144	trickBlob artBlob145146	// The prior tile file, kept one step longer than the current one. mpv places147	// a tile on a later turn than the reply that named it, so that file must148	// still exist when mpv maps it. The bridge removes a tile only once a second,149	// newer tile has replaced it.150	trickHavePrev bool151	trickPrev     artBlob152153	// The playlist as the bridge resolved it: the file names mpv reported,154	// and the art tier each item resolved to.155	playlistFiles []string156	tracks        []trackEntry157158	// The one album request the bridge holds, nil when it holds none. The159	// display asks for the cover as soon as it reads the item's block, and160	// mpv reports the playing item before it reports the playlist, so the161	// request can arrive in the moment between, when the bridge does not yet162	// know what the item's art is. A newer request replaces an older one,163	// because only the latest box is still on the screen.164	pendingAlbum *artRequest165}166167// runCommand connects to the bus, drives mpv's IPC socket, and reports168// the run. It returns when mpv's socket closes or the kubelet's grace169// signal arrives, and exits zero: the command sidecar is a native170// sidecar, and mpv's own exit code is the pod's outcome.171func runCommand() {172	namespace := os.Getenv(playNamespaceVariable)173	name := os.Getenv(playNameVariable)174	busAddress := os.Getenv(busAddressVariable)175	base := os.Getenv(topicBaseVariable)176	if base == "" {177		base = defaultTopicBase178	}179180	// The kernel runs no default action for a signal sent to PID 1, and181	// the command sidecar is its container's PID 1. The signal context182	// ends the report side on the kubelet's SIGTERM, which is the same183	// end mpv's closed socket gives.184	runCtx, stopRun := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)185	defer stopRun()186187	cmd := &commander{188		statusTopic:       playStatusTopic(base, namespace, name),189		availabilityTopic: playAvailabilityTopic(base, namespace, name),190		commandsTopic:     playCommandsTopic(base, namespace, name),191		volumeTopic:       os.Getenv(playerVolumeTopicVariable),192		presentations:     parsePresentations(os.Getenv(presentationsVariable)),193		artDir:            artMountPath,194		playerName:        os.Getenv(playerNameVariable),195		remotes: playRemoteMap(196			os.Getenv(remoteEventsTopicsVariable),197			os.Getenv(remoteFocusTopicsVariable)),198		marks: map[string]string{},199	}200201	// The bus runs on its own context, not the signal context, so the202	// two closing publishes still have a live connection to leave on203	// after the grace signal ends the report side.204	busCtx, stopBus := context.WithCancel(context.Background())205	cmd.bus = newBus(busAddress, "play-"+namespace+"-"+name,206		&busWill{Topic: cmd.availabilityTopic, Payload: []byte(availabilityOffline), Retained: true},207		cmd.onConnect, cmd.handle)208	// The subscription is made once. The Bus remembers the filter and209	// re-sends it on every reconnect, so a broker restart does not need210	// the command sidecar to subscribe again.211	cmd.bus.Subscribe(cmd.commandsTopic)212	// The volume topic is retained, so the broker delivers the213	// unit's current level on this subscribe and the level reaches214	// mpv with no request of its own. A Player with no sinks names no215	// topic, so this pod subscribes to no level at all.216	if cmd.volumeTopic != "" {217		cmd.bus.Subscribe(cmd.volumeTopic)218	}219	// The controllers' own topics, two per Remote the unit names.220	cmd.subscribeRemotes(cmd.bus)221	go cmd.bus.Run(busCtx)222223	cmd.report(runCtx)224225	// The run is over: mpv ended or the kubelet is terminating the pod.226	// report published the ending report first, so a subscriber that is227	// listening has already read the mark. Clear the retained status so a228	// finished Play leaves no report that reads as still playing, mark the229	// availability offline, and hold the bus open long enough to send both230	// before the connection ends.231	cmd.bus.Publish(cmd.statusTopic, nil, true)232	cmd.bus.Publish(cmd.availabilityTopic, []byte(availabilityOffline), true)233	time.Sleep(busFlushGrace)234	stopBus()235}236237// onConnect refills the broker the moment a session reaches a CONNACK.238// It publishes online, and re-publishes the last-known report, because239// the broker drops its retained set on a restart and a reconnect must240// leave the current status behind again.241func (c *commander) onConnect(bus *Bus) {242	// A fresh session redelivers the retained level, so that message243	// is a catch-up again and applies silently again.244	c.volumeMutex.Lock()245	c.volumeCaughtUp = false246	c.volumeMutex.Unlock()247	bus.Publish(c.availabilityTopic, []byte(availabilityOnline), true)248	c.reportMutex.Lock()249	payload, have := c.marshalLastReport()250	c.reportMutex.Unlock()251	if have {252		bus.Publish(c.statusTopic, payload, true)253	}254}255256// marshalLastReport encodes the last-known report, and reports whether257// there is one. The caller holds reportMutex, so the payload and the258// state it came from cannot diverge. A report that will not marshal is259// logged and treated as no report at all, because there is nothing to put260// on the bus in its place.261func (c *commander) marshalLastReport() ([]byte, bool) {262	if !c.haveReport {263		return nil, false264	}265	payload, err := json.Marshal(c.lastReport)266	if err != nil {267		fmt.Fprintf(os.Stderr, "command: report: %v\n", err)268		return nil, false269	}270	return payload, true271}272273// handle sorts one inbound message by its topic. The volume topic and274// the controllers' topics carry payloads that are not the command275// vocabulary, so each is read before it. A payload that does not276// decode, or an action this build has no command for, writes nothing,277// so a newer program's command degrades to no effect rather than a278// crash.279func (c *commander) handle(topic string, payload []byte) {280	if c.volumeTopic != "" && topic == c.volumeTopic {281		c.applyVolume(payload)282		return283	}284	if c.handleRemote(topic, payload) {285		return286	}287	var command mediaCommand288	if err := json.Unmarshal(payload, &command); err != nil {289		return290	}291	c.apply(command)292}293294// apply is the one path from a command to mpv, for a press this pod295// read off a controller and for a command another program published296// alike. A volume step and a mute leave without reaching mpv: they297// publish the unit's next state, and the subscription applies it, so298// the pod that pressed and every pod that only listened run one apply299// path. A seek and a chapter jump send a second command, because they300// carry no-osd and the sidecar summons the display to draw the new301// position.302func (c *commander) apply(command mediaCommand) {303	if isVolumeAction(command.Action) {304		c.pressVolume(command)305		return306	}307	mpv := commandFor(command)308	if mpv == nil {309		return310	}311	c.command(mpv)312	if feedback := feedbackFor(command); feedback != nil {313		c.command(feedback)314	}315}316317// applyVolume folds one message off the volume topic and writes it318// to mpv. It is the only place in the pod that sets the level, so a319// press made here and a press made on another screen of the same320// unit reach mpv the same way.321func (c *commander) applyVolume(payload []byte) {322	state, ok := parseVolumeState(payload)323	if !ok {324		return325	}326	c.volumeMutex.Lock()327	c.volume = state328	c.haveVolume = true329	signal := c.volumeCaughtUp330	c.volumeCaughtUp = true331	c.volumeMutex.Unlock()332	for _, command := range volumeCommands(state) {333		c.command(command)334	}335	if signal {336		c.command(volumeChangedCommand())337	}338}339340// pressVolume publishes what a press means, retained, and writes341// nothing to mpv. It computes from the last message the topic342// delivered, or from unity before any message arrives, so a pod343// that just started still steps from a definite level.344func (c *commander) pressVolume(command mediaCommand) {345	if c.volumeTopic == "" {346		return347	}348	payload, err := marshalVolumeState(nextVolume(c.heldVolume(), command))349	if err != nil {350		fmt.Fprintf(os.Stderr, "command: volume: %v\n", err)351		return352	}353	c.bus.Publish(c.volumeTopic, payload, true)354}355356// heldVolume is the state the last message left, and unity before357// any message arrives.358func (c *commander) heldVolume() volumeState {359	c.volumeMutex.Lock()360	defer c.volumeMutex.Unlock()361	if !c.haveVolume {362		return defaultVolumeState()363	}364	return c.volume365}366367// report is the reporting side of the run. It dials mpv, observes the368// four properties the status is made of, and turns each change into a369// report on the bus. It ends when mpv's socket closes, which is how mpv370// says the run is over, or when the context ends on the grace signal.371func (c *commander) report(ctx context.Context) {372	conn, err := dialMPV(ctx, mpvSocketPath)373	if err != nil {374		fmt.Fprintf(os.Stderr, "command: no reports for this run: %v\n", err)375		return376	}377	defer conn.Close()378	// The read blocks until mpv writes, which can be minutes apart in a379	// paused film, so closing the socket is what ends the read when the380	// context ends. A running mpv ends the read by closing its own end.381	defer context.AfterFunc(ctx, func() { conn.Close() })()382383	c.drive(ctx, conn, c.send)384385	// drive returns for one of two reasons, and each is an ending: mpv386	// reached the end of the last item and closed its socket, or the387	// kubelet's SIGTERM ended the context. So the mark goes out here, with388	// the position the last report carried, before runCommand clears the389	// retained status and marks the pod offline.390	c.endRun()391}392393// drive is the socket loop the reporter and the standalone art server share.394// It observes the properties, reads the events, folds each into a report395// through send, forwards the current item's block, and answers each logo396// request. The reporter passes its bus-backed send. The art server passes a397// send that reports nothing, so the same decode code runs with or without a398// bus.399func (c *commander) drive(ctx context.Context, conn net.Conn, send reportSender) {400	// observeProperties writes the socket, and so does the commands401	// handler, so the observe runs under the same mutex the handler402	// takes. The connection is set first, so a command that arrives403	// mid-observe waits on the mutex rather than reaching a nil socket.404	if err := c.attach(conn); err != nil {405		fmt.Fprintf(os.Stderr, "command: no reports for this run: %v\n", err)406		return407	}408	defer c.detach()409410	changes := make(chan propertyChange, 16)411	messages := make(chan clientMessage, 16)412	reading := make(chan struct{})413	go func() {414		defer close(reading)415		defer close(changes)416		defer close(messages)417		if err := readEvents(ctx, conn, changes, messages); err != nil && ctx.Err() == nil {418			fmt.Fprintf(os.Stderr, "command: mpv's socket: %v\n", err)419		}420	}()421422	// The message goroutine answers the display's exit press and its logo423	// requests off the same socket the reporter reads. It ends when the424	// socket closes and the reader closes the messages channel.425	go c.serveMessages(messages)426427	runReporter(ctx, changes, send, c.present, c.playlistChanged)428	<-reading429}430431// serveMessages answers the three things the display broadcasts: the exit432// press, its request for the current block, and each art request. It runs433// beside the reporter, so a slow decode or a network fetch never holds up the434// position reports.435func (c *commander) serveMessages(messages <-chan clientMessage) {436	for message := range messages {437		if isExitMessage(message.Args) {438			c.exit()439			continue440		}441		if isPresentationRequest(message.Args) {442			c.resendPresentation()443			continue444		}445		c.serveArt(message.Args)446	}447}448449// resendPresentation answers the display's request with the block for the450// item that is playing. It sends nothing before the first item, because the451// reporter presents that item as soon as mpv says which one plays, so a452// block is on its way already. It does not swap the art the way present453// does: the item has not changed, and the decoded art the volume holds is454// still the current item's own.455func (c *commander) resendPresentation() {456	c.artMutex.Lock()457	item := c.artItem458	c.artMutex.Unlock()459	if item < 1 {460		return461	}462	c.command(presentationCommand(c.blockForItem(item)))463}464465// attach sets the mpv connection and observes the properties under one466// lock, so the first writes to the socket cannot interleave with a467// command the handler sends the moment the connection is live.468func (c *commander) attach(conn net.Conn) error {469	c.mpvMutex.Lock()470	defer c.mpvMutex.Unlock()471	c.mpv = conn472	return observeProperties(conn, observedProperties)473}474475// detach forgets the connection when the run ends, so a late command476// writes nothing rather than a closed socket.477func (c *commander) detach() {478	c.mpvMutex.Lock()479	c.mpv = nil480	c.mpvMutex.Unlock()481}482483// command writes one mpv command under the mutex. A command that484// arrives before mpv is dialed, or after the run ends, finds a nil485// connection and writes nothing.486func (c *commander) command(command []any) {487	c.mpvMutex.Lock()488	defer c.mpvMutex.Unlock()489	if c.mpv == nil {490		return491	}492	if err := sendCommand(c.mpv, command); err != nil {493		fmt.Fprintf(os.Stderr, "command: mpv command: %v\n", err)494	}495}496497// parsePresentations reads the baked array into an indexed slice. An498// unset or malformed value leaves no blocks, so every item forwards the499// empty object and the display falls back to the file.500func parsePresentations(value string) []json.RawMessage {501	if value == "" {502		return nil503	}504	var blocks []json.RawMessage505	if err := json.Unmarshal([]byte(value), &blocks); err != nil {506		return nil507	}508	return blocks509}510511// present hands the current item's block to the display over the mpv512// socket.513//514// It clears the previous item's art first, so the shared volume holds only515// what the current item can show.516func (c *commander) present(item int) {517	c.swapArt(item)518	c.command(presentationCommand(c.blockForItem(item)))519}520521// swapArt drops the previous item's decoded art when the playlist reaches a522// new item, so one item's logo never lingers on the next and the shared volume523// holds only the current item's blobs.524func (c *commander) swapArt(item int) {525	c.artMutex.Lock()526	defer c.artMutex.Unlock()527	if item == c.artItem {528		return529	}530	for _, blob := range c.artCache {531		os.Remove(blob.path)532	}533	c.artCache = nil534	if c.trickHave {535		os.Remove(c.trickBlob.path)536	}537	if c.trickHavePrev && c.trickPrev.path != c.trickBlob.path {538		os.Remove(c.trickPrev.path)539	}540	c.trickHave = false541	c.trickHavePrev = false542	c.trickSheet = nil543	c.trickSheetKey = ""544	c.artItem = item545}546547// blockForItem returns one item's block, or the empty object when the548// item falls outside the baked list. The item counts from one, so its549// index is one less.550func (c *commander) blockForItem(item int) json.RawMessage {551	index := item - 1552	if index < 0 || index >= len(c.presentations) {553		return json.RawMessage(emptyPresentation)554	}555	return c.presentations[index]556}557558// send publishes one report to the status topic, retained, and holds it559// as the last-known report. A restarted operator reads the retained560// report back from the broker, and a reconnect re-publishes the held561// report through onConnect, so neither loses a running Play's place.562func (c *commander) send(report playReport) error {563	c.reportMutex.Lock()564	// The reporter folds mpv's property changes alone and carries no565	// ending, so the mark is stamped here. Every report after the ending566	// carries it, and a subscriber that reads any one of them reads the567	// same ending.568	if c.ended {569		report.Ended = true570	}571	payload, err := json.Marshal(report)572	if err == nil {573		c.lastReport = report574		c.haveReport = true575	}576	c.reportMutex.Unlock()577	if err != nil {578		return err579	}580	c.bus.Publish(c.statusTopic, payload, true)581	return nil582}583584// endRun marks the run over and publishes the mark at once, retained,585// beside the numbers the last report carried. Every ending calls it: the586// exit press, mpv reaching the end of the last item, and the kubelet's587// SIGTERM.588//589// The operator turns the mark into the Player's idle status and the590// re-present that draws the idle screen again. The pod takes seconds to591// terminate, and an ending read from the pod's own death would leave a592// dead film on the screen for every one of them.593//594// A run that never reported publishes nothing, the same rule the reporter595// follows: mpv has not said which item plays, so there are no numbers to596// carry, and the pod's own death is what ends such a run. The art server597// runs this same code with no bus, and it publishes nothing either.598func (c *commander) endRun() {599	if c.bus == nil {600		return601	}602	c.reportMutex.Lock()603	c.ended = true604	c.lastReport.Ended = true605	payload, have := c.marshalLastReport()606	c.reportMutex.Unlock()607	if !have {608		return609	}610	c.bus.Publish(c.statusTopic, payload, true)611}612613// exit ends the run at a person's press. The display broadcasts the exit614// message when a person presses back at the bare video, and the sidecar615// answers it here rather than letting the display quit mpv itself,616// because the order is the whole point: the ending reaches the bus617// first, and only then does quit reach mpv. So the operator holds the618// mark while the film is still on the display, and how far mpv gets619// through its shutdown before its socket closes changes nothing.620//621// The exit code is zero, so the pod ends Completed, the outcome a film622// that ran to its end gives, and not Error.623func (c *commander) exit() {624	c.endRun()625	c.command(exitCommand())626}627628// playbackState is the run at one moment, as the command sidecar holds629// it. The fields are the report's fields, held between events, because630// each event carries one property and a report carries all of them.631type playbackState struct {632	paused   bool633	item     int634	position string635	duration string636637	// The language of the audio track and the subtitle track mpv chose. Each stays638	// set once mpv reports it.639	audioLanguage    string640	subtitleLanguage string641}642643// reportable holds reports back until mpv has said which item plays.644// mpv's playlist-pos counts from zero and reads -1 before anything645// loads; the API counts from one, the way a person counts tracks, so an646// item below one describes no playback at all.647func (s playbackState) reportable() bool {648	return s.item >= 1649}650651func (s playbackState) report() playReport {652	return playReport{653		Paused:           s.paused,654		Item:             s.item,655		Position:         s.position,656		Duration:         s.duration,657		AudioLanguage:    s.audioLanguage,658		SubtitleLanguage: s.subtitleLanguage,659	}660}661662// apply folds one property change into the state, and its return value663// says whether the change earns a report at once. A pause and an item664// change are the two things a person watching kubectl is waiting to665// see, and both are rare. A position that advances is neither rare nor666// surprising, so it waits for the interval.667func (s *playbackState) apply(change propertyChange) bool {668	if !change.known() {669		return false670	}671	switch change.Name {672	case "pause":673		var paused bool674		if err := json.Unmarshal(change.Data, &paused); err != nil {675			return false676		}677		changed := paused != s.paused678		s.paused = paused679		return changed680	case "playlist-pos":681		var position int682		if err := json.Unmarshal(change.Data, &position); err != nil || position < 0 {683			return false684		}685		item := position + 1686		changed := item != s.item687		s.item = item688		return changed689	case "time-pos":690		var seconds float64691		if err := json.Unmarshal(change.Data, &seconds); err != nil {692			return false693		}694		s.position = formatPosition(seconds)695		return false696	case "duration":697		var seconds float64698		if err := json.Unmarshal(change.Data, &seconds); err != nil {699			return false700		}701		s.duration = formatPosition(seconds)702		return false703	case audioLanguageProperty:704		var lang string705		if err := json.Unmarshal(change.Data, &lang); err != nil {706			return false707		}708		changed := lang != s.audioLanguage709		s.audioLanguage = lang710		return changed711	case subtitleLanguageProperty:712		var lang string713		if err := json.Unmarshal(change.Data, &lang); err != nil {714			return false715		}716		changed := lang != s.subtitleLanguage717		s.subtitleLanguage = lang718		return changed719	}720	return false721}722723// formatPosition writes seconds as H:MM:SS, because the value's one job724// is to be read in kubectl get output. The seconds are floored, not725// rounded: a position that reads 0:00:01 while the first second still726// plays is wrong in the direction a person notices.727func formatPosition(seconds float64) string {728	if math.IsNaN(seconds) || math.IsInf(seconds, 0) || seconds < 0 {729		seconds = 0730	}731	whole := int(math.Floor(seconds))732	return fmt.Sprintf("%d:%02d:%02d", whole/3600, whole%3600/60, whole%60)733}734735// reportSender is how a report leaves the command sidecar. The loop736// takes a function rather than the bus so a test catches the reports737// with no broker at all.738type reportSender func(playReport) error739740// itemPresenter is how a forwarded block leaves the loop, a function741// like reportSender, so a test catches the forward with no mpv socket.742type itemPresenter func(item int)743744// playlistReceiver is how mpv's playlist leaves the loop, a function like745// itemPresenter. The playlist takes its own path out because it settles each746// item's album art, and no field of the report carries it.747type playlistReceiver func(playlist json.RawMessage)748749// runReporter is the whole reporting rule in one loop: fold the change,750// send it now when it is one of the two that matter, and otherwise send751// no more than one report per interval. A send that fails is logged and752// the run goes on, because the loss is the operator's view of the film753// and not a reason to stop playing.754func runReporter(ctx context.Context, changes <-chan propertyChange, send reportSender, present itemPresenter, playlist playlistReceiver) {755	var state playbackState756	var sent time.Time757	var presented int758	for {759		select {760		case <-ctx.Done():761			return762		case change, open := <-changes:763			if !open {764				return765			}766			// The playlist is the art, not the report, so it leaves here767			// and folds into no playbackState field. It arrives before mpv768			// says which item plays, because observe answers every property769			// with its current value at subscribe time.770			if change.Name == playlistProperty {771				if change.known() {772					playlist(change.Data)773				}774				continue775			}776			atOnce := state.apply(change)777			if !state.reportable() {778				continue779			}780			// Forward the block on the first item and on every advance,781			// keyed on the item and not the throttled position, so the782			// display swaps its presentation the moment the playlist783			// reaches a new item.784			if state.item != presented {785				presented = state.item786				present(state.item)787			}788			if !atOnce && time.Since(sent) < reportInterval {789				continue790			}791			sent = time.Now()792			if err := send(state.report()); err != nil {793				fmt.Fprintf(os.Stderr, "command: report: %v\n", err)794			}795		}796	}797}

1package main23// The command sidecar's controller half. The events topic carries key4// names, so nothing stands between a controller and the pod that owns5// mpv's socket, and one container holds every controller the unit6// names. The focus mark is still the gate: it names a Player and never7// a Play, and a controller pointed at another room reaches this film8// not at all.910import "encoding/json"1112// A playRemote is one of the unit's controllers as this sidecar reads13// it: the retained focus topic it gates on. The events topic is the14// map's key, because that is what an inbound message carries.15type playRemote struct {16	focus string17}1819// playRemoteMap pairs each remote's events topic with the focus topic20// on the same line of the second list. The operator joins both lists21// with newlines and keeps them aligned by position, the same shape the22// idle screen client reads.23func playRemoteMap(events, focuses string) map[string]playRemote {24	remotes := map[string]playRemote{}25	focusList := splitTopicLines(focuses)26	for index, topic := range splitTopicLines(events) {27		if topic == "" {28			continue29		}30		remote := playRemote{}31		if index < len(focusList) {32			remote.focus = focusList[index]33		}34		remotes[topic] = remote35	}36	return remotes37}3839// subscribeRemotes makes the two subscriptions each controller needs.40// Both are made once, because the Bus re-sends every filter on a41// reconnect. The focus topic is retained, so the gate stands before42// the first press.43func (c *commander) subscribeRemotes(bus *Bus) {44	for events, remote := range c.remotes {45		bus.Subscribe(events)46		if remote.focus != "" {47			bus.Subscribe(remote.focus)48		}49	}50}5152// handleRemote answers the topics the controllers own and reports53// whether this message was one of them, so the caller reads the54// commands topic only for a message no controller sent.55func (c *commander) handleRemote(topic string, payload []byte) bool {56	if remote, ours := c.remotes[topic]; ours {57		c.key(topic, remote, payload)58		return true59	}60	if events, ours := c.remoteForFocus(topic); ours {61		c.setFocus(events, string(payload))62		return true63	}64	return false65}6667// key turns one key event into what this pod does with it. A press68// this Play's Player does not hold the mark for does nothing. A key69// with no row does nothing. The cycle key asks the operator to move70// the mark and never reaches mpv.71func (c *commander) key(topic string, remote playRemote, payload []byte) {72	var event keyEvent73	if err := json.Unmarshal(payload, &event); err != nil {74		return75	}76	if !c.holdsFocus(topic) {77		return78	}79	command, bound := commandForKey(event)80	if !bound {81		return82	}83	if command.Action == actionCycleFocus {84		c.publishCycle(remote)85		return86	}87	c.apply(command)88}8990// focusCycleSuffix turns a remote's focus topic into its cycle topic, the91// same path remoteFocusCycleTopic builds, so the sidecar needs no second92// topic list.93const focusCycleSuffix = "/cycle"9495// publishCycle sends the cycle request the operator arbitrates, on96// the remote's own cycle topic, not retained, because a cycle is an97// event and not a state. It is the same message the idle screen client98// publishes between films.99func (c *commander) publishCycle(remote playRemote) {100	if remote.focus == "" {101		return102	}103	c.bus.Publish(remote.focus+focusCycleSuffix, nil, false)104}105106// setFocus records one controller's mark. The gate is set on every107// message, catch-up and live alike, because this pod draws nothing on108// a mark and only reads it.109func (c *commander) setFocus(events, mark string) {110	c.focusMu.Lock()111	defer c.focusMu.Unlock()112	if c.marks == nil {113		c.marks = map[string]string{}114	}115	c.marks[events] = mark116}117118// holdsFocus reports whether this controller's mark names the Player119// this Play runs on. A sidecar that read no Player name matches no120// mark and answers no press.121func (c *commander) holdsFocus(events string) bool {122	c.focusMu.Lock()123	defer c.focusMu.Unlock()124	return c.playerName != "" && c.marks[events] == c.playerName125}126127// remoteForFocus reports which controller a focus topic marks. The128// list is the unit's own controllers, so the scan is over a handful.129func (c *commander) remoteForFocus(topic string) (string, bool) {130	if topic == "" {131		return "", false132	}133	for events, remote := range c.remotes {134		if remote.focus == topic {135			return events, true136		}137	}138	return "", false139}

1package main23// Discovery is the reader's teaching mode. This file renders what one4// event reports: the node it came from, the event type, the code by5// its evdev name, the value as a press, a release, or a repeat, and6// the Keymap entry that would bind it, ready to paste. Where no entry7// can bind it, the line states why instead.89import "fmt"1011// The placeholder the pasted fragment carries on its right side. A12// Keymap row names the kernel key the control should report, or none13// to drop it, and most controls need no row at all.14const keymapKeyHint = "<a KEY_* name, or none>"1516// discoveryLines renders one event: the fields on the first line, and17// under them the Keymap entry that binds it, indented to paste under18// spec.buttons or spec.axes.19func discoveryLines(node string, event inputEvent) []string {20	switch event.Type {21	case evKey:22		return keyLines(node, event)23	case evAbs:24		return axisLines(node, event)25	}26	return nil27}2829// keyLines names a key event's code and value. Only the press earns a30// fragment, because a Keymap binds the press alone; the release and31// the repeat lines state that instead, so a stream of value 2 does not32// read as a bug.33func keyLines(node string, event inputEvent) []string {34	name := keyCodeNames[event.Code]35	line := fmt.Sprintf("%s %s %s %s", node, eventTypeField(event.Type),36		codeField(name, event.Code), keyValueField(event.Value))37	switch {38	case name == "":39		return []string{line + ": the kernel gives this code no name, so a Keymap cannot bind it"}40	case event.Value != 1:41		return []string{line + ": a Keymap binds the press alone"}42	}43	return []string{44		line,45		fmt.Sprintf("  - press: %s   # code %d", name, event.Code),46		"    key: " + keymapKeyHint,47	}48}4950// axisLines names a hat event's code and direction. The two directions51// earn a fragment; the return to the middle does not, because a Keymap52// binds -1 and 1 and treats 0 as the release.53func axisLines(node string, event inputEvent) []string {54	name := axisCodeNames[event.Code]55	line := fmt.Sprintf("%s %s %s %d", node, eventTypeField(event.Type),56		codeField(name, event.Code), event.Value)57	switch {58	case name == "":59		return []string{line + ": a Keymap binds the two hat axes alone"}60	case event.Value == 0:61		return []string{line + ": a Keymap binds -1 and 1, not the return to the middle"}62	}63	return []string{64		line,65		fmt.Sprintf("  - axis: %s   # code %d", name, event.Code),66		fmt.Sprintf("    value: %d", event.Value),67		"    key: " + keymapKeyHint,68	}69}7071// eventTypeField gives the type by the kernel's own name, with the72// number beside it.73func eventTypeField(eventType uint16) string {74	name := "EV_KEY"75	if eventType == evAbs {76		name = "EV_ABS"77	}78	return fmt.Sprintf("%s (%d)", name, eventType)79}8081// codeField gives the code by name and number, or the number alone82// when the kernel gives the code no name.83func codeField(name string, code uint16) string {84	if name == "" {85		return fmt.Sprintf("%d", code)86	}87	return fmt.Sprintf("%s (%d)", name, code)88}8990// keyValueField names a key's three values for what a person did.91func keyValueField(value int32) string {92	switch value {93	case 0:94		return "release (0)"95	case 1:96		return "press (1)"97	case 2:98		return "repeat (2)"99	}100	return fmt.Sprintf("(%d)", value)101}

1package edl23// An album folder becomes a timeline. Two callers write one: the player4// shim in the playback pod, because only the pod mounts the media, and the5// local/edl tool on a workstation. Both call this code, so what a person6// sees locally is what a Play runs.78import (9	"cmp"10	"io/fs"11	"os"12	"path/filepath"13	"regexp"14	"slices"15	"strings"1617	"github.com/dhowden/tag"18)1920// The file names an album is made of, matched without case because a library21// writes either. mpv decodes all six, and dhowden/tag reads only the MP3, M4A,22// FLAC, OGG, and DSF families, so a wma or wav track takes its title from its23// file name and its cover from the folder it sits in.24var AudioExtensions = []string{".mp3", ".flac", ".m4a", ".ogg", ".wma", ".wav"}2526// The track number a library writes in front of a file name, which the27// title fallback strips: digits, then a dash, a dot, or an underscore, with28// whatever spacing surrounds the mark.29var trackPrefix = regexp.MustCompile(`^\d+\s*[-._]\s*`)3031// Facts are the album's words as its own files state them, for a caller32// that builds a presentation block from a folder.33//34// The year is a number, because the presentation block's year is a number.35// A file that states none reads as zero.36type Facts struct {37	Artist string38	Album  string39	Year   int40}4142// AlbumFiles is the album in the order it plays. The file names carry the43// track order, so name order is play order and no tag is read to settle it.44//45// The walk descends, because a multi-disc album is a folder of folders, and46// the whole relative path settles the order, so CD1 comes before CD2 and47// each disc keeps its own track order. A hidden entry is skipped, because48// macOS and sync tools write dot-named companions beside the real files.49func AlbumFiles(dir string) ([]string, error) {50	absolute, err := filepath.Abs(dir)51	if err != nil {52		return nil, err53	}5455	var relatives []string56	walk := func(path string, entry fs.DirEntry, err error) error {57		if err != nil {58			return err59		}60		if path != absolute && strings.HasPrefix(entry.Name(), ".") {61			if entry.IsDir() {62				return fs.SkipDir63			}64			return nil65		}66		if entry.IsDir() || !IsAudio(entry.Name()) {67			return nil68		}69		relative, err := filepath.Rel(absolute, path)70		if err != nil {71			return err72		}73		relatives = append(relatives, relative)74		return nil75	}76	if err := filepath.WalkDir(absolute, walk); err != nil {77		return nil, err78	}7980	slices.SortFunc(relatives, compareNatural)81	files := make([]string, len(relatives))82	for index, relative := range relatives {83		files[index] = filepath.Join(absolute, relative)84	}85	return files, nil86}8788// The order is natural, not the byte order the file system gives: a person89// writes track 2 and track 10 without padding, and the byte order plays 1090// before 2. The comparison reads both names in step, a run of digits as the91// number it spells and any other run as its bytes.92func compareNatural(a, b string) int {93	for len(a) > 0 && len(b) > 0 {94		digits := isDigit(a[0])95		if digits != isDigit(b[0]) {96			return cmp.Compare(a[0], b[0])97		}98		var left, right string99		if digits {100			left, a = runOf(a, isDigit)101			right, b = runOf(b, isDigit)102			if order := compareNumbers(left, right); order != 0 {103				return order104			}105			continue106		}107		left, a = runOf(a, func(c byte) bool { return !isDigit(c) })108		right, b = runOf(b, func(c byte) bool { return !isDigit(c) })109		if order := strings.Compare(left, right); order != 0 {110			return order111		}112	}113	return cmp.Compare(len(a), len(b))114}115116// Two digit runs compare as the numbers they spell, and the written length117// breaks a value tie, so a padded name and a bare one hold one order.118func compareNumbers(a, b string) int {119	left, right := strings.TrimLeft(a, "0"), strings.TrimLeft(b, "0")120	if len(left) != len(right) {121		return cmp.Compare(len(left), len(right))122	}123	if order := strings.Compare(left, right); order != 0 {124		return order125	}126	return cmp.Compare(len(a), len(b))127}128129// runOf reads the leading run of bytes the test accepts, and returns it with130// what is left of the name.131func runOf(name string, accepts func(byte) bool) (run, rest string) {132	end := 0133	for end < len(name) && accepts(name[end]) {134		end++135	}136	return name[:end], name[end:]137}138139func isDigit(c byte) bool {140	return c >= '0' && c <= '9'141}142143// IsAudio says whether one file name is an album track.144func IsAudio(name string) bool {145	extension := strings.ToLower(filepath.Ext(name))146	return slices.Contains(AudioExtensions, extension)147}148149// Timeline writes the whole EDL: the header, then one segment per track.150// Each segment names the file and the title mpv turns into that track's151// chapter.152func Timeline(files []string) string {153	var text strings.Builder154	text.WriteString(Header + "\n")155	for _, file := range files {156		text.WriteString(Quote(file) + ",title=" + Quote(TitleOf(file)) + "\n")157	}158	return text.String()159}160161// TitleOf is the track's name: the tag first, then the file name with its162// extension and its track number removed. A ripped library names each file163// for its track, so the file name is a sound fallback.164func TitleOf(file string) string {165	if title := taggedTitle(file); title != "" {166		return flatten(title)167	}168	name := strings.TrimSuffix(filepath.Base(file), filepath.Ext(file))169	return flatten(trackPrefix.ReplaceAllString(name, ""))170}171172// A timeline is a line per segment, so a title that holds a newline would173// end the segment early and the rest of the title would read as another174// one. Every control byte becomes a space, and a run of them becomes one175// space.176func flatten(title string) string {177	var text strings.Builder178	spaced := false179	for index := 0; index < len(title); index++ {180		if c := title[index]; c >= 0x20 && c != 0x7f {181			text.WriteByte(c)182			spaced = false183			continue184		}185		if !spaced {186			text.WriteByte(' ')187			spaced = true188		}189	}190	return strings.TrimSpace(text.String())191}192193// taggedTitle reads one file's title tag, and reads nothing from a file with194// no tags.195func taggedTitle(file string) string {196	metadata := readTags(file)197	if metadata == nil {198		return ""199	}200	return strings.TrimSpace(metadata.Title())201}202203// AlbumFacts is the album's words as its own files state them. The album's204// fields are the same on every track, so the first tagged file states them205// for the whole album.206func AlbumFacts(files []string) Facts {207	for _, file := range files {208		metadata := readTags(file)209		if metadata == nil {210			continue211		}212		return Facts{213			Artist: strings.TrimSpace(metadata.Artist()),214			Album:  strings.TrimSpace(metadata.Album()),215			Year:   max(0, metadata.Year()),216		}217	}218	return Facts{}219}220221// readTags reads one file's tags, and reads nothing from a file it cannot open222// or that carries none.223func readTags(path string) tag.Metadata {224	file, err := os.Open(path)225	if err != nil {226		return nil227	}228	defer file.Close()229	metadata, err := tag.ReadFrom(file)230	if err != nil {231		return nil232	}233	return metadata234}