NullPlayer User Guide

A faithful recreation of Winamp 2.x for macOS with Plex/Jellyfin/Subsonic integration, ProjectM visualizations, and casting support.

System Requirements

• •macOS 14.0 (Sonoma) or later
• •Internet connection (for streaming and skin downloads)

Core Features

Windows

Window Docking

Windows automatically snap together when dragged near each other:

• •Edge-to-edge snapping
• •Screen edge snapping
• •Group movement (docked windows move together)
• •Group minimize (attached windows minimize together)
• •Snap to Default (context menu) resets all windows

Main Window Elements

Sliders

• •Position Bar: Seek through track
• •Volume Slider: Adjust playback volume (0-100%)
• •Balance Slider: Pan audio left/right

Transport Buttons

Previous, Play, Pause, Stop, Next, Eject (open file dialog)

Toggle Buttons

• •Shuffle: Random playback order
• •Repeat: Loop playlist
• •EQ: Show/hide Equalizer
• •PL: Show/hide Playlist

Modern UI adds: 2X (Double Size), HT (Hide Title Bars), CA (Cast), pM (ProjectM), SP (Spectrum), LB (Library)

Media Sources

Plex Integration

• •Browse music, movies, and TV shows
• •Album artwork and metadata
• •Radio features (Track/Artist/Album/Genre/Decade/Rating/Hits/Deep Cuts)
• •Automatic scrobbling (90% or end, min 30s)
• •Video playback with casting

Jellyfin Integration

• •Browse music and video libraries
• •Multiple library support
• •Rating scale: 0-100% (0-10 internal)
• •Scrobbling (50% or 4 minutes for audio, 90% for video)

Navidrome/Subsonic

• •Browse artists, albums, playlists
• •Token authentication
• •Scrobbling (50% or 4 minutes)
• •Casting support via proxy

Internet Radio

• •Shoutcast/Icecast streaming
• •ICY metadata display
• •Auto-reconnect on disconnect
• •Station management
• •Casting to Sonos

Local Files

Drag & drop or use File menu. Supports: MP3, M4A, AAC, WAV, AIFF, FLAC, OGG, ALAC

Output Devices & Casting

Sonos

• •Multi-room casting
• •Group management while casting
• •Local file streaming via embedded server
• •Network stream proxying for Subsonic/Jellyfin

Chromecast

• •Audio and video casting
• •Position synchronization
• •Buffering state handling

DLNA

• •UPnP device discovery
• •Video casting to TVs

AirPlay

• •Native macOS AirPlay support
• •Auto-detected output devices

Audio Features

Equalizer

• •10-band graphic EQ (-12dB to +12dB per band)
• •Preamp control
• •Presets (Flat, i'm old, i'm young, Rock, Pop, Jazz, Classical, etc.)
• •Auto EQ (genre-based automatic presets)
• •Anti-clipping limiter

Playback Options

• •Gapless Playback: Seamless track transitions (local files)
• •Sweet Fades: Crossfade between tracks (1-10s duration)
• •Volume Normalization: Consistent loudness (-14dB target)
• •Remember State on Quit: Restore session on launch

Spectrum Modes

• •Accurate: True signal levels (40dB range)
• •Adaptive: Global adaptive normalization
• •Dynamic: Per-region normalization (bass/mid/treble)

Visualizations

Main Window GPU Modes

Spectrum, Fire, Enhanced, Ultra, JWST, Lightning, Matrix (double-click to cycle)

Album Art Visualizer

30 effects transforming album artwork based on audio

ProjectM/MilkDrop

100+ bundled presets, OpenGL rendering, fullscreen support

Spectrum Analyzer Window

55 bars, 7 quality modes (Winamp/Enhanced/Ultra/Fire/JWST/Lightning/Matrix)

Skins

Loading Skins

• •Skins > Load Skin... to open .wsz file
• •Place in ~/Library/Application Support/NullPlayer/Skins/ for auto-discovery
• •Bundled skins: Silver (default), Classic, Dark, Light

Modern UI Mode

• •Options > Use Modern UI to enable modern skin engine
• •Requires restart to switch modes
• •Modern skins use skin.json format
• •Bundled modern skins: NeonWave (default), Skulls

Double Size Mode (Modern UI)

• •Toggle via 2X button or context menu
• •Scales all windows by 2x
• •Persists across restarts

Hide Title Bars (Modern UI)

• •Toggle via context menu
• •Hides skinned title bars on all windows
• •Preserves border line

Keyboard Shortcuts

Playback

• •Space: Play/Pause
• •V: Stop
• •B: Next track
• •Z: Previous track
• •←/→: Seek backward/forward 5s
• •↑/↓: Volume up/down

Windows

• •Cmd+L: Show/hide Playlist
• •Cmd+G: Show/hide Equalizer
• •Cmd+S: Show/hide Spectrum Analyzer (modern UI) or Library Browser (classic UI)
• •Cmd+K: Show/hide ProjectM
• •Cmd+J: Jump to current track in playlist

Playlist

• •Enter: Play selected track
• •Delete: Remove selected tracks
• •Cmd+A: Select all

Library Browser

• •Enter: Play Now (insert and play)
• •Shift+Enter: Play Next (insert after current)
• •Option+Enter: Add to Queue (append)
• •Cmd+F: Focus search field
• •Escape: Clear search

Data Storage

Additional Documentation

For comprehensive documentation, see:

• •features-reference.md - Detailed window/feature documentation
• •keyboard-shortcuts.md - Complete keyboard shortcut reference

Quick Tips

• •Drag & drop files/folders onto the player to add them
• •Right-click anywhere for the context menu
• •Double-click title bars for shade mode
• •Shift+Click for multi-select in playlist/browser
• •Cmd+J to jump to currently playing track
• •Windows dock automatically when dragged near each other
• •Modern UI has Double Size (2X) and Hide Title Bars (HT) modes