Jambox

Jambox is a build project for bootable Jamulus appliance USB sticks.

The target appliance is a dedicated Debian-based Jamulus workstation for generic x86_64 UEFI laptops. It should boot from USB, use wired Ethernet and a supported USB audio interface, start JACK, launch two Jamulus clients, apply deterministic routing, and expose only the expected operator workflow.

Current Contents

• jamulus_usb_appliance_codex_spec_corrected_v2.md - implementation spec for the mutable ext4 Debian USB prototype.
• jamulus_usb_vm_test_codex_spec.md - VM and USB validation procedure.

Repository Policy

Source, scripts, docs, service units, manifests, and configuration templates belong in git.

Large generated artifacts do not belong in git. This includes bootable images, VM disks, ISO files, compressed root filesystems, package caches, generated archives, mounted root filesystems, and transient test output.

Build and Test Workflow

Primary targets:

make deps-check
make image
make inspect-image
make vm-test
make vm-test-interactive
make vm-negative-test
make usb-write DEVICE=/dev/sdb
make usb-vm-test DEVICE=/dev/sdb

The image builder creates build/jamulus-appliance.raw as a GPT/UEFI Debian appliance image with JAMBOOT, JAMROOT, and JAMCONFIG partitions. The runtime appliance starts from LightDM autologin into Openbox and launches jamulus-appliance-start automatically. VM dummy-JACK mode is only selected by explicit boot entries that add jamulus.vm_test=1 and, for automated tests, jamulus.vm_auto=1 to the guest kernel command line. Normal boot must remain the default bootloader choice.

The default image is intentionally minimum-sized rather than expanded to the target USB capacity. By default it is computed from a 512 MiB EFI partition, a 2500 MiB root partition, a 128 MiB persistent config partition, and small GPT padding, producing a roughly 3142 MiB raw image. Unused USB space after writing is expected. Override with IMAGE_SIZE_MIB=<mib> make image only after checking the target device size, or adjust ROOT_SIZE_MIB=<mib> when deliberately building a larger root filesystem.

Image builds use a reusable base-image cache at build/jambox-base.raw. make image reuses that base when the Debian suite, partition sizing, and official Jamulus package inputs are unchanged, then refreshes the appliance overlay and local Jamulus override in place. Use make base-image or FORCE_BASE=1 make image to rebuild the cached base. Use USE_BASE_CACHE=0 make image for a fully uncached rebuild.

Jamulus is installed from the pinned official GitHub amd64 release package jamulus_3.12.1_ubuntu_amd64.deb, not Debian's native jamulus package. To move to another official release, set both JAMULUS_DEB_URL and JAMULUS_DEB_SHA256 during make image. Debian package fallback is disabled unless JAMULUS_ALLOW_DEBIAN_PACKAGE=1 is deliberately set for a one-off build.

While the packaged 3.12.1 release does not contain the recently accepted startup fixes used by this appliance, make image defaults to JAMULUS_PREFER_LOCAL_BUILD=auto. In auto mode the build prefers build/jamulus-head-bookworm/jamulus from make jamulus-head while the installed official package version is 3.12.1 or older. The image still installs the official package for dependencies/provenance, but places the bookworm-built binary at /usr/local/bin/jamulus, which is preferred on PATH. Once the installed official package version is newer than JAMULUS_LOCAL_BUILD_UNTIL_VERSION (default 3.12.1), auto mode stops installing the local override. Force either path with JAMULUS_PREFER_LOCAL_BUILD=1 or JAMULUS_PREFER_LOCAL_BUILD=0.

USB writing is intentionally restricted for this run: make usb-write refuses every target except DEVICE=/dev/sdb. It logs lsblk, findmnt /dev/sdb1, and udevadm output, unmounts /dev/sdb partitions, then proceeds only if /dev/sdb exists, is a 4GB-to-8GB removable/USB device, the image fits, and no partitions remain mounted. It reselects normal boot after writing and runs ext4 checks on the written root/config partitions before declaring success.

Image construction, inspection, VM GRUB-entry selection, and USB writing require root privileges. The scripts expect passwordless sudo or direct root execution for those targets.

Appliance Runtime Notes

• Persistent appliance configuration lives under /config.
• /config/logs and /config/diag are prepared at boot and writable by the jamulus user. Run jamulus-appliance-save-diag from a TTY to collect current status, journal, and appliance logs into /config/diag/<timestamp>.
• Default channel convention is mic input 1, mono instrument input 2, stereo instrument inputs 3/4, and headphone outputs 1/2.
• JACK routing is handled by /usr/local/bin/jamulus-route-audio; qjackctl is neither installed nor used.
• Exactly two Jamulus clients are launched: jamulus-mic headless and jamulus-instrument visible.
• Local inputs are not routed directly to local outputs. Mic-client playback is explicitly disconnected from local playback.
• show-jamulus-status includes a direct-monitoring note because hardware interface monitoring is outside JACK routing control.

GitHub Setup

After creating the GitHub repository, connect this local repo with:

git remote add origin git@github.com:<owner>/<repo>.git
git push -u origin main

Use HTTPS instead if that is how the GitHub account is configured:

git remote add origin https://github.com/<owner>/<repo>.git
git push -u origin main