classicOS is custom firmware for iPod based on Rockbox.
A fresh interface inspired by modern iOS.
Tested on iPod Video (5G). Support for other models is unverified.
Build · Install · Development · License
classicOS is currently tested on the iPod Video (5G). Other iPod models are untested, and the build commands below target the iPod Video.
The current build and deployment workflow is developed on macOS.
| Dependency | Used for |
|---|---|
| Bun | Package management, UI compilation, and project commands |
| SDL2 | Desktop simulator |
| Rust stable | Simulator runtime |
Rust nightly-2026-07-01 with rust-src |
iPod runtime |
| Rockbox ARM toolchain | Native firmware; place in ~/rbdev/bin or on PATH |
From the repository root:
bun install --frozen-lockfilebun run simThis builds and launches the simulator. Add music to out/sim/simdisk/.
| Key | Action |
|---|---|
| Up / Down | Move focus with the wheel |
| Enter | Select |
| Esc | Menu / Back |
| Space | Play / Pause |
| Left / Right | Previous / Next track |
| H | Toggle hold |
| F5 | Save a screenshot |
To build without launching, use bun run build:sim.
bun run build:ipodThe firmware image is written to out/ipod/rockbox.ipod.
Follow Rockbox’s installation guide to install the bootloader for your iPod model. Once installed, mount your iPod in disk mode and pass its volume path:
bun run deploy /Volumes/CLASSICOSReplace /Volumes/CLASSICOS with your iPod's mount point. Deployment copies
the firmware, matching codecs, shell assets, and library configuration. It
preserves the first firmware/codecs backup, verifies the firmware copy, and
ejects the volume. The bootloader and original firmware remain unchanged.
Run the model, renderer, and runtime checks:
bun run typecheck
bun run testPass Make variables through the build commands:
bun run build:ipod PJS_HUD=1
bun run build:sim PJS_APP=ipod-video-demo| Directory | Responsibility |
|---|---|
shell/ |
Screens, model, icons |
runtime/ |
UI engine, compiler, and framework powered by PocketJS |
host/ |
Boot, input, playback/library services, and native integration |
system/ |
Kernel, drivers, filesystem, codecs, and playback |
scripts/ |
Build, simulate, deploy |
tests/ |
Model and renderer checks |
docs/ |
Architecture and development documentation |
out/ |
Generated build output |
The shell runs on the runtime, while the host connects it to the system's hardware and music services. Everything builds into one firmware image.
The build script creates ignored links under system/apps/classicos/ so
system build rules can find host sources. Edit the maintained files in
host/. Build output and simulator data live in out/.
See the contribution guide for issues, pull requests, validation, and AI-assisted contributions. Hardware test reports for other iPod models are welcome.
classicOS builds on Rockbox and PocketJS, includes code adapted from CrazyPod, and uses the Inter typeface (OFL) and Framework7 Icons (MIT).
classicOS is an independent project and is not affiliated with Apple Inc. iPod is a trademark of Apple Inc.
New classicOS code is licensed under GPL-2.0-or-later. The combined firmware is distributed under the applicable GNU GPL terms.
PocketJS-derived runtime code retains its MIT license; see runtime/LICENSE. Existing third-party components retain their original licenses and copyright notices.