discstation
v0.3.1
Published
DiscStation optical-media appliance host — one cross-OS installer
Maintainers
Readme
DiscStation
DiscStation is a physical-media appliance for DVD-Video, data DVDs, audio CDs,
playback, ripping, phone uploads, and ESP32 remote control. The ESP32 remote
is optional — with none attached, the built-in web UI becomes a full
on-screen remote instead, so npm install -g discstation alone is enough to
use every mode.
Hardware
- Brain: Raspberry Pi 4/5 (or any Linux box)
- Remote (optional): ESP32 DevKit (WROOM-32) with an SSD1306 OLED, a rotary encoder, and 3 buttons — connected by USB serial or over Wi-Fi (see below) — or none at all; the web UI / mobile app's on-screen remote covers the same controls when no ESP32 is detected, and steps aside (greyed out, auto-collapsing) the moment one appears.
- Drive: ATAPI DVD writer (e.g. iHAS124) over USB
Updating the remote's firmware (over the air)
No cable needed once a remote runs this firmware: every host release ships the
matching firmware image (built by npm publish via scripts/build-firmware.sh).
When the attached remote is older, the web page and the phone app show
"Remote firmware X — Y is available" + UPDATE REMOTE. The remote downloads the
image from the host over Wi-Fi, checks its MD5, writes it to its spare firmware
slot and reboots (about 10 s; the OLED shows progress). It works whether the
remote is linked by USB or Wi-Fi, as long as it has joined your network, and it
is refused while a burn/rip/play is running.
- One cable flash first: remotes flashed before this feature can't update
themselves; the page says so. Flash once with
arduino-cli compile --upload -b esp32:esp32:esp32 -p <port> arduino/DiscStationand every later update is one click. - Safety: a corrupt or wrong-checksum image is rejected and the running firmware keeps working. There is no automatic rollback for a firmware that boots but misbehaves - recover with a cable flash. Over Wi-Fi the remote only accepts an image from the host that is already driving it.
- Manual fallback (per remote, from any computer): set
OTA_PASSWORDinsecrets.h, thenarduino-cli upload -b esp32:esp32:esp32 -p discstation-xxxx.local --protocol network --upload-field password=<pw> arduino/DiscStation. - Headroom: the image uses ~96% of the 1.31 MB app slot; if it grows past that, updates will be refused until the partition scheme is changed (cable flash).
Wi-Fi remote (optional)
The firmware also serves the same line protocol over TCP 2323, so the remote can talk to the host over Wi-Fi instead of a USB cable.
- Provisioning (no code edit): on first boot with no stored credentials
the remote starts an open
DiscStation-XXXXaccess point; join it from a phone, the captive portal (orhttp://192.168.4.1) lists nearby networks — pick yours, enter the password, done. It reconnects on every boot after that. Change networks later: hold HOME/BACK for 10 s on the home screen to wipe the credentials and reopen the portal. Power users can insteadcp arduino/<board>/secrets.h.example secrets.hand setWIFI_SSID/WIFI_PASSat build time (git-ignored). - Host side: nothing to configure. With no USB cable present the host
finds the remote by mDNS automatically (
discstation-xxxx.local). SetDISC_REMOTE_HOSTindiscstation.envto an explicit IP only if mDNS is blocked on your network, oroffto never look. A USB cable always wins when both are present. - Trust model: TCP 2323 is unauthenticated on the LAN, same as the USB link and the LAN web UI — fine for a home appliance. During the ~30 s of portal setup the password crosses an open AP; the ESP32 is 2.4 GHz only (a "connected to the router but no data" symptom usually means a 5 GHz-only / band-steering network or a wrong password).
Features
| Mode | Description |
|------|-------------|
| Burn Video DVD | YouTube URL or local file → ffmpeg 2-pass → DVD-Video disc |
| Burn Data DVD | Any files/folders → ISO/Joliet data disc (no quality loss) |
| Play | Playback via mpv (DVD-Video, Audio CD, VCD, SVCD) — both the OLED remote and the web/app on-screen remote show a live spectrum visualizer of the actual audio (Linux only for now; see docs/PLATFORM_SUPPORT.md); while a track plays the screen keeps the track/volume view (or the visualizer) up — the OLED's spinning-disc screensaver appears on its home/standby screens or after playback has been paused for 15 s, while the web/app remote shows the same spinning disc immediately in place of the visualizer any time there's no real audio data to show (paused, or a host platform that can't capture audio at all) |
| Rip | Audio CD → FLAC (MusicBrainz); DVD-Video → VIDEO_TS mirror or HandBrake MKV (TMDb naming) |
Project Structure
.
├── src/
│ ├── discstation.py # Main orchestrator, serial, web server
│ ├── discstation_burn.py # Burn pipeline (download, convert, author, burn)
│ ├── discstation_host.py # Per-OS device/path/backend abstraction
│ ├── discstation_meta.py # TMDb video metadata
│ └── static/ # Built-in web UI (index.html, app.js, style.css)
├── mobile/ # Expo (React Native) companion app
├── arduino/DiscStation/ # ESP32 DevKit remote firmware
├── scripts/setup.mjs # `discstation-setup` — cross-OS installer dispatch
├── scripts/check.sh # static checks + smoke test (run before committing)
├── docs/ # Platform support notes
├── install.sh / install-macos.sh / install-windows.ps1
├── requirements.txt / requirements-optional.txt
├── systemd/ # Linux auto-start unit
└── README.mdSetup
Install (any OS)
npm install -g discstation
discstation-setup # dispatches to the installer for your OS, then opens the UIThe host runs as a background service; the UI is the built-in web app at
http://localhost:8081. discstation-setup opens it when it finishes, and the
discstation command re-opens it any time — both also print the LAN address
(e.g. Also reachable at http://192.168.1.50:8081/ ...) so you know what to
open from a phone or another computer, or enter into the mobile app. It's a
PWA — use your browser's Install DiscStation (or the in-page
INSTALL APP button on Chromium) to get a standalone app window with a
dock/taskbar icon on macOS, Linux, and Windows.
discstation-setup --help lists the forwarded env vars. From a git clone,
npm run setup does the same thing.
Updating: npm install -g discstation alone now redeploys and restarts
the already-running service automatically (a postinstall hook copies the
updated files over and restarts it) — no need to re-run discstation-setup
after every update. Note this deploys whatever version is published, so installing an
older published release over a newer git checkout rolls the running service
back to it until you publish (or re-copy src/) again. discstation-setup itself is still what performs the
first install (system packages, venv, cert, service registration).
Support by OS:
| OS | What runs | Optical support |
|----|-----------|-----------------|
| Linux | install.sh — apt deps, venv, systemd --user service, self-signed cert | full burn / rip / play |
| macOS | install-macos.sh — Homebrew deps, venv, launchd agent, cert | burn / rip / play (audio-CD burning is best-effort; set DISC_DEVICE if detection fails) |
| Windows | install-windows.ps1 — Python + venv, self-signed cert, firewall rules, auto-start Scheduled Task | burn (ISO / data / audio CD) via IMAPI2 on Windows 10/11 and 7; DVD rip (HandBrake main-feature mode) and play (mpv) use the shared cross-platform path; full VIDEO_TS mirror rip and audio-CD rip aren't implemented on Windows yet |
Or run the platform script directly
# Linux host
./install.sh
# Arduino (ESP32 DevKit remote)
arduino-cli compile --upload -b esp32:esp32:esp32 -p /dev/ttyUSB0 arduino/DiscStation
# macOS host
./install-macos.sh
# Windows host
PowerShell -ExecutionPolicy Bypass -File .\install-windows.ps1Platform Support
Linux and macOS both run the complete optical workflow (burn, rip, play) —
macOS via xorriso / hdiutil / cd-paranoia / dvdbackup / HandBrake, with
audio-CD burning the one best-effort area. Windows burns (ISO / data / audio
CD) via IMAPI2 and plays via mpv; DVD ripping works in HandBrake main-feature
mode but not full VIDEO_TS mirror or audio-CD ripping yet. See
docs/PLATFORM_SUPPORT.md.
Web Interface
Built-in web server on port 8080 (HTTPS with self-signed cert) and a plain
HTTP mirror on 8081 for the mobile app / any browser that balks at the
self-signed cert. On startup the host prints the LAN URL to open
(>>> Open http://<ip>:8081 ... <<<).
- Upload files from any device on the LAN for data DVD burning
- Submit YouTube URLs for video DVD burning
- Dark theme, mobile-responsive, PWA (installable on phone)
- On-screen remote — opens automatically with no ESP32 attached, since it's the only control surface in that case (toggle it via the "REMOTE" tag next to the wordmark any time). Mode buttons only show what the disc in the drive can actually do — a blank CD offers BURN DATA/BURN AUDIO, a blank DVD offers BURN/BURN DATA, an already-recorded disc offers PLAY/RIP — and picking one starts it directly, no separate confirm step. Its screen mirrors the physical OLED remote: the disc title/status and offered modes at idle, and a glowing peak-hold spectrum visualizer that fills the width of the screen during playback (see Play, above) - or a spinning-disc animation in its place whenever there's no real audio data to visualize (paused, or a host platform with no audio capture). EJECT/CLOSE toggle, volume, and full playback transport including PREV/NEXT track for audio CDs. Greys out and auto-collapses the instant a physical remote is detected, so the two never fight for control — including mid-burn/rip/play: plugging the remote in hands it control without interrupting whatever's running, and its screen picks up the current status instead of starting over; unplugging it hands control back to the on-screen remote within a second or two.
Mobile App
The mobile/ Expo app (enter the host's LAN address in its settings screen)
has the same on-screen remote as the web UI, rendered inline in the main
screen rather than a popup — same "REMOTE" tag toggle, opens automatically
with no ESP32 attached, mode buttons filtered to what the disc actually
supports, and picking one starts it directly. Its screen has the same
idle title/offered-modes view, live spectrum visualizer (or spinning-disc
fallback when there's no real audio data to show) and PREV/NEXT track
controls for audio CDs as the web UI's playback screen - subscribed to the
same /events SSE stream. Same auto-collapse behavior when a physical ESP32
shows up — mid-operation and without interruption, same as the web UI — and
the same underlying /remote/button protocol.
Disc Support
- DVD-R, DVD+R (single and dual-layer)
- DVD-RW, DVD+RW
- CD-R, CD-RW (audio CD ripping)
Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| DISC_SPEED | auto | Burn speed (e.g. 4x, 8x) |
| DISC_TARGET_BYTES | 4300000000 | Target size for AUTO mode |
| DISC_CLEANUP_DAYS | 2 | Auto-cleanup old job directories |
| DISC_OUTPUT_LIMIT_BYTES | 4300000000 | Conservative DVD5 payload limit |
| DISC_DL_OUTPUT_LIMIT_BYTES | 8000000000 | Conservative DVD9 payload limit |
| DISC_DEVICE | auto | Optical drive node override |
| DISC_PORT | auto | ESP32 serial port override |
| DISCSTATION_HTTP_PORT | 8081 | Plain-HTTP port for the mobile app (0 disables) |
| DISCSTATION_DVD_RIP_MODE | mirror | mkv = HandBrake main-feature transcode instead of a full VIDEO_TS mirror |
| DISC_AUDIO_DEVICE | auto | mpv audio-output device override |
YouTube Download Configuration
The host prefers an embeddable YouTube client and small HTTP chunks to reduce current YouTube 403 failures. It falls back to the Android VR client if needed.
| Variable | Default | Description |
|----------|---------|-------------|
| YTDLP_PLAYER_CLIENTS | web_embedded,android_vr | Comma-separated clients tried in order |
| YTDLP_HTTP_CHUNK_SIZE | 1M | HTTP chunk size for media downloads |
| YTDLP_FORMAT | H.264/AAC up to 720p, then generic MP4 | yt-dlp format selector override |
| YTDLP_RETRIES | 3 | HTTP download retries per client |
| YTDLP_FRAGMENT_RETRIES | 3 | DASH/HLS fragment retries |
| YTDLP_COOKIES | unset | Netscape-format cookies file |
| YTDLP_COOKIES_FROM_BROWSER | unset | Browser source such as firefox or chrome |
| YTDLP_USER_AGENT | unset | Optional browser user-agent matching the cookies |
| YTDLP_PO_TOKEN | unset | Client/context PO token in yt-dlp format |
| YTDLP_EXTRACTOR_ARGS | unset | Additional yt-dlp extractor arguments |
Cookie files and PO tokens must stay outside the repository and service logs.
Modes (Video DVD)
| Mode | Quality | Use Case | |------|---------|----------| | AUTO | Standard ~4300kbps | Default | | BEST | Higher ~4450MB target | Quality priority | | LONG | Lower ~350kbps min | Long videos (>2.5h) | | DATA | Original quality | Files as-is on disc |
License
MIT
