docker-dosbox-novnc/TODO.md

TODO

• ~Reduce image size of jayfield/dosbox-novnc (currently 2.3GB). Done in two steps:

  1. Merged the game download/extract steps and the unzip/smbclient install into a single layer (so the downloaded zips and the packages only needed to extract them no longer persist in the final image). 2.31GB -> 1.6GB.
  2. Stopped baking the games into the image at all (927MB of that was just t7g's two CD ISOs). run.sh mounts a named volume (dosbox-games) so installed games persist across --rm restarts. 1.6GB -> ~690MB. Container now needs network access to vlda-01 at runtime (not just build time) to install games.
  3. Dropped the auto-download at container startup entirely. scripts/setup_server.py is a small stdlib-only HTTP server (started alongside Xvnc/fluxbox/websockify) that serves an HTML page on ${SETUP_PORT} (70${DISPLAY_NUM}, published as 7099 by run.sh) listing every *.zip on the SMB share with an Installed/Install status per game; the user clicks "Install" to fetch+extract a specific game into ${GAMES_HOME} on demand.

• Manifest-driven games + Start/Stop/Uninstall (test balloon, stuntcar only): games are no longer discovered from raw *.zip files on the share. setup_server.py now lists *.json manifests instead (one per game, e.g. Games\dosbox\stuntcar.json), each declaring name/title/zip/start_cmd. The web page grew Start/Stop/Uninstall buttons alongside Install, driven entirely by that manifest — nothing about a game's identity or how to run it is hardcoded in the image anymore. Only stuntcar.json exists on the share so far (as a deliberate pilot); t7g has no manifest yet and will not show up in the setup page until one is added (t7g.json with a start_cmd for its dosbox-0.74-3.conf). game.sh/scripts/start_game.sh (the old docker exec-based launch path, with its hardcoded DOSBOX_VERSION/run.bat convention) were intentionally left untouched for this pilot and now overlap with the new Start button — worth reconciling (or removing) once the manifest approach is rolled out to all games.

• Create manifests for SCUMM engine games (Monkey Island, Day of the Tentacle, Indiana Jones, etc.). Note these are usually best run via ScummVM rather than raw DOSBox — scummvm isn't installed in the image yet, so this may need a Dockerfile change (add the scummvm package) alongside the manifests themselves, and each manifest's start_cmd would invoke scummvm with the right game-id instead of dosbox run.bat -conf ....

• Get game sound actually audible during play. --device /dev/snd is passed through and alsa-utils is installed, so DOSBox can write to an ALSA device inside the container, but VNC/noVNC only ever streams video, not audio — nothing currently carries that sound out to the browser.

  Target latency is a few tens of ms, not seconds — that rules out the "obvious" approach of a PulseAudio null sink piped through ffmpeg into a compressed (mp3/ogg) HTTP/Icecast-style stream consumed by an <audio> tag: codec frame buffering plus the <audio> element's own jitter buffer realistically puts that in the 1-3s range, no matter how it's tuned.

  Concrete approach instead: PulseAudio null sink → capture raw/lightly-buffered PCM (small frames, e.g. parec with a short --latency) → push those frames to the browser over a plain WebSocket (new endpoint alongside setup_server.py, or a small dedicated process) → browser side, feed them straight into the Web Audio API via an AudioWorkletNode (not <audio>, not ScriptProcessorNode — that's deprecated and has worse latency) for near-real-time scheduled playback. No container/codec framing in the path at all.

  Build this to be reusable across the other noVNC-family projects (docker-xserver-novnc, docker-sdr-novnc), not dosbox-specific — it's a "browser audio + noVNC" concern, nothing about it is really about DOSBox. Follow the docker-common/scripts/signals.sh precedent (see the docker-common repo): keep the generic PulseAudio-sink/WebSocket/AudioWorklet piece project-agnostic there, then copy it (not symlink) into each project's own scripts/ the same way signal handling is shared, so a fix in one place gets propagated by hand to the others.