Changelog

Leer en español

Format loosely follows Keep a Changelog.

Versioning

This project uses date-based version numbers (vYYYY.MM.DD), not semantic versioning – there is no compatibility contract between versions to track (it’s a single dedicated appliance build deployed to one Pi, not a versioned library with multiple independent consumers). A version is just “the state of this component as of this date,” matching the date-grouped structure this changelog already used before versioning was introduced.

Each independently-installable component tracks its own version, in its own VERSION file, bumped whenever a meaningful change to it lands on main:

• VERSION – the base pedal system (src/, systemd/, root docs).
• expansions/setlist-admin-usb/VERSION
• expansions/setlist-admin-wifi/VERSION

To check what’s actually deployed on the real Pi: ssh -4 pedal "cat ~/chocolatepi-repo/VERSION ~/chocolatepi-repo/expansions/*/VERSION" (compare against the git commit it’s checked out to, since a VERSION file only changes when someone remembers to bump it – the commit hash is always the ultimate source of truth; the version number exists to give a human a memorable string to reference instead of a hash).

This changelog stays the source of truth for what changed and why; [Unreleased] collects changes not yet cut into a dated version below it. Cutting a version means: confirm the change actually works end-to-end (real hardware for anything touching it, not just unit tests), bump the affected component(s)’ VERSION file(s), and rename [Unreleased] to that date – reopening a fresh empty [Unreleased] above it for whatever comes next.

[Unreleased]

• Fixed a real race in rollback.sh, found running it for the first time ever against the real Pi (2026-10-03): disabling setlist-admin.service before usb-tether-watchdog.service left a window where the watchdog – now also WiFi-aware, not just phone-tether-aware – started it right back up moments later, while its unit file was still on disk. Confirmed live: systemctl status showed it active again minutes after the script finished, Loaded: not-found. Fixed by disabling the watchdog first, closing the window. Re-ran the full uninstall → reinstall cycle afterward and confirmed pedal-core.service was never touched, the PIN hash and every Bank in the library survived byte-for-byte, and the admin app came back up on its own over WiFi immediately after a fresh install.
• library-optimizer.service now automatically cleans up leftover scratch files from an interrupted job, real user request after noticing ~470MB of them had piled up over one day of testing (2026-10-03): a service restart mid-job (manual, a crash, a reboot) abandons whatever _process_job() was mid-copy/mid-encode – recover_orphaned_jobs() already reset the queue’s status back to “queued” in that case, but had no idea the abandoned scratch_input/scratch_output files under ~/pedal-optimizer-scratch/ existed, so they just sat there forever (previously only removed by rollback.sh, i.e. only on a full uninstall). run_forever() now sweeps the entire scratch directory once, unconditionally, at every startup, before the first tick – always safe, since a job reset to “queued” gets a brand new scratch copy under a fresh random filename once it’s picked up again, so nothing already on disk at startup can ever be resumed or referenced. Mirrors the same pattern already used for the USB’s own .part files and the admin app’s upload-scratch directory (see the entry below). 5 new tests in tests/test_library_optimizer.py.
• Fixed: a slow upload held pedal-core.service stopped (no standby, no playback at all) for its entire network-transfer time, real incident found live testing the new WiFi-reachability feature above (2026-10-03): upload_song()/assign_track() (expansions/setlist-admin-usb/src/admin/api.py) used to read the upload’s raw, network-backed stream directly inside _writable_usb() – so the window pedal-core.service stayed down for was bounded by the uploader’s own connection speed, not by the USB write itself. Confirmed live: a 76MB upload over a weak WiFi connection left the pedal dark for roughly 15 minutes. Fixed by receiving the upload to local scratch storage on the Pi first (AdminAPI._receive_to_scratch(), new --upload-scratch-dir, cleaned up at startup the same way .part files on the USB already were) and only wrapping the short, local-disk-speed copy from there onto the USB in _writable_usb() – the same scratch-then-copy pattern library_optimizer.py already uses for its own, often larger, ffmpeg output. 4 new tests in tests/test_admin_api.py, two of which fail immediately (by design) if a future change ever goes back to reading the upload stream inside the writable-USB window.

• setlist-admin-usb can now also be reached over WiFi, no phone needed, real user request (2026-10-03): usb-tether-watchdog.service (expansions/setlist-admin-usb/src/admin/usb_tether_watchdog.py) gained a second, independent condition alongside phone-tether detection – wifi_connected_to_profile() checks via nmcli whether the Pi’s active WiFi connection is an exact match for one specific, named NetworkManager profile (default "preconfigured", the one Raspberry Pi Imager saves during initial setup – confirmed live via nmcli that this is exactly how the Pi already reconnects to the band’s home WiFi with no extra configuration whenever a USB WiFi dongle is plugged in). setlist-admin.service now starts if either a phone is tethered or the Pi is on that trusted WiFi network, with both able to be true at once with no conflict; losing both stops the service, same as before. Deliberately trusts only that one named profile, never “any WiFi with a usable IP” – an unrelated network (a venue’s guest WiFi, say) must never expose the PIN-gated admin app. See that expansion’s SPECIFICATION.md section 16 and USAGE.md’s “Reaching the app over WiFi” for the full design and usage. 10 new tests in expansions/setlist-admin-usb/tests/test_admin_usb_tether_watchdog.py.

  As part of the same work, setlist-admin-wifi (the separate, more complex expansion with its own hotspot-configuration UI and encrypted on-USB credential storage) is now formally reframed in its own docs as a roadmap item, not near-term work – it’s implemented and unit-tested, and its original hardware blocker (a dead USB WiFi dongle) was resolved 2026-10-01, but a full revival isn’t worth doing now that the simpler feature above covers the actual need. No code in that expansion changed. Also documented: the actual procedure for changing which WiFi network the Pi connects to after its initial setup (systemd/README.md’s new “Changing which WiFi network the Pi connects to” section, cross-referenced from TROUBLESHOOTING.md and setlist-admin-usb’s USAGE.md) – there wasn’t one written down anywhere before this.

• Added a resource-aware video lane, real user request (2026-10-03): the video lane’s mpv process was measured live costing a full CPU core (~106%) and ~300MB RAM (34% of the reference Pi 2’s total ~921MB) continuously, just to loop standby – real, ongoing cost for nothing if no display is physically connected to show it. A new DisplayMonitor (src/core/display_monitor.py) polls the DRM connector’s sysfs status (debounced, so a loose/flickering cable doesn’t flap the lane) and Core.set_display_connected() starts/ stops the video lane accordingly, including once at startup with the real boot-time state. With no display connected, a video track plays its audio only (through the same lane an audio-only track already uses) instead of doing nothing – the system stays fully functional. Deliberately never interrupts what’s already playing: a clip already playing when the display disconnects keeps playing, audio and all, until it ends on its own or STOP is pressed; a live mid-clip handoff between lanes was considered and rejected (real audio-glitch risk syncing position between two independent mpv processes). See MASTER_SPECIFICATION.md’s “Resource-aware video lane” entry for the full decision record. 20 new tests (tests/test_core.py, tests/test_display_monitor.py – core.py and player.py previously had zero automated tests, only the manual core_smoke_test.py; the new logic here is pure routing/state, genuinely unit-testable with mocked Player/AudioPlayer).

  As a side effect, this also self-heals a real incident from the same day: connecting the HDMI cable after powering on used to leave the Pi showing no video at all until a manual systemctl restart pedal-core.service – the kernel’s own DRM hotplug detection worked, but the already-running mpv process never rebound to it. Now the video lane simply wasn’t running yet in that case, and starts fresh (correctly binding to the now-connected display) within a few seconds of the monitor detecting the cable – see TROUBLESHOOTING.md’s updated entry.

• Fixed a batch of real issues found during a full user QA pass (2026-10-02), both expansions unless noted:
  • pedal-core.service could crash-loop for several minutes under heavy CPU load: a library write’s cleanup remount losing a race with pedal-core.service’s own mpv (an existing, legitimate fallback – stop it, force the remount, restart it) means a brand-new mpv has to spawn and open its IPC socket from scratch, and that took longer than the 5s budget while a concurrent “Optimize” job’s ffmpeg was pinning the CPU – confirmed live, the pedal showed mpv’s idle screen for a couple of minutes. Raised to 20s in src/core/player.py (base pedal system, not an expansion) – normal startup is unaffected (well under 1s with no contention).
  • list_sets() listed filesystem-reserved folders (e.g. an NTFS-created system folder) as selectable Sets – confirmed live on the real library USB.
  • The “Optimizing”/”Queued” states rendered identically (both green “Optimizing”) – with two jobs in flight, there was no way to tell which was actually running vs. just waiting its turn. Confirmed live: this caused cancelling the wrong one by mistake. Now visually distinct.
  • Uploading to the library always sent the whole file before learning about a name collision – normally fast, but can wait minutes if the USB is busy with an unrelated scratch-copy. Now checks the already-loaded song list client-side first, instantly, for the common case.
  • A slow/overloaded Pi could abort a request at the network level, surfacing a raw, untranslated “TypeError” instead of a clear message.
  • “Set as standby”/”Unlock”/”Set PIN” buttons gave no tap feedback, and the standby dropdown stayed on the just-applied video afterward, looking unfinished.
  • New Bank creation asked for a number by hand – Banks are sequential slots a MIDI controller steps through one at a time, so it now auto-assigns the next one. Not capped at any specific controller’s own physical bank count.
• Fixed, real incident (2026-10-02): starting a second “Optimize” job while another’s source was still being copied off the USB could 500 (RemountError) – setlist-admin.service and library-optimizer.service are two independent OS processes with separate memory, so usb_mount.py’s existing in-process threading.Lock() did nothing to stop a write in one from racing a long read in the other. Added a real cross-process file lock (flock() on a well-known path, skipped on Windows where fcntl doesn’t exist – local tests still rely on the in-process lock alone) that every write and the scratch-copy step now share, via a new usb_mount.exclusive_read() – a concurrent write now simply waits its turn (bounded at 5 minutes) instead of racing a umount against an open file descriptor and losing.
• Fixed, real incident (2026-10-02): cancelling an “Optimize” job could 500 (RemountError) if tapped within the first stretch of a job’s life – the cancel marker lived on the USB alongside every other job marker, so writing it needed the same writable-USB remount as any other write, but the scratch-copy step that runs before every encode (see the write-blocking fix below) holds a read handle open on the mount for as long as that copy takes, well past the mount’s own bounded EBUSY retry (tuned for a brief pedal-core.service/mpv collision, not a multi-second-to-minutes file copy). Moved the cancel marker to local Pi storage instead (optimize_queue.DEFAULT_STATE_DIR, ~/.pedal-optimizer-state/) – it only ever needs to reach this Pi’s own library_optimizer.py process, never the USB stick itself, and never needs to survive a reboot (a job that survives a reboot gets requeued fresh via recover_orphaned_jobs() anyway, so a stale cancel marker surviving would have incorrectly re-cancelled the next run). cancel_song_optimization() no longer needs a writable-USB window at all now. Both expansions.
• Added a ES/EN language toggle, both expansions: a dropdown in the topbar (now reading “ChocolatePi - Setlist Admin”) switches all UI chrome – labels, buttons, confirms, alerts, toasts – between English and Spanish, persisted per-browser via localStorage (static/i18n.js). Song/track/Set/Bank names are user data and are never routed through translation, by design – every render function keeps those out of the translation calls on purpose. Server-sent error messages stay in English for now, a separate, explicitly deferred piece of work.
• Added auto-refresh for optimize/cancel status, both expansions: cancelling or starting a job resolves on the backend in seconds, but the app only ever re-fetched song state on an explicit action, so the Cancel/Optimize button stayed stuck showing the old state until a manual page refresh. Polls GET /api/songs every 5s only while something is actually queued/running, and stops itself the moment nothing is.
• Fixed, real incident (2026-10-02): a song’s “Optimize”/”Cancel” state could show stale (e.g. “already optimized” while a job was genuinely still running) after a refresh – GET /api/songs is a plain GET with no Cache-Control header, so a browser’s own heuristic caching served a stale response. Same fix as the static-file one below, applied to every JSON response too (_send_json()). Both expansions.
• Added a power-loss warning and a real Cancel button for “Optimize”, both expansions, after a real question about what happens to the Pi and the file if it loses power mid-job: tapping “Optimize” now shows an explicit warning not to unplug the Pi while it’s running, and once a job starts, a “Cancel” button appears next to it (optimize_queue.request_cancel()/is_cancel_requested(), checked by library_optimizer.py between ffmpeg polls and before a queued job starts). The in-progress indicator reads “Optimizing…” (shown as a standing green button, not hidden, alongside “Cancel”) rather than disappearing in favor of the Cancel button.
• Fixed, real incident (2026-10-02): a stale app.js/index.html mismatch could leave a refresh showing only the topbar, nothing else – no Cache-Control header at all on static files, so a stale cached copy of one file could be served alongside a fresh copy of another. Added Cache-Control: no-cache, no-store, must-revalidate to _serve_static(). Both expansions.
• Fixed, real incident (2026-10-02): the Export Set share/download image still had the old “supported formats” disclaimer baked into the PNG itself, even after an earlier commit removed it from the on-screen view – a separate, canvas-drawn copy in renderSetlistToPngBlob() that the earlier fix missed. Removed entirely (SUPPORTED_FORMATS_DISCLAIMER/ wrapTextLines() deleted). Both expansions.
• Fixed, real incident (2026-10-02): an “Optimize” job running ffmpeg directly against the USB-mounted source held that file open for the entire encode (confirmed live, 45+ minutes for one 4K source) – umount refuses outright while anything holds a file open on that mount, reading included, so every other library write (even an unrelated “create Bank”) failed with a 500 the whole time. Fixed: library_optimizer.py now copies the source to local scratch before encoding; ffmpeg only ever touches the local copy. The USB mount is held open only for the brief copy itself, not the encode’s full duration.
• Fixed, real incident (2026-10-02): a transient ffprobe timeout under heavy concurrent load (several parallel codec checks plus a long-running ffmpeg job) got cached as a permanent “not optimized” result by the then-new per-file codec cache (codec_check.py) – three files got permanently stuck showing “Optimize” even after load cleared. Fixed: the cache now only ever stores a successful probe, never a failure.
• Fixed, real incidents (2026-10-02): forms (PIN entry, etc.) weren’t centered on a wide screen – main centers via margin: 0 auto, but a narrower form inside it never did, invisible on a phone, glaring on a tablet. Also fixed a ~37-second gap between logging in and the song library actually appearing (confirmed live, ~24 songs, several multi-GB videos): list_songs() ran ffprobe serially, every call, for every song – now cached per (path, mtime, size) and parallelized across up to 4 workers (I/O-bound, not CPU-bound).
• Fixed, real incident (2026-10-02): an “Optimize” job stuck “running” forever in the UI, with no “retry” option, after the Pi was rebooted mid-job – list_queued() deliberately never picks “running” jobs back up (on the assumption a different, live tick is already working on it), an assumption that breaks the moment the daemon itself is the one that died. library_optimizer.py now calls optimize_queue.recover_orphaned_jobs() once at startup, resetting any orphaned “running” marker back to “queued”.
• Real data-loss incident (2026-10-01) and the gap it exposed: the band’s actual standby video (a ~55-minute, ~754MB recording) was permanently overwritten with no backup when it was replaced through the app’s own “Set as standby” picker – library_ops.set_standby_video() does a plain _atomic_copy_file() straight over standby.mp4, with no copy of whatever it’s replacing. Recovered only because the user happened to still have the original, unconverted source file on a separate computer; re-encoded it with hardware-accelerated H.264 (h264_v4l2m2m for both decode and encode – confirmed live, about 0.87x realtime for 1080p/25fps source already in H.264, versus the ~0.1x this project saw earlier for a software-only HEVC decode) to ~800MB, re-added it to the library, and the user re-selected it as standby. Not yet fixed in code: set_standby_video() still has no backup step – a real, now-confirmed-costly gap. Deferred product decision, see NEXT_STEPS.md.
• A working USB WiFi dongle was found and tested (2026-10-01): a different chipset (Ralink/MediaTek MT7601U) than the dead one that originally paused setlist-admin-wifi (Realtek rtl8192cu). Confirmed on real hardware: the kernel’s own mt7601u driver attached cleanly, wlan0 came up and associated with the home network automatically via an already-saved NetworkManager profile, and SSH worked over it with eth0 fully disconnected. This is basic OS-level WiFi connectivity only – it unblocks resuming setlist-admin-wifi’s own hardware validation (see that expansion’s SPECIFICATION.md status note), but the expansion itself (its own systemd units, nmcli config read/write flows) still hasn’t been installed or exercised on this dongle. In the meantime, setlist-admin-usb’s server was reached directly over this WiFi connection too, as a manual, temporary workaround (it already binds 0.0.0.0:8080, so nothing-specific to USB tethering was needed – just starting it by hand with usb-tether-watchdog.service stopped so it wouldn’t immediately stop it back).
• Fixed, found deploying the “Optimize” feature below to the real Pi: library-optimizer.service crash-looped immediately (ModuleNotFoundError: No module named 'admin') – library_optimizer.py lives under src/admin/ and does from admin import ..., same as server.py, but unlike server.py it never added src/ to sys.path first. Invisible to the unit tests, since those already put src/ on sys.path themselves before importing it – only running it exactly the way systemd does (a bare python3 library_optimizer.py) surfaced it. Fixed with the same sys.path.insert(0, "..") line server.py already had. Both expansions.
• Deployed and verified on the real Pi (2026-10-01): full overlay- disable/deploy/test/re-enable/reboot cycle completed; 181 (USB) + 200 (WiFi) tests passed on the Pi itself; library-optimizer.service installed and confirmed genuinely running (not just “active” mid- crash-loop, which is how the bug above was first caught); a real end-to-end pass – a tiny synthetic HEVC clip uploaded straight through AdminAPI.upload_song(), queued via request_song_optimization(), picked up by the daemon in a few seconds, and reported H.264/needs_optimization: False once done – confirmed the whole pipeline (queue, daemon pickup, scratch encode, atomic copy-in, pedal_core_guard fallback, queue clearing) works for real, not just under mocks. pedal-core.service stayed up and standby.mp4 kept playing throughout. Not yet confirmed: the actual phone UI flow (tapping “Optimize”, watching the button read “Optimizing…”, disconnecting/reconnecting the phone mid-job) – that part was exercised via AdminAPI calls directly over SSH, not from the app itself. See expansions/setlist-admin-usb/NEXT_STEPS.md.
• Added a library-wide “Optimize” button, both setlist-admin expansions. Real user request: uploads already warned if a video wasn’t H.264 (section 9’s codec_check.py), but fixing it meant manually re-encoding over SSH – the same ~90-minute, one-off process this project had just done by hand for the standby video. Now the Song library lists an “Optimize” button next to any file (codec_check.is_optimized()) that isn’t already in the recommended format; tapping it queues the same re-encode (scale=-2:1080,fps=25, H.264 high@4.0, AAC 128k, documented in LIBRARY.md) without blocking the UI. Scoped to the library only – _Songs/ entries aren’t loaded into any live Set or the standby slot until the user separately assigns them, so an in-progress optimization never affects what’s actually playable right now.
  • The job queue is a small JSON file per song under .setlist-admin/optimize-queue/ on the USB itself (optimize_queue.py), not in-memory – so “Optimizing…” (shown instead of the button while a job is active, confirmed by polling GET /api/songs) survives the phone that queued it disconnecting and reconnecting later, exactly as requested. A failed job (corrupt/unreadable source, or a timeout past 4 hours) shows “Optimize (retry)” with the reason in the button’s tooltip.
  • The actual encoding runs in a brand new, always-on systemd unit, library-optimizer.service, deliberately independent of setlist-admin.service’s own lifecycle: a job this long has to survive the admin UI being stopped by the USB-tether/network watchdog the moment a phone disconnects, which a plain subprocess of that service wouldn’t. It polls the queue every 5s and processes one job at a time (this hardware can’t usefully run two ffmpeg encodes at once).
  • Unlike the manual standby-video conversion (which held pedal-core.service stopped, and playback dark, for the entire ~90-minute encode), the daemon reads the source with the USB still mounted read-only and encodes to a local scratch directory (~/pedal-optimizer-scratch/, off the USB entirely) – the shared pedal_core_guard.writable_usb() fallback (now its own module, extracted out of api.py once this daemon needed the identical stop-pedal-core/recover-broken-mount logic as a second caller) is only invoked for the few seconds it takes to copy the already- finished, much smaller output back into place. Nice=15/ CPUWeight=10 (more aggressive than setlist-admin.service’s own Nice=10/CPUWeight=20) keeps a running encode from ever starving live playback.
  • install.sh/rollback.sh (both expansions) now install/remove library-optimizer.service alongside the existing units, and rollback.sh also clears the scratch directory.
• Moved the “supported formats” hint (audio MP3/WAV, video MP4/MOV/ MPEG/MPG with embedded audio, plus H.264/1080p/~8-12 Mbps video guidance) from the Export Set screen – where it was pointless noise on a view meant to be read on stage, not uploaded from – to right next to the actual upload control in the Song library section, where it’s useful before picking a file. Real user request, both expansions.
• Fixed: found live while certifying the replace-on-duplicate feature just above – remounting /media/usb back to ro right after a large write (a multi-hundred-MB video) timed out at 10s more than once, even though the write itself had already completed successfully. The file was never at risk (confirmed: it landed correctly both times this happened), but the request still failed with a 500, and once the broken-mount auto-recovery above wasn’t even needed (the mount itself stayed intact – this was a plain timeout, not the dead-FUSE-mount incident from earlier). Root cause: the FUSE layer appears to still be flushing buffered data to the physical device at that point, which can outlast the write call itself having already returned. usb_mount._remount() now runs a best-effort sync -f <mount> before the umount/mount pair, forcing that flush to happen up front instead of leaving it to block inside the time-limited calls that follow. Both expansions, kept convergent.
• Added: uploading a song to the shared library with a name that’s already taken now offers “… already exists in the library. Replace it?” instead of just failing – confirm to overwrite it in place (_atomic_write_stream() already makes that itself safe, same as any other write here), or cancel to leave the existing one untouched. Real user request, made right after hitting the duplicate- name rejection during the same live testing session that found the two incidents below. library_ops.upload_song() gained an overwrite parameter and a more specific SongAlreadyExistsError (a LibraryOpsError subclass); api.py translates that specifically into ApiError(409) instead of a generic 400, so the frontend can offer the replace-it confirmation without string-matching the error text. Both expansions, kept convergent.
• Fixed: a third real incident from the same live certification session – a validation rejection that happens before the request body is read at all (e.g. upload_song()’s duplicate-name check, which runs before anything touches the stream) was sending its 400 response without first draining the still-unread body. For a real, multi-hundred-MB video, that left the connection in a state the client’s own TCP stack treated as reset – “Load failed” in Safari – even though the server’s response, with the correct rejection reason, had been sent. (Also discovered via this: the video had actually uploaded successfully on an earlier attempt, during the chaos of the broken-mount incident below – every retry since was correctly, if confusingly, being rejected as a duplicate.) Fixed: every raw-body upload handler (assign_track, upload_song, both expansions) now drains any unread body in a finally, regardless of success or failure, via a new _LimitedReader.drain(). Also: 400 responses are now logged server-side with their exact reason (server.py), not just the status code – a 400 is an expected outcome, not a bug, but not logging it meant no way to find out afterward what was actually rejected and why when a phone’s own alert() wasn’t seen in time.
• Fixed: a real incident, found live while certifying the new standby-video feature – every write in both setlist-admin expansions (uploading, renaming, assigning, the new standby picker, all of it) started failing with a 500 as soon as pedal-core.service ran continuously and stayed stable (which it now does, thanks to this same day’s MIDI-disconnect fix above – see that entry). Root cause: usb_mount.writable_usb() remounts the entire /media/usb volume rw for any write at all, no matter which file – Linux has no per-file read/write mode within one mount, so the whole volume has to have zero open file handles anywhere on it. pedal-core.service’s mpv keeps whatever it’s currently looping (always standby.mp4 in practice) open continuously and never releases it on its own – confirmed on real hardware: 30 straight seconds of retries, zero successes, while pedal-core.service ran normally; stopping it unblocked the remount instantly, every time. usb_mount._remount()’s bounded retry (0.3s x 5, built for a brief, transient busy window) was never going to get past a hold that doesn’t release at all. (Likely explanation for why this worked in earlier sessions: the MIDI-disconnect bug fixed earlier today used to restart mpv frequently on its own, which incidentally created the brief gaps this depended on – today’s stability fix removed those by accident.) Fixed in api.py (both expansions): every mutating method now goes through _writable_usb(), which tries the normal fast path first via a cheap, side-effect-free probe (an immediate rw-then-ro round trip, nothing written) – if the volume is free, nothing changes, zero disruption. Only if that probe itself fails does it stop pedal-core.service (releasing every open handle, including the looping standby video – playback briefly interrupts, screen goes black for a few seconds, same as any other pedal-core.service restart), perform the real write exactly once, then restart it afterward. The probe’s own full remount cycle is what makes this safe to fall back from without any risk of running the actual write twice.
• Fixed, found minutes after the fix above while actually certifying it on real hardware: a phone’s connection reset mid-upload (the new pedal-core.service stop adds a few real seconds before a write starts, which can trip a client-side timeout/backgrounding), and the recovery from that failed write – the remount back to ro – itself timed out after 10s and left the FUSE mount genuinely dead: mount still listed /media/usb as mounted, but every access returned ENOTCONN (“Transport endpoint is not connected”), because the ntfs-3g process backing it had simply exited. The fix above then restarted pedal-core.service into that broken mount, which made it worse – confirmed live: mpv showed its own “Drop files or URLs to play here” idle screen, with nothing loaded, until manually recovered over SSH (umount -l then a fresh mount -o ro). api.py (both expansions) now does exactly that recovery automatically: right before restarting pedal-core.service, it runs a real filesystem check (ls the mount point, not just trusting mount’s own output, bounded by a timeout so a hung rather than fully-dead backing process can’t block it) and self-heals first if it’s broken. If recovery itself doesn’t work, pedal-core.service still gets restarted regardless (logged as an error) rather than left stopped forever on a headless appliance with no one available to notice.

[v2026.10.01] – MIDI-disconnect resilience, standby video management

• Reverted same day: this version briefly logged mpv’s own stderr into pedal-core.log (see the next bullet for why it was added) – rolled back a few hours later. Reasoning: pedal-core.log lives under /home/, which under the normal, protective root overlay is RAM-backed (tmpfs), not disk – and nothing rotates it. Checked on the real Pi: the overlay’s effective cap is ~461MB (half of this Pi’s 921MB RAM, tmpfs’s own default sizing), with no rotation on any of this project’s three long-running logs (pedal-core.log, setlist-admin.log, usb-tether-watchdog.log). Unbounded log growth on an appliance meant to run indefinitely without a reboot is a real RAM-exhaustion risk, not just a disk-space one. A log that only earns its keep during an active debugging session isn’t worth that standing cost left on permanently – core/player.py is back to sending both mpv lanes’ stdout/stderr to DEVNULL. If a future investigation genuinely needs mpv’s own error output, capture it temporarily for that session (e.g. patch stderr=subprocess.PIPE and tail it live over SSH) rather than leaving it logged permanently. TROUBLESHOOTING.md’s “Audio (and video) stop completely…” entry reflects the final (reverted) state.
• Fixed: a real, reproduced incident – the M-VAVE being off or disconnected (at startup, or mid-session: a loose cable, a USB hub glitch, the kind of brief dropout a real undervoltage event can cause, see TESTING.md) used to be treated as fatal by src/main.py: the whole process exited and depended entirely on systemd blindly restarting it every RestartSec=5, which also killed and relaunched both mpv lanes every single cycle (visible as the screen flickering back to black) for as long as the controller stayed missing – total silence, no footswitch could do anything, and nothing on screen indicated why. main.py now retries the MIDI connection in-process, without tearing Core/mpv down in between attempts: standby keeps looping solidly the whole time a reconnect is pending, and a footswitch press works again the instant the controller reappears. Confirmed live: powering the M-VAVE back on mid-session was picked up on the very next retry (a few seconds later), no reboot needed.
• Both the MIDI fix above and the mpv-stderr-logging attempt (first bullet, reverted the same day) came out of investigating a real report of audio stopping entirely after about an hour of intensive real-hardware testing – see TROUBLESHOOTING.md’s new entry for the full writeup. The M-VAVE gap is the strongest confirmed lead; no direct log evidence of the Behringer itself losing power was found, since the relevant boot’s logs didn’t survive a reboot.
• Added standby video management to both setlist-admin expansions: a new “Standby video” panel shows what’s currently looping (standby.mp4’s size/last-changed time) and lets you pick any video already in the shared song library (_Songs/) to become the new one. To use a brand new file: upload it to the library first (already supported), then choose it here – reuses the existing upload/rename/ delete song-library UI rather than duplicating it, so “save it to the library, rename it, or delete it” all already work for standby candidates the same way they do for any other song. New library_ops.set_standby_video()/get_standby_info(), always writing the chosen file to the fixed standby.mp4 name regardless of the source’s own extension (mpv plays by sniffing content, not by filename, same as every other assignment in this app).

[v2026.09.27] – Set/Bank rename, real-hardware validation, Export Set, active-Set-on-reboot fix, power-loss documentation

• Renamed the library’s terminology throughout the whole project (code, tests, and docs): the top-level folder, previously called a “Show”, is now a Set (a group of Banks + songs usable in a single live performance); what was previously called a “Set” (the mid-level folder holding up to three A/B/C tracks) is now a Bank, matching the M-VAVE PD41’s own bank/group terminology. Track letters (A/B/C) are unchanged. active_show.txt is now active_set.txt; folders go from <Show Name>/Set N/ to <Set Name>/Bank N/. Both setlist-admin expansions’ REST routes moved from /api/shows and /api/shows/{show}/sets/... to /api/sets and /api/sets/{set}/banks/.... The internal Mapper/Core protocol parameter name setlist (Library.resolve(setlist, track), src/core/library.py) is deliberately not part of this rename – it’s an internal implementation detail never surfaced to a user, kept stable on purpose. Existing library USBs need their folders/file renamed by hand to match (see LIBRARY.md) before this version’s code will find anything on them.
• Real-hardware validation of expansions/setlist-admin-usb/ (iPhone USB tethering), which found and fixed several real bugs:
  • Transient umount failures (pedal-core.service’s mpv holds /media/usb open continuously) now get a bounded retry instead of failing the whole write.
  • The library USB has been observed to spontaneously unmount itself on real hardware with no corresponding log evidence anywhere – root cause not confirmed, but a real power-supply brownout was caught in the act (vcgencmd get_throttled showed under-voltage) during the same session, the strongest lead so far. usb_mount.py now self-heals: _remount() treats “already not mounted” as success instead of erroring, and new usb_mount.ensure_mounted() (used by is_first_run()) attempts a recovery mount before a read-only check ever draws a wrong conclusion from an empty directory (previously misreported as “first run,” prompting to overwrite an existing PIN).
  • Two overlapping requests (e.g. a real double-tap on a button) used to race each other’s raw umount/mount calls with no coordination, occasionally corrupting the remount state. writable_usb() is now held under a process-wide lock, serializing every write.
  • A phone disconnecting mid-upload (usb-tether-watchdog.service stopping the admin server via SIGTERM the instant the tethered interface disappears) never corrupted real data (the atomic temp-file write design held), but did leave large orphaned .part/.swaptmp files behind forever, since SIGTERM skips Python’s normal exception-cleanup path. New library_ops.cleanup_stale_temp_files() sweeps these on every server startup.
  • rename_song()/delete_song() didn’t verify a song file still existed before touching it (unlike every other function in library_ops.py) – a stale reference to a song deleted by hand directly on the USB hit a raw, unhandled FileNotFoundError instead of a clean error message.
  • Frontend: several button handlers had no error handling at all (a server error was an invisible unhandled promise rejection); the per-track upload handler never checked the response status; list reloads reset scroll to the top of the page after every save/assign/rename (root cause: the container was genuinely empty, sometimes for as long as several sequential network round-trips, forcing the browser to clamp scroll – fixed by building new content off-screen first and swapping it in in one step); and the “this worked” button flash fired only after the server responded instead of the instant the button was tapped, so a slow upload looked unresponsive for its whole duration.
• Added an Export Set view to both setlist-admin expansions: a full-screen, large-print running order for the selected Set (each track’s exact stored filename + extension, in Bank/letter order), with a supported-formats disclaimer and a “Share” button that renders the list to a PNG image and hands it to the phone’s native share sheet (desktop/unsupported-browser fallback: plain download). Closes via an on-screen ✕, Escape, or the browser back gesture.
• Fixed: in setlist-admin-usb, picking a different Set from the dropdown only changed what the app was showing/editing – it never told the pedal which Set to actually play. Only creating a new Set called the set_active_set API; switching between Sets that already existed had no way to become “the” active one at all short of deleting and recreating one. Fixed by having “Reboot now to apply” set whichever Set is currently selected as active immediately before rebooting – the one moment this app already asks the user to confirm intent, so also the right moment to commit to it. (Not yet ported to setlist-admin-wifi, which has no reboot button of its own – see expansions/setlist-admin-usb/NEXT_STEPS.md.)
• Documented (en/es TROUBLESHOOTING.md, plus systemd/README.md section 4) a consolidated answer to “is the Pi safe against a power cut, and what are the actual risk windows”: during normal band use, /, /boot/firmware, and /media/usb are all RAM-backed or ro, so there’s nothing for a power loss to corrupt; the real (brief) windows are a library edit’s /media/usb rw remount, the overlay being disabled for development, and hand-editing cmdline.txt – the last two are maintenance-only, never during a show. Also calls out that an underpowered supply, not a clean unplug, is the more likely real-world trigger, per this project’s own directly-observed under-voltage event.
• Added a shared song library (_Songs/ at the USB root) to both setlist-admin expansions, so a song only needs to be uploaded once and can be reused across any number of Sets instead of re-uploading it into every new Set. Documented as a base-project convention in LIBRARY.md (en/es) – works by hand over SSH too, not just through either app – with an explicit warning not to delete songs from it, since doing so only removes them from future picking, never from a Bank they’re already assigned to (that’s always an independent copy). library_ops.py’s new functions (list_songs/upload_song/rename_song/delete_song/ assign_song_to_slot/save_track_to_library) are identical between the two expansions. scripts/rollback.sh gained a separate --purge-library flag (distinct from --purge, which only ever touched the small PIN/credentials file) since deleting actual song files is a bigger, more deliberate action. Also fixed two real, pre-existing bugs found while building this (present since the original WiFi design, unrelated to the song library itself): library_ops.LibraryOpsError was never translated into a proper HTTP response (fell through to a generic 500 “Internal error” instead of the 400 with a helpful message it should have been), and URL path segments (Set names, now also song filenames) were never percent-decoded server-side despite the frontend percent-encoding them, so any name actually needing encoding (any space or accented character) silently failed.
• Introduced expansions/: a top-level home for optional, independently installable/removable addons to the base pedal system – moved setlist-admin (USB-tether design) into expansions/setlist-admin-usb/ as the first one, fully self-contained (its own src/, systemd/, scripts/install.sh+rollback.sh, tests/, docs), so installing or rolling it back can never collaterally affect the base project or any other expansion. See expansions/README.md for the model. The earlier WiFi-based attempt, previously only living on the explore/setlist-admin branch, was brought onto main too as a second, equally independent expansion (expansions/setlist-admin-wifi/) – still paused on its dead USB WiFi dongle blocker, not installed by default, but now visible in the same checkout instead of requiring a branch switch to see.
• Added setlist-admin (USB-tether design): a second attempt at the companion web app for managing the library USB (Sets/Banks/tracks, full CRUD) from a phone’s browser, this time reachable by plugging the phone into the Pi with a USB cable (Android USB tethering or iPhone Personal Hotspot over cable) instead of the Pi needing its own WiFi radio – see expansions/setlist-admin-usb/SPECIFICATION.md for the design and why (the earlier WiFi-based attempt is paused on a dead USB WiFi dongle, not this feature’s fault). Reuses that design’s CRUD backend and frontend UX unchanged (library_ops.py, usb_mount.py including its ntfs-3g fix, auth.py, the CRUD screens) so the two stay convergeable later. A phone is identified by its USB network driver name (rndis_host/cdc_ether/cdc_ncm for Android, ipheth for iPhone), not by IP range, so a permanently-attached Ethernet cable never spuriously starts the admin server. No WiFi credential storage, no NetworkManager profile juggling – that whole layer is gone. Applying a setlist change still requires a reboot (this project already tried and abandoned a live-reload mechanism once, see below in this same file); the app adds a “Reboot now to apply” button so that doesn’t need SSH. Not yet validated on real hardware.
• Designed and implemented setlist-admin (a companion web app for managing the library USB and the Pi’s WiFi from a phone/computer browser), then reverted it from main: real-hardware validation (SETLIST_ADMIN_SPECIFICATION.md section 8a) went cleanly through install and the watchdog’s dry-run/live stages, but then the USB WiFi dongle (Realtek rtl8192cu) turned out to be failing hardware – confirmed by testing it on a separate computer, where it didn’t enumerate as any USB device at all. Since the whole feature depends on a working WiFi adapter, further testing is blocked until there’s a known-good one. The full design, implementation, tests, and a real bug found along the way (ntfs-3g doesn’t support mount -o remount,rw – fixed to a real umount+mount cycle) are preserved on the explore/setlist-admin branch for a future attempt with an alternative design.
• Added REBUILD.md (en/es): execution-order runbook for reproducing this project on a new PC + new Raspberry Pi, written for an AI coding agent working cold, without conversation history.
• Added TROUBLESHOOTING.md (en/es): symptom-indexed reference of every real failure this project hit during development/testing.
• systemd/README.md (en/es): added a “can a human actually do this alone” review chapter (walked the guide as a non-programmer musician would), which found and fixed several real gaps – git/cloning the repo onto the Pi was never mentioned, no SSH-client guidance, no text-editor (nano) instructions for the two files that need manual edits, and the power supply requirement was only documented reactively (after the fact in TESTING.md) instead of as an upfront requirement (now also in README.md’s hardware list).
• Fixed a real EN/ES content gap in TESTING.md: the Spanish version was missing the section that closes out test 4.0 (the real-TV frame-rate follow-up), leaving a Spanish-only reader thinking it was still open when it had already been resolved.
• Fixed: booting without the library USB dropped into systemd emergency mode (no SSH, unrecoverable on a headless appliance) instead of the local standby fallback. Cause: the overlay filesystem’s default recurse=1 wraps every mount (including /media/usb) in its own overlay with no nofail, so a missing USB failed a boot-critical mount. Fixed by setting recurse=0 (root only) in cmdline.txt – see systemd/README.md section 4.
• Added LIBRARY.md (en/es): how to name library USB folders/files, and the exact filename-spacing mistake (A - x.mov vs A - x.mov) that fails completely silently – found live while testing a Bank 5 video that didn’t play.
• Project renamed from “Sequence Pedal” / “Pedal de Secuencias” to Chocolate Pi – a proper product name (playing on the M-VAVE Chocolate foot controller + Raspberry Pi actually used) instead of a literal description. Repo, badges, and docs updated to match; GitHub redirects the old repo URL automatically.

2026-09-05 – Initial public release

First open-source release. Actively used and validated against real hardware (Raspberry Pi 2, Behringer U-PHORIA UM2 USB audio interface, M-VAVE PD41 MIDI controller, library USB drive).

• Layered architecture (Adapter → Mapper → Core) so controller-specific code never leaks into playback logic.
• Adapter validated against an M-VAVE PD41 in Program Change A mode (see MAVAVE_ANALYSIS.md for the empirical mapping and its correction: 8 groups, not 32).
• Core: library resolution from a USB drive, mpv-driven video with a standby loop, a dedicated audio-only lane for standalone tracks, and audio always prioritized over video.
• Local fallback standby video for when the library USB isn’t present at boot.
• systemd auto-boot service; USB presence checked once at boot only (no live hot-swap – a reboot is required to pick up library changes).
• Read-only root filesystem (Raspberry Pi OS overlay) so the Pi can be power-cycled at any moment without filesystem corruption risk.
• MIT license, bilingual documentation (English primary, Spanish under docs/es/), GitHub Sponsors.