Skip to main content

Module: karaoke

A karaoke machine as a dashboard workspace, modelled on PiKaraoke: search YouTube for karaoke versions, download them into a local library with yt-dlp, queue them up per singer, and play them on a stage pane built to be read from across a room. The agent is a first-class operator — karaoke.queue takes a song the way a person would say it.

Status: implemented. Search, download, library, queue, transport, pitch shift, and the agent tool group all work. Not built: scoring, a dedicated guest-facing mobile page, and playlists — see Deferred.

Karaoke is a module package: it lives in modules/karaoke and can be disabled and re-enabled from the Marketplace while the app runs. Its stage routes audio through the mixer via the audio.mediaStrip@1 service when the audio module is loaded.

The one idea: the session lives on the server​

Everything else follows from this. A karaoke night is one room, one screen, several people holding phones, so the queue cannot live in the stage component's React state. It lives in a process-global KaraokeSession (modules/karaoke/py/src/horrible_mod_karaoke/session.py); every mutation broadcasts the whole PlayerState on the karaoke /ws channel, and every client is a pure renderer of it.

Three consequences, each of which is a bug if you forget it:

  • The stage owns playback; the server owns intent. playing is what the room wants; the pane holding the <video> element reconciles toward it. That is why a remote can pause a video it isn't rendering. The stage reports its real position back (POST /player/progress) so remotes can draw a scrubber — the server never claims to know it.
  • Entry ids, not song ids. The same song queued for three singers is three entries. Keying the queue by song id would make "add it again for the next singer" a silent no-op, so removals and reorders address the entry_id.
  • Every mutation bumps revision. Broadcasts can arrive out of order after a reconnect; a client that renders a stale one shows a queue that jumps backwards, so the store drops anything older than what it holds.

A pleasant side effect: a workspace switch unmounts the stage pane (unmount is not close) and loses nothing but the video element — the session is untouched.

Layout contributions​

The stage window is the whole layout a host needs: running order in its left strip, search in its right.

ViewIdRoleNotes
Karaoke stagekaraoke.stagedocumentSingleton. Takes keyboard capture so its single-key transport bindings don't fight the shell's, and declares fullscreen: true — the stage is pointed at a room, and chrome around the lyrics is chrome the singers read past.
Queuekaraoke.queueembedded — the stage's left stripRunning order, reorder, history.
Find songskaraoke.searchembedded — the stage's right stripYouTube search + the downloaded library, in one pane.

The queue and search were dock tools until the pane consolidation. As docks they were two more launcher entries for one machine and outlived the stage in whatever workspace you left them in; as strips on karaoke.stage (both defaultOpen) they come and go with it, and openPanel('karaoke.queue') reveals the strip.

Commands and keybindings​

karaoke.open, karaoke.findSongs, karaoke.showQueue, karaoke.playPause, karaoke.next, karaoke.restart, karaoke.keyUp, karaoke.keyDown.

KeyCommand
spacePlay / pause
nNext singer
rRestart the song
↑ / ↓Raise / lower the key

All five are scoped when: "paneFocus == 'karaoke.stage'". Unscoped, space and n would be stolen from every text field in the app.

Settings​

karaoke.volume (default volume, 0–1) and karaoke.searchResults (how many YouTube hits to request).

Search: biased toward karaoke versions​

The search route appends karaoke to the query unless the user already typed it. This is the highest-value thing PiKaraoke does with search — nobody opening this pane wants the original recording — and it's a flag (karaoke=false) rather than a hardcode, so the agent can search literally when asked to.

Searching uses yt-dlp's ytsearchN: pseudo-extractor with extract_flat, which returns the result list from one page fetch. Resolving each hit's formats is roughly a second per result and makes the search box unusable.

Downloads​

Downloads do not ride the shared task queue (backend.modules.tasks), which runs jobs serially — a karaoke download is minutes of network I/O, and putting one there would park every library ingest behind it. They run as detached asyncio tasks under a semaphore of 2, so a party can queue songs at once without saturating the link. Progress lands on the karaoke channel as song events.

Queueing a song that is still downloading is deliberate: the entry holds its place in the running order and the file arrives long before that singer's turn. Waiting would push a guest's song behind ones queued after it.

That has a consequence which is easy to get wrong, and did go wrong once: an entry can reach the stage before its file exists. A <video> pointed at a media URL that 404s sets error.code = 4 and never retries — so the first song of the night would sit black forever, even once its download finished a second later. Hence QueueEntry.ready: the stage renders a waiting screen instead of mounting a media element, and session.song_downloaded flips the flag and rebroadcasts when the file lands, which is what starts playback. A download that fails drops its waiting entries and advances the stage, rather than stranding the room on a song that will never play.

The filename is the row id, not the title. PiKaraoke encodes metadata into the filename (Artist - Title---videoid.mp4) because its library is the directory listing; here the database is the index, so a filename only has to be unique and safe on every OS — which a title never is (AC/DC, emoji, a 1,200-character clickbait title, Windows' 260-character path limit).

YouTube needs a JavaScript runtime. yt-dlp solves YouTube's player challenges by running scripts from yt-dlp-ejs (pulled in by the yt-dlp[default] dependency) in a JS runtime, and it enables only deno by default. Without one, YouTube withholds most formats and 403s the rest — measured 2026-09-10 on yt-dlp 2026.7.4, the pre-muxed mp4 died with HTTP Error 403: Forbidden. download_opts therefore passes js_runtimes for deno, node and bun; a missing runtime is skipped. The table is copied per download, because yt-dlp mutates it in place.

Video is two streams joined by ffmpeg. YouTube no longer serves a single pre-muxed mp4 for most songs — measured 2026-09-10 on yt-dlp 2026.8.19 with a runtime, the format list held separate video-only and audio-only streams and nothing combined, so the old best[ext=mp4]/best failed with "Requested format is not available". So download_opts picks the format by whether ffmpeg is present, looked up per download (transpose.ffmpeg_path, the binary pitch shift uses) so installing it takes effect on the next song without a restart:

DownloadFormatResult
Video, ffmpeg presentVIDEO_FORMAT: bv*[vcodec^=avc1][height<=720]+ba[ext=m4a], then any mp4 video ≤720p + m4a, then a single file, then last video ≤720p (H.264 preferred) + any audio, for a video whose only audio is Opus/WebM — ffmpeg copies Opus into the mp4merged .mp4, ffmpeg_location passed explicitly
Video, no ffmpegNO_FFMPEG_FORMAT: b[ext=mp4]/b/ba[ext=m4a]/baa pre-muxed file if the video still has one, else audio only
Audio only (start_download(..., audio_only=True))AUDIO_FORMAT: ba[ext=m4a]/ba/b.m4a; ffmpeg is never consulted

H.264 comes first because it decodes in every browser and WebView without depending on hardware codec support, which AV1 and VP9 do; 720p is plenty for lyrics on a TV. Verified with a real --test download: with ffmpeg the selector took 136+140 (720p H.264 + m4a) and merged them into one .mp4; without, it fell through to 140 and wrote an .m4a.

Without ffmpeg the song still downloads, because a song you can sing to with no picture beats a failed download. download_song recognises the fallback (got_audio_only: the result's vcodec is "none", or the extension is an audio one when codecs are missing) and lands the row as ready with a note in error (AUDIO_ONLY_NOTE). The Library row renders error inline and only disables a song whose status is failed, so the note explains the black stage without blocking the song. The Search tab shows an install hint whenever /status reports no ffmpeg. An audio-only request (audio_only=True) carries no note: it asked for audio on purpose.

Pitch shift​

Right the key for a singer with ♭ / ♯, ±6 semitones. Shifting pitch without changing tempo is three ffmpeg filters, not one:

asetrate=44100*r , aresample=44100 , atempo=1/r r = 2^(semitones/12)

asetrate plays the stream faster and higher (the tape-speed trick), aresample restores the expected sample rate, and atempo slows it back — leaving only the pitch change. Dropping atempo is the classic bug and yields chipmunks; a test pins its presence and its direction. ±6 is the clamp because atempo accepts 0.5–2.0 per instance and 2^(6/12) ≈ 1.414 fits in one stage.

This is a live transcode, not a cached file. A cached shifted copy would be seekable and cheaper on a replay, but singers change key while hunting for their key — up two, no, down one — and each change would be a full-length re-encode before a single note came out. A pipe starts playing in about a second at the cost of losing seek, which is the right trade for the one control people actually reach for mid-song. Accordingly /media/{id}?semitones=N does not advertise accept-ranges, and changing key is a <video> source change on the client.

ffmpeg is only needed for this. Without it on PATH, everything else works and the transpose endpoint returns 503.

Backend surface​

Mounted at /api/karaoke.

RoutePurpose
GET /search?q=YouTube search (karaoke-biased).
GET /songs, DELETE /songs/{id}The downloaded library.
POST /downloadFetch a video; optionally queue it in the same call.
GET /media/{id}[?semitones=]Serve the video. Range-capable at the original key.
GET /playerThe whole PlayerState.
POST /queue, DELETE /queue/{entry_id}, POST /queue/move, POST /queue/clearRunning order.
POST /player/{play,pause,next,restart,stop,seek,volume,transpose,autoplay}Transport.
POST /player/progress, POST /player/endedThe stage reporting back.
GET /statusWhat this node can do (yt-dlp / ffmpeg present). No ffmpeg means audio-only downloads and no pitch shift.

Every session mutation returns the full PlayerState and broadcasts it, so a caller never re-fetches after acting.

GET /media/{id} implements Range properly, including the suffix form: bytes=-3 asks for the last three bytes. Reading that number as a start offset is the classic misread and serves the wrong part of the file; there's a test for it.

Storage​

WhatWhere
Song catalogkaraoke_songs table in $HORRIBLE_DATA_DIR/app.db
Media files$HORRIBLE_DATA_DIR/karaoke/songs/<song_id>.<ext>
Session (queue, now playing)Memory only — a night's running order is not a durable record

Agent tools​

Grouped under karaoke, so they're disclosed on demand rather than costing context on every turn. Six tools, and the split is by what a host asks for, not by HTTP route.

ToolPurpose
karaoke.statusWhat's playing, how far in, what's queued and for whom. Source of entry_ids.
karaoke.queueThe main one. Queue a song by name.
karaoke.controlEvery transport verb behind one enum, plus volume/transpose/autoplay.
karaoke.unqueueRemove one entry by entry_id.
karaoke.searchSearch without queueing, when the user wants options.
karaoke.libraryWhat's downloaded; never touches the network.

karaoke.queue deliberately takes a search phrase, not a song id. Asked to "put on some Fleetwood Mac", a model given only an id-taking tool has to search, pick, download and queue across four turns — and reliably fumbles one. This tool does the whole path: it prefers a copy already in the library (instant, already the right cut, no bandwidth), otherwise searches, starts the download, and queues the entry immediately.

Both list panes expose an agent context snapshot, and the queue's includes entry_id — a title wouldn't identify a song queued twice.

> queue Africa by Toto for Sam, then put Dancing Queen next
karaoke.queue(query="Africa by Toto", singer="Sam")
karaoke.queue(query="Dancing Queen", next=true)

Browser vs desktop​

BrowserDesktop
Stage, queue, search✅✅
Search + download✅ (backend does the work)✅
Pitch shift✅ when ffmpeg is on the node's PATH✅ same
Remote control from a phone✅ with the backend bound to the LAN (pnpm dev:lan)✅ pnpm dev:desktop binds 0.0.0.0 already

No platform branching in the module: the session is server-side, so both layouts are the same client.

Setup​

yt-dlp is a core dependency (uv sync) — it's a pure-Python wheel with no native build; its [default] extra brings yt-dlp-ejs, and YouTube additionally needs a JS runtime (deno, node or bun) on PATH. ffmpeg is optional but gates two things: video downloads (without it songs download as audio only, with a note on the row) and pitch shift. Install it however your OS prefers and make sure it's on PATH.

Content is not bundled and never will be — the same rule hassault applies to AssaultCube's media and search applies to SearXNG. Songs are fetched from YouTube to the user's own node, on their own instruction, and stored only there.

Deferred​

  • A guest-facing mobile page. The architecture already supports it — the session is server-held, so a phone pointed at the node is a working remote — but there's no stripped-down guest UI or QR code onboarding yet, and no admin password gating what a guest may do. PiKaraoke has both.
  • Scoring. PiKaraoke's is famously random.
  • Playlists / saved set lists, and importing a local media folder.
  • Drag-and-drop queue reordering. ↑/↓ buttons today: this pane is most likely to be driven from a phone in a dark room, where a precise drag against a scrolling list is genuinely hard. POST /queue/move takes an index, so a drag implementation is a client-only change.