🦙 Wamp

Classic Winamp 2.x, reborn as a native macOS app

No Electron. No web views. No dependencies. Just Swift, AppKit, and nostalgia.

• 🎨 Real Winamp skins — load any classic .wsz skin and the entire app reskins: sprites, bitmap fonts, playlist colors, visualizer palette
• 🔊 Gapless CUE playback — one FLAC + .cue becomes individual tracks with sample-accurate, gapless transitions
• 🎚 10-band equalizer with preamp, presets, and a live frequency-response curve
• 📊 Real-time spectrum analyzer — 32-bin FFT via Accelerate, skinnable via viscolor.txt
• ⚡ Jump to File — incremental search over 10k-track playlists in under 16 ms
• 🍎 First-class macOS citizen — media keys, Control Center "Now Playing", menu bar tray, full state restore

• Classic transport — play, pause, stop, previous, next, seek
• Volume and balance sliders with real-time response
• Retro LCD time display with seven-segment digits and scrolling track title
• Double Size mode (⌘⇧D) — the whole window scales 2×, pixel-perfect
• Always-on-top pin (⌘⇧T) and a minimize-to-tray menu

Wamp parses the original Winamp 2.x skin format — a .wsz archive of bitmap sprites and INI files — and renders it faithfully:

• main.bmp, cbuttons.bmp, eqmain.bmp, pledit.bmp sprite sheets
• Bitmap fonts from text.bmp / nums.bmp for the LCD and titles
• Playlist colors from pledit.txt, visualizer palette from viscolor.txt
• Interactive mini-transport baked into the skinned playlist corner — just like 1999
• Hardened loader: corrupt archive entries are skipped, decompression is capped against zip bombs, malformed region.txt fails soft
• Skins load atomically off the main thread; Unload Skin returns to the built-in look instantly

A few classics to try live in skins/: base-2.91, Blue Plasma, OS8 AMP — Aquamarine, Radar Amp.

• Drag & drop files, folders, .m3u/.m3u8 and .cue straight from Finder
• Multi-select like a real Mac app — Shift-click ranges, Cmd-click toggles, ⌘A, Backspace removes
• Instant search box + Jump to File (⌘J) with prefix → word-boundary → substring ranking
• Shuffle and repeat (off / track / playlist) with auto-advance
• Import from Music Library… — pulls local tracks and playlists from Music.app (via ITLibrary, with an iTunes Music Library.xml fallback); streaming-only and missing files are skipped and counted
• Skinned scrollbar, skin-correct row colors, live track-count/duration footer

Drop a .cue next to a FLAC (or open a FLAC with an embedded CUESHEET Vorbis comment) and the album splits into individual virtual tracks:

• Gapless transitions between consecutive tracks via chained scheduleSegment calls
• External .cue wins over embedded CUESHEET
• Encoding detection: UTF-8, Shift-JIS, CP-1251, CP-1252
• Absolute Windows/Unix FILE paths resolve by basename — same behavior as foobar2000
• CRLF files, hostile timecodes, and malformed input all fail soft, never crash

Plus hardware media keys (play/pause, next, previous) and the macOS Now Playing widget in Control Center.

Requirements: macOS 26.3+, Xcode 26+

git clone https://github.com/wishval/wamp.git
cd wamp

# Build
xcodebuild -project Wamp.xcodeproj -scheme Wamp -configuration Debug build

# Or just open in Xcode and hit ⌘R
open Wamp.xcodeproj

Run the tests (they cover the models, CUE parsing, and persistence):

xcodebuild -project Wamp.xcodeproj -scheme Wamp -destination 'platform=macOS' test

AppDelegate  (nib-less bootstrap, owns the singletons)
├── AudioEngine        PlayerNode → 10-band EQ → Mixer → Output, FFT tap
├── PlaylistManager    track list, shuffle, repeat, auto-advance
├── StateManager       debounced JSON persistence, restores on launch
├── SkinManager        atomic .wsz load → publishes a SkinProvider
│   └── SkinModel      sprites, regions, colors, bitmap fonts
├── CueSheet           parser + encoding detection + FLAC extractor
│   └── CueResolver    expands a cue into virtual Tracks
└── MainWindow         275px-wide borderless stack
    ├── MainPlayerView     LCD, transport, sliders, spectrum
    ├── EqualizerView      10 bands + presets + response curve
    └── PlaylistView       drag-drop, search, keyboard nav

Views bind to models through Combine — @Published fires, views redraw. No delegates, no notification spaghetti.

Wamp is a local player. It will not stream Spotify or Apple Music catalog tracks — both route audio through a system-managed graph that bypasses our DSP, so the EQ and spectrum analyzer would be lying to you. Details in docs/non-goals.md.