Movie Night · engineering notes

A TV catalogue that still works when the microphone does not

I wanted a home film and TV library that was pleasant to use from the sofa. That turned out to be several problems at once: a screen three metres away, a remote with five buttons, file names nobody agrees on, and outside services that fail quietly. Voice seemed like the answer, until I noticed that a voice-first app makes the microphone, the speech service and the network all requirements. So I built the catalogue to work without any of them, and added voice as a second way in. These are the notes on how it fits together and the mistakes that shaped it.

The short version
205commits from 25 August to 15 November 2026
70Python modules in the app
1,412checks in the suite, by the project's own record
31words the offline grid recogniser listens for
6 severy streamed segment, exactly as the playlist says
89%of one Discover run spent in the language model, before the order changed

01Why I built it

A home media library is easy to fill and awkward to use. On a desk, a file browser is fine. From the sofa it is a wall of small text, and a television remote cannot drive it at all: it sends four arrows and OK, with no pointer and no Tab key.

The obvious fix is a voice assistant, and I started there. But a voice-first design quietly turns every link in the chain into a requirement. If the microphone is unplugged, the speech service is busy or the network drops, the person on the sofa is left looking at a screen that cannot be driven. I wanted the opposite: a catalogue that works with a mouse or a remote alone, where voice is a faster way to do things that can always be done another way.

One question settled most of the design calls that followed: can someone on the sofa do this with one hand, in one second, without knowing anything? It sounds soft, but it is a useful test. It rules out a search box on a device with no keyboard, a control the arrows cannot reach, and a setting that only exists in a config file.

02Architecture at a glance

Movie Night is a Python application whose screen is a single web page. A small local server serves the page into a kiosk window on the television and, when asked, to phones and tablets on the home network. Speech-to-text and the language model come from a gateway on my small fleet of machines, over plain HTTP; nothing else is shared with any other project.

It began life inside a larger project that runs that fleet, purely so the television box could pick it up from the same update. That convenience had a cost, so it was split into its own repository with its history intact. It has its own environment, requirements, tests and documents, and the one tie left is deliberate: the fleet's updater, which makes every box run the committed code and proves that it does.

Catalogue state machineOne class that holds the library and the filters and applies every command. It contains no Qt, no microphone and no browser.
Page and serverA renderer over the state. It polls, draws and posts commands back, and never navigates away from itself.
Library indexGroups files into films, shows and seasons, with the folder as the authority. Written atomically, backed up daily.
MetadataOMDb for ratings and posters, TMDb for episodes and seasons, and a key ledger that knows a dead key from a spent one.
Voice and the click gridPush-to-talk speech through the gateway, plus an offline recogniser for the grid's small vocabulary.
Player controlVLC driven through its own HTTP interface, for exact seeking and a real resume position.
DiscoverSuggestions for films not yet owned, every one verified on OMDb before it is shown.
Meaning profilesA local database of tags, meaning vectors, community knowledge and subtitle lines, built on each box.
Home-network streamingHLS produced on demand, one session per viewer over one shared library, admitted by address.

The shape comes from one rule: pure logic in the middle, thin edges outside. The microphone, hotkeys, Qt and process launches are imported lazily and fail softly, so every module imports on any machine and every side effect degrades rather than crashes. That is also what lets the catalogue start on a box with no audio libraries installed at all.

03One brain, three ways in

The first version kept its state inside the voice assistant. That meant the catalogue could only exist while a microphone did, which was exactly backwards. So I moved everything a command can do into one state machine. A click on a poster, OK on a remote and a spoken request all become the same small command object, and one method applies it. Everything that touches the outside world, playing a file or saving the library, is passed in, so the whole machine can be tested with plain data.

The page is only a renderer. It polls the state, draws it and posts commands back. Because there is one implementation, voice and mouse cannot disagree about what 'play the first one' means, and every new command is automatically available to both.

Two smaller rules came from running it in kiosk mode. The page must never navigate away from itself, because there is no tab strip to come back from: anything external is opened by the server in an ordinary browser. And the grid of posters is never rebuilt wholesale. Cards are reused between polls and redrawn only when what they show changes. I measured the server answering a poll in under two milliseconds, so the browser was where the time went, and that is where the work belonged.

Everything sayable is clickable, and everything clickable is sayable. Audited against the action list, not from memory. A phrase that misfires into a library search is worse than one the app does not know, because it looks like the feature is broken.

04A remote has five buttons

Making the page reachable with four arrows and OK took longer than I expected. The first measurement found the arrows reaching the poster grid and very little else: the filter chips, the header, the settings and the 'watch here' button were all out of reach from the sofa.

The fix that lasted was spatial navigation. Pressing an arrow moves focus to the nearest control in that direction, using the geometry on screen. An earlier version used a list of control classes, and every control added after the list was written was invisible to the remote. A dialog is treated as a screen of its own, focus never wanders onto the library hidden behind it, and the focus ring is loud, because a control that is focused but not visibly focused is unusable at three metres.

To keep it honest I wrote a prober that walks the page breadth-first at 1920 by 1080, pressing the arrows from every control it reaches. It now reaches every control in the library and in Discover, in both the desk and the TV layout. It exits with a failure when there was nothing to walk, because once it printed 'every control is reachable' about a panel it had never opened.

Reachable is not the same as readable. A TV mode enlarges everything by multiplying the zoom and card-size settings rather than replacing them, so somebody's deliberate choice survives. Colour carries meaning too: one colour per kind of action, the same everywhere it appears, so the green row can be found without reading it.

05Voice that does not wait on the network

Most spoken requests go to the speech service on the fleet, which takes about a second. That is fine for 'play the next episode'. It is not fine for clicking a point on the screen, which takes several commands in a row.

For that I adapted the keyboard-navigation idea of a narrowing grid. Saying 'grid' draws a 3 by 3 numbered overlay over the whole screen. Saying a number zooms into that cell and redraws, and 'click' clicks the centre. It works on anything on screen, a browser link or a button in the player, with no knowledge of the page underneath. Because the vocabulary is closed, 31 words in all, a small offline recogniser handles it while the grid is up. Nothing leaves the box, and each number lands in milliseconds. If the recogniser is not installed, the grid falls back to push-to-talk.

Titles are the hard part of speech. Speech-to-text mangles names, and a cloud lookup for every miss is slow. So a spoken title is matched against the library locally first, in a way that tolerates near misses. Only when that fails does the language model get a chance to correct it. When it does, the correction is saved, so the same mis-hearing resolves offline the next time and the box slowly gets better at this household's voices.

The player is VLC, driven through its own HTTP interface rather than simulated keystrokes. 'Skip to forty minutes' lands exactly, and resume uses the position the player reports, not a stopwatch. Resume and Start over are two buttons with the time printed on them, never one that guesses.

06Making sense of a folder of files

File names are where the mess lives. A season folder may hold files with a season marker and no episode number. Some files start with an absolute episode counter that looks like a show name. A show and a film can share a name. I tried several clever file-name rules before accepting that the folder already knew: a folder whose own name carries a season makes a season, and a folder of those makes one show. A flat folder of mixed downloads is left alone, because a looser rule would sweep it into one invented series.

The lesson that cost the most here was that a correct parser fix can change nothing. The refresh compares a folder signature, so an index whose files have not moved is never re-derived. The fix shipped, the box re-indexed, and the numbers came back identical. Data derived by code now carries a version stamp, and the reader re-derives when the stamp is old. The same applies to metadata lookups, because a wrong answer is cached just as firmly as a right one.

When the same episode is owned twice, the app shows one row and plays the better copy. Ranking by file size is the obvious rule and the wrong one: a smaller file in a newer codec can be the better picture. It ranks on what the release states, resolution then source, and compares sizes only within one codec. The other copy stays one menu away, because a choice that cannot be overridden is one nobody trusts.

Files move between drives, and an index keyed by path would lose their watch history. A file that vanishes and reappears with the same name and size keeps its record, but only when that match is unique, because a guess hands one title another's history.

07Finding something you do not own

Discover suggests films and shows that are not in the library, each with the reason it surfaced. The first version asked the language model for ideas and waited. I timed one run: the model took 89 per cent of it, while TMDb answered genre, year and rating queries exactly and in a fraction of the time. So the exact sources now run first and render on their own, and the model is asked only when they come up short or the request carries a feeling no filter can express.

OMDb cannot browse or suggest, but it is an excellent verifier. Every candidate, from any source, is checked there before it can reach the screen. A proposer is allowed to invent a title; verification is what makes that safe.

The 'hidden gems' and 'deep cuts' bands are ranges of vote counts, and I had assumed one ratio between the two sites that count them. Measured, IMDb's count runs a median of 18 times TMDb's for films and 63 times for TV, and the gap changes again by language. The first bands also overlapped, so 'deep cuts' repeated most of the gems. They now tile, both skip the current year's releases, which have few votes because they are new rather than obscure, and every cached result carries a fingerprint of the rules that chose it.

Discover also takes a plain sentence. A word table turns what it recognises into filters at once. The model may fill only the gaps the sentence hints at, because when it was allowed more it added decades, a rating floor and exclusions nobody asked for. A request that finds nothing widens itself, letting the least important filter go first and saying which one it let go.

08Search by meaning

Sometimes a person knows the feel of what they want and not its name: something cosy and clever, or the film where a character says a line they half remember. For that, each box builds a profile of every title it meets.

A profile has TMDb's curated keywords, tags from the local language model for tone, themes, setting, pace and audience, and two meaning vectors from a local embedding model: one for the whole profile and one for the feel alone. Close vectors mean similar things. In a measured example, a cosy village murder mystery scored 0.81 against a gentle English whodunit and 0.28 against a space battle epic. The model's tags only ever rank results. Nothing it says is shown as fact.

Two research datasets add what viewers measurably feel and longer plots than the one or two lines OMDb carries: the MovieLens Tag Genome and the MPST plot synopses. Both forbid redistribution, so nothing is committed. Each box downloads and builds its own copy, and the project documents every source, its terms and its use.

Finally, subtitles. Every line of an owned film's subtitles goes into a full-text index, so a quoted search finds the film and the minute. A subtitle file beside the video is read at once. A track inside the video means reading the whole file, about 90 seconds a film, so that happens only overnight, a few at a time, and never while something is playing.

09Watching from another room

Phones and tablets on the home network can browse and watch without taking over the television. Access is an address check, not a secret in the URL. Every request from outside the private address ranges is refused before anything else is considered, an address that cannot be parsed is refused too, and forwarded-for headers are ignored because they are a claim made by the caller. A false refusal is one puzzled tablet. A false admission is the library on the internet.

Each viewer gets their own screen, and all of them share one library object. That sounds simple, and it broke the first way it could: a helper returned a new copy of the index, so a phone marked an episode watched and the television never found out. The rule now is to write into the shared library, never to rebind it. A viewer leaving the room also must not turn the television off.

Playback is HLS, produced on demand by ffmpeg, either as a copy of the streams or through the box's hardware encoder. The arithmetic is mine rather than ffmpeg's. Each seek starts a fresh run in its own directory, numbered from zero, and I map global segment numbers onto files. The playlist is written by the app, so a player can seek past the point the encoder has reached. The player library ships with the app, because a television box may have no route to the internet.

Tablets taught the rest. A tablet on Wi-Fi sleeps, drops and wakes, so a lost segment is retried rather than fatal, only one poll is ever in flight, and dragging the seek bar seeks once on release, because every far seek restarts the encoder. The stutter that remained came from segment lengths, which is one of the lessons below.

10A box that runs with nobody watching

A television box runs for months. Nobody reads its logs, and it gets switched off at the wall. So nothing may need a human to recover. The library is saved to a temporary file and then renamed, so a power cut cannot leave half a file. A file that cannot be parsed is never treated as empty, and a damaged library restores itself from the newest good daily backup, keeping the damaged copy aside. Failed lookups retry on their own, a stale record of a show still airing is fetched again, and leftover encoder processes are cleared at start.

A command called doctor answers the question that matters on a new box: can it record what you watch? It checks the player, names whatever owns its control port, checks the folders, and launches the player with no window to prove a position can be read. Its most useful check needs only the library: titles played, none ever finished and none holding a position is not a hint, it is a diagnosis.

There is also a rating limit per box, set on an admin page. It holds wherever a title is listed or a file is handed out: the grid, search, a show's episodes, the player and the stream. Unknown ratings are blocked unless the admin allows them. The admin login is created by the owner on first visit and stored as a salted PBKDF2 hash, and every change must carry a header another site's form cannot send. An optional door PIN asks other devices once, and never the television itself.

11How it is checked

The suite runs from a clean clone with the standard library; the few sections that build Qt widgets skip themselves when Qt is absent. By the project's own record it holds 1,412 checks. The house rule is that a feature without a test is not done.

Unit tests were not enough for the page. A syntax check cannot see a scope error, and two of those shipped and broke the whole app. So a script executes the real page code against every view with a stub DOM, and then clicks every control. The list of controls is derived from the handlers' own code, so a new control is covered the moment it is written. I proved it by putting the old bugs back into a copy of the page and watching it fail.

Beside the suite sit tools that check a real box. One renders a view at 1920 by 1080, the size that matters, because three faults in one session were invisible in the markup and obvious once drawn. One walks the page with a remote's buttons. One plays a title the way a browser does, following the playlist, seeking, and reading back what arrived. One runs real Discover searches in a private session, so the television's own screen is never driven, and checks every row against its band.

12Ten lessons

The project keeps a lessons file, and every entry in it cost something: a shipped bug, a wasted deploy, or a feature that looked finished and was not. These are the ten I would most want someone else to read. Nearly all of them are the same rule meeting a different wall: measure or cite, never infer.

01The feature was right; it was talking to another program

Resume and 'watched' had each been built twice and neither worked. The library's own data showed titles played and not one ever finished or holding a position. The tracking code was correct. The player's control port was already held by another program's web interface on that box, so the player could never bind it, every position query went to the wrong application, and a fallback recorded one-second viewings. On the same box, the configured player path did not exist, so every play went through the file association with nothing watching it. Neither fault raised an error.

Now: The port is resolved and then verified, the player is found in its real install locations, a play with no readable position is recorded as started and never as progress, and the doctor command checks all of it on every new box.

a lesson a human has to remember is not solved; turn it into a check that runs.

02A fix must be able to reach the data it fixes

Folder-based grouping landed, the box re-indexed, and the count of loose files came back byte-identical. The refresh compared a folder signature, nothing on disk had moved, and even a forced rebuild copied each stale record straight back because every timestamp matched. The same was true of a fix to the metadata lookup: on a fully enriched library it would have applied to nothing.

Now: Derived data carries a version stamp, bumped in the same change as the rule, and a re-derive really re-parses instead of re-copying.

a correct fix that cannot reach stored answers looks exactly like a wrong one.

03A miss and an outage are different answers

OMDb answers 'no such film' and 'your key is dead' the same way, and only the error text separates them. Rotating keys on the wrong one burns every key hunting for a film that does not exist. One service later the same trap appeared again: TMDb lookups recorded 'this show does not exist' when the network had simply dropped, which blacklisted a real show for good.

Now: Three outcomes, never two: found, genuinely absent, and could not ask. A key ledger also separates a dead key from one that is merely spent for the day, and shows the remaining budget.

never record a fact about the world from a failure to reach it.

04Rendering is not running, and running is not clicking

A syntax check passed while two scope errors broke the whole app; one left the header and chips drawn and not a single poster card. I built a harness that executes every view against a stub DOM. Then a handler that called the wrong function rendered perfectly and would have thrown the moment anyone touched it, because the harness drew everything and clicked nothing.

Now: The harness clicks every control, with the list derived from the handlers' own code, and it was proven by reintroducing the old bugs into a copy of the page.

a check is only as deep as the journey it actually walks.

05A capability bolted to an optional component

Automatic poster and rating fetching lived inside the voice assistant. The television runs the catalogue without the assistant, so it never fetched anything in its life, and most of its cards had no poster. The same shape appeared three times: a gesture that only existed when the tray icon did, and two background passes that only existed with a microphone. Each read correctly in the file it was written in.

Now: Background passes live in the shared core, and both ways of starting the app call them.

ask which process actually runs this on the box that needs it.

06A question answered at the wrong width

The day streaming shipped, a table answering 'can a browser decode this audio codec?' was used to settle 'can this stream container carry it, and can the player get it back out?'. They sound alike and are not. Films played with no sound and no error. A measured number about what a downmix costs was then used to decide whether a browser could play six-channel audio, and it could not, so nothing played at all.

Now: When a value crosses a boundary, from decoder to container or from cost to compatibility, the question is asked again in the new context and the answer gets its own name.

an honest answer to a neighbouring question is still the wrong answer.

07A checker that stops early reports success

The playback checker fetched the first three segments and never looked inside them. All three came from the first encoder run, so a clock that restarted on the second run was invisible, and a stream no browser accepts read as 'plays'. Another round of checks built the URL it expected instead of following the playlist, and missed a playlist with no media id in it. The remote prober once found zero controls in a panel and printed that every control was reachable.

Now: Checkers walk the whole journey a real client walks, follow what the server actually returned, read back what arrived, and treat 'could not look' as different from 'found nothing'.

a test that builds its own input is testing itself.

08I could not read it is never it is empty

Mid-film on a tablet, a save rewrote the library file in place. The background rescan read it at that moment, turned the half-file into an empty library, and rebuilt it from bare file names, then saved that. Every poster, rating, episode record and watch history was gone, and the posters simply disappeared from the screen. It was recovered only because the operating system had kept a snapshot.

Now: Saves go to a temporary file and are renamed, an unparseable file is marked unreadable and is never written over or rebuilt from, the rescan works from the copy it holds, and a dated backup is kept each day.

the failure to read is a fact; do not convert it into a different one.

09A segment must be exactly what the playlist says

Tablets streaming from the box would stop or stutter and need restarting. The playlist the app writes promised a segment every six seconds, but ffmpeg can only cut at a keyframe, and the hardware encoder's own interval made every segment ten seconds long. A player asking for one stretch of the film was handed another, so it jumped, stalled and restarted the encoder again and again. A segment counted as ready once it had any bytes, so a half-written one could be served.

Now: Every re-encode forces a keyframe at each segment boundary, segments are written under a temporary name and renamed, and a stream that stalls three times steps down in quality. Verified on the box: segments of 6.0 seconds, contiguous.

when you promise a format, check the bytes against the promise.

10The model may only add what the sentence hints at

Discover learned to take a sentence. Asked for a slow-burn psychological thriller set somewhere cold, the model added decades, a rating floor and three exclusions nobody asked for. A spoken request once became five filters at once, because 'maybe' genres were treated as demands and a negative-sounding word produced exclusions. The screen said only 'try widening it'.

Now: A word table decides first. The model may fill only gaps the sentence hints at, a softly said genre is a preference, exclusions need a real 'no' or 'without', and a request that finds nothing widens itself one filter at a time, saying which.

give a model the gaps, not the steering wheel.

13What I would do differently

Most of what I would change is about order rather than technique. The faults that cost the most were not hard to fix once seen; they were hard to see.