Skip to content
Back to search

nullplayer

nullPlayer is a free open source macOS media player with some unique features

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ad-repo/nullplayer with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ad-repo/nullplayer'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ad-repo--nullplayer/badge.svg)](/listings/ad-repo--nullplayer)

HTML

<a href="/listings/ad-repo--nullplayer"><img src="/api/listings/ad-repo--nullplayer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download the latest DMG:

https://github.com/ad-repo/nullplayer/releases/latest/download/NullPlayer.dmg

Requires macOS 14 Sonoma or newer.

NullPlayer is signed with an Apple Developer ID and notarized by Apple, so it passes Gatekeeper's developer and notarization checks. macOS may still ask you to confirm the first launch.

1. Open `NullPlayer.dmg`. 2. Drag `NullPlayer.app` to Applications. 3. Open NullPlayer from Applications.

See [docs/download.md](docs/download.md) for the same install steps in a short download-only page.

Install with Homebrew

[Homebrew](https://brew.sh/) is a free package manager for macOS. Installing with it makes updates a single command.

**New to Homebrew? Here's the whole thing, start to finish:**

1. Open **Terminal** — press `Cmd + Space`, type `Terminal`, and press Return. 2. Install Homebrew by pasting this line and pressing Return. It asks for your Mac login password (the cursor stays still while you type — that's normal) and takes a few minutes:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Already have Homebrew? Skip this step. 3. Add Homebrew to your shell so the `brew` command is found. The installer finishes by printing a **Next steps** section — run the two commands it lists. On Apple Silicon Macs (M1/M2/M3/M4) they are:

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
   eval "$(/opt/homebrew/bin/brew shellenv)"

On older Intel Macs, replace `/opt/homebrew` with `/usr/local`. If `brew` already worked before you started, skip this step. 4. Add the NullPlayer tap (one-time configuration):

   brew tap ad-repo/nullplayer

5. Install NullPlayer:

   brew install --cask ad-repo/nullplayer/nullplayer

6. Open NullPlayer from your Applications folder or Launchpad.

**Updating to a new release:**

brew update
brew upgrade --cask ad-repo/nullplayer/nullplayer

<details> <summary>Homebrew power-user notes</summary>

Verify the tap is serving the latest version:

brew livecheck --cask ad-repo/nullplayer/nullplayer

`brew uninstall --cask --zap nullplayer` removes app data under `~/Library/Application Support/NullPlayer` and the app's preferences/caches, but **does not** remove Keychain entries for Plex/Subsonic/Jellyfin/Emby tokens. To clear those:

security delete-generic-password -s com.nullplayer.app

</details>

Optional command-line launcher

If you want to use NullPlayer as a scriptable command in terminal workflows or automation pipelines, the DMG includes:

- `nullplayer` — launcher wrapper - `Install NullPlayer CLI.command` — one-click installer for `/usr/local/bin/nullplayer`

Install flow:

bash "/Volumes/NullPlayer/Install NullPlayer CLI.command"
nullplayer --cli --help

The launcher looks for:

- `/Applications/NullPlayer.app` - `~/Applications/NullPlayer.app`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 768 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">NullPlayer. Your media. Your backend. Your home devices. Your UI.</h2>
  2. https://github.com/user-attachments/assets/4f53dbd9-cfd2-4ca1-87d5-96d39e224a92
  3. https://github.com/user-attachments/assets/46c1192c-cc57-4531-89b2-dbbb5e253a63
  4. <p align="center">
  5. <img width="640" height="360" alt="audion_rain_10mb" src="https://github.com/user-attachments/assets/9926e024-6aba-4934-afa3-499bda3e9bc2" />
  6. <img width="500" alt="nullplayer-skins-all" src="https://github.com/user-attachments/assets/be764bfb-c284-4787-ada7-8b532253b4e9" />
  7. </p>
  8. ## **If you enjoy NullPlayer please ⭐ STAR ⭐ the project on GitHub**
  9. ## Features
  10. NullPlayer is 100% open source and built as a clean-room effort; no Winamp, WACUP, or Windows Media Player source code has been copied or viewed
  11. Nullplayer is the **first macOS and only open-source engine capable of rendering Winamp ClassicPro and Winamp 5 (`.wal`) skins**, letting you run all Winamp skin types on macOS while enjoying modern media ecosystem support
  12. NullPlayer is also the **first macOS and only open-source engine capable of rendering Windows Media Player (`.wmz`) skins**:from WMP 7, 7.1, XP (8), 9, 10, 11 and 12. It supports their views, JScript, EQ, SRS and visualizer controls, all driving NullPlayer's playback engine. Skin scripts run sandboxed in an isolated JavaScriptCore context with no ActiveX, registry, shell, DLL, plug-in or HTML access.
  13. NullPlayer is also the **first macOS and only open-source engine capable of rendering Sonique (`.sgf`) skins**: Sonique 1.x skins in all three of Sonique's modes (navigator, mid and small), with the navigator's visual mode screen and equalizer drawer, checked against real Sonique 1.96 skin by skin.
  14. NullPlayer is not affiliated with, endorsed by, or connected to Winamp, Nullsoft, Microsoft, Winamp Group SA, Llama Group, Radionomy Group, Jamendo, Hotmix, Bridger, SHOUTcast, Sonos, Plex, WACUP, Emby, Jellyfin, Google, Panic or anyone else
  15. No Winamp, Windows Media Player or Sonique skins or Audion faces are distributed with the project, apart from the default `.wal` skin, [iTunes Miniplayer](https://github.com/spacecowgoesmoo/Old-iTunes-Miniplayer), shipped with its author's permission
  16. ### General Features
  17. - Library browser for Plex, Jellyfin, Emby, Navidrome/Subsonic, YouTube and local files, with List, Cover Flow and Tiles views; right-click a track for **Go to Artist** or **Go to Album**
  18. - 21-band EQ (Original/Original-Metal) and 10-band EQ (Classic, Modern)
  19. - [EQ profiles](#quick-start-eq-profiles) — saved 31-band EQ curves with separate left and right channels and a parametric stage, assigned to tracks, albums or artists and applied whenever they play
  20. - [EQ Cast](#quick-start-eq-cast) — casts to Sonos and Chromecast with the track's EQ profile applied, by rendering the track with its profile first
  21. - Gapless + Sweet Fades (configurable crossfade), volume normalization, play speed (0.25×–4×), and Reference Tuning (432/440 Hz/custom)
  22. - SRS inspired audio enhancements: WOW stereo widening and TruBass low-frequency enhancement plus a Headphones profile for TruBass
  23. - Stream Ripper — rip and import stream URLs to FLAC, MP3, or MP4 with metadata, cover art, and `.cue` sheets (requires `yt-dlp` + `ffmpeg`)
  24. - Intelligent radio mix generation for all sources
  25. - Track Radio for the local library — right-click a track and choose **Start Track Radio** to queue tracks like it, scored from its tags (artist, genre, year, tempo, key, grouping) with no audio analysis
  26. - Cast to Sonos (multi-room), Chromecast, DLNA, and AirPlay — local files, server streams, and radio
  27. - Cast Visualization — send the running visualization and the music live to a Chromecast or DLNA TV at 720p, 1080p or 4K, 30 or 60 fps (macOS 14.2+)
  28. - Sonos content filtering for unsupported lossless formats and improved playlist support
  29. - Sonos Rooms window for picking cast rooms and setting each room's volume individually
  30. - Drag-and-drop, macOS Now Playing integration, and [Discord Music Presence](https://github.com/ungive/discord-music-presence)
  31. - Headless CLI for querying libraries, playback, and routing to local outputs or cast devices, full color terminal cover art rendering
  32. ### Backend Support
  33. - Server integration for Plex, Jellyfin, Emby, YouTube and Navidrome/Subsonic with scrobbling
  34. - Local media library with metadata parsing, editing, and management
  35. - Mixed playlists — combine tracks or video from any sources (local, Plex, Jellyfin, Emby, Subsonic/Navidrome, radio, movies, YouTube) into a single playlist
  36. - Internet radio (Shoutcast/Icecast) with live metadata and auto-reconnect
  37. - YouTube as a library source — search and subscribe to channels, browse uploads, download audio (FLAC/ALAC/MP3/AAC/Opus) or video up to 4K ad-free (requires `yt-dlp` + `ffmpeg`)
  38. ### Skin System Support
  39. - Classic mode: full `.wsz` Winamp 2.X skin support with window snapping and docking; scroll over the main window to step the volume 5%, or over the balance slider to step the balance 10%
  40. - Winamp Modern (`.wal`) skin support (Winamp 5.X and ClassicPro); the ClassicPro Windows plug-in engine is extracted from the user-supplied installer and runs natively on macOS
  41. - Original mode: JSON-based skin system with color theming, custom assets, procedural backgrounds, and bloom effects and full skinning documentation for authors
  42. - Original-Metal mode: seven brushed-metal finishes with backlit LCD displays
  43. - Windows Media Player mode: the only Mac player that runs WMP 7–12 `.wmz` skins, loaded through a bounded, isolated engine with a sandboxed JScript runtime; import, select, remove, and switch views from **Skins > Media Player**, or fall back to a built-in unskinned player
  44. - Panic Audion faces: the 2021 face archive, drawn by a port of Panic's own FaceKit viewer and checked against it face by face; every face button drives NullPlayer, and its windows take their colours from the face. Install and select from **Skins > Audion Faces**
  45. - Sonique 1.x `.sgf` skins: all three modes (navigator, mid and small) drawn from the skin, with the navigator's visual mode screen and equalizer drawer; checked against real Sonique 1.96 skin by skin. Install and select from **Skins > Sonique**
  46. - Live skin switching. Cycle through Classic, Modern, Original, Original-Metal, Windows Media Player skins, Audion faces and Sonique skins with no restart or interuption in playback
  47. - Full development harness for debugging and reverse engineering Winamp 5, ClassicPro, and Windows Media Player skins, and for checking Audion faces against Panic's FaceKit, and Sonique skins against real Sonique
  48. - Native nullplayer windows are themed to the host skin
  49. ### Media Support
  50. - Audio codecs: MP3, FLAC, AAC, WAV, AIFF, ALAC, OGG, Opus (in `.m4a`)
  51. - Video codecs: MKV, MP4, MOV, AVI, WebM, HEVC (VLCKit/libVLC)
  52. - `.cue` sheet support - virtual split cue/flac into ephemeral playlist items or optionally split to multiple tagged files on import
  53. ### Unique Nullplayer Windows
  54. - Visualizations - ProjectM (100 presets included), Geiss, Tripex, AVS (with preset editor), Goom, Corona and Smear ports, Art window with album art effects, and spectrum analyzer
  55. - Audio Analysis window — oscilloscope, stereo peak/RMS meters, scrolling Metal spectrogram
  56. - Cava spectrum analyzer — bar spectrum with mono/stereo modes, gradient presets, and configurable smoothing
  57. - PeppyMeter — skinnable analog VU meter with 25 templates and auto-switch mode
  58. - Flow network monitor — live throughput graph with selectable interface
  59. - Equalizer Studio — editor for EQ profiles: 31 faders and a 4-band parametric strip per channel, a spectrum analyser per channel, live preview ([quick start](#quick-start-eq-profiles))
  60. - Sonos Rooms — resizable room mixer with a checkbox and independent volume slider per room (usable before and during a cast)
  61. - Compact Mode — menu-bar-only app with embedded mini player (Classic, Original, and Original-Metal)
  62. ### Visualization Support
  63. NullPlayer's visualizations span its windows, from the in-skin main-window display to full-screen engines. All visualization choices persist across launches.:
  64. - **Main Window** — 12 inline modes on the player's own display: Off, Classic 19-band, Cava bar, Enhanced, Ultra, Fire, JWST (deep-space), Lightning, Matrix, Snow, EKG, and the vis_classic analyzer port; cycle with a double-click or pick from **Visuals > Main Window > Mode**
  65. - **Spectrum Window** — dedicated 84-bar analyzer with 9 modes (Winamp/vis_classic/Enhanced/Ultra/Fire/JWST/Lightning/Matrix/Snow) and skin-matched styles
  66. - **Cava** — a cava-style bar spectrum (clean-room vDSP port) in its own window and inline in the main window, with mono/stereo modes, gradient color presets, and configurable bars, smoothing, and bass tilt
  67. - **ProjectM/MilkDrop** — 100+ bundled presets with OpenGL rendering and fullscreen support
  68. - **Geiss** — port of Ryan Geiss's classic visualization with runtime controls (sensitivity, gamma, beat detection, palettes, auto-switch)
  69. - **Tripex** — Winamp-era 3D visualization port
  70. - **AVS (Advanced Visualization Studio)** — Winamp's AVS engine (libavs) with 35 bundled presets, your own `.avs` preset folder, auto-cycle, and a preset editor (**Edit Preset…**) that changes the running preset live: add, remove, reorder and toggle effects, edit every parameter and EEL code, save as `.avs` or export JSON
  71. - **Goom** — the classic XMMS-era Goom visualizer (Goom2k26 core): fifteen zoom effects it picks from the music, or you pick from the right-click menu (→ / ← / R step) and keep with **Hold Effect**. Five are new to NullPlayer: Spiral, Vortex, Flower, Heart (pink heart scopes in heart-shaped ripples) and Pentagram (a star in a circle, in star-shaped ripples)
  72. - **Corona** — the Sonique-era visualizer: particle flames that swirl and leap on the beat over a rippling reflection, in 31 palettes (the presets) plus a brighter **Blaze** mode
  73. - **Smear** — the Sonique visualizer in the style of G-Force: the picture flows through 60 scripted move maps (the presets) while scripted colour schemes, waveforms and particles come and go
  74. - **Cast Visualization** — right-click the Visualizations window → **Cast Visualization** to play ProjectM, Geiss, Tripex, AVS or Goom on a Chromecast or DLNA TV, with the music; the window keeps its menu for switching engines and presets while the TV plays
  75. - **Album Art Visualizer** — 30 audio-reactive effects (Core Image) transforming album art in the Art window
  76. - **Winamp Modern (`.wal`) skins** — the skin draws its own in-skin visualizations, including workscope/oscilloscope analyzers and custom engine visuals (e.g. the MMD3 and ClassicPro beat visualizers)
  77. - **Windows Media Player (`.wmz`) skins** — a skin's `<EFFECTS>` area renders native Spikes, Bars, Ambience, Cava, vis_classic, ProjectM, Geiss, Tripex, or AVS visuals inside the rectangle the skin draws for them
  78. - **Audio Analysis** — Friture-style multi-pane window: Scope, Levels (peak/RMS), Spectrogram, Octave, Pitch, and Delay
  79. - **PeppyMeter** — skinnable analog VU meter (needle/bar) with 25 templates and a random auto-switch mode
  80. - **Flow** — live network throughput graph with selectable interface
  81. ### Agentic Development Support
  82. NullPlayer is built to be worked on by coding agents as well as people. The repo ships the
  83. context an agent needs instead of making it rediscover the codebase every session.
  84. - **Subsystem skills** in [`skills/`](skills/) — maintained technical documentation, one owner per subsystem: audio and EQ, each skin engine, every media-server integration, casting, each visualizer, the local library, CLI, and testing. The clean-room skin engines add per-skin dossiers (what each problem skin taught the engine and what was ruled out), a canonical probe/harness reference, and a `skin-subsystem-blueprint` for adding a new skin family.
  85. - **Invocable skills, not just docs** — `/wal-skin-report <skin.wal>` produces a full compatibility report for a Winamp 5 skin; `skin-screenshots` drives the live app to capture one main-window frame per skin across every skin system and assembles a slideshow GIF.
  86. - **Automation-first surfaces** — a headless `--cli` mode for querying libraries, resolving sources, starting playback, and routing to Sonos / Chromecast / DLNA, plus a `--ui-testing`launch mode and accessibility identifiers so the UI can be driven programmatically.
  87. - **Scripted workflows** — one-command bootstrap, build-and-run, DMG/MAS packaging, third-partynotice generation and validation, `.wal` and `.wmz` corpus render sweeps and census (with a corpus exclusion list and baseline diffing), and backlog validation, so an agent verifies its work the same way a maintainer does.
  88. - **Live-defect workflow** — a `live-ui-testing` process skill for bugs that only show on screen: instrument first, drive the running app with AppleScript and synthesized input, and measure what is actually drawn; every subsystem skill routes its *Debugging a live defect* section there.
  89. - **Unit tests** under [`Tests/`](Tests/), with a documented testing philosophy (`skills/testing`) that explicitly forbids weakening tests changing app code just to make them pass.
  90. - **Explicit architectural guardrails** encoded where an agent will read them: skin engines must not cross-import, Winamp Modern (`.wal`) and Windows Media Player (`.wmz`) work must never alter Classic or Original behavior, the sprite-origin and `Data`-slicing gotchas are stated up front.
  91. - **App control: agents drive the real app** — the [`app-control`](skills/app-control/SKILL.md) skill lets an agent launch, configure, drive, screenshot, and measure the running debug build across every skin family (Classic, Original, Original-Metal, `.wal`, `.wmz`, Audion faces, Sonique `.sgf`):
  92. - **Token friendly agent routing** A routing table picks the cheapest way to answer a question, from a headless probe to handing the user a preloaded interactive session. Canonical test media and launch recipes included.
  93. ## Installation
  94. Download the latest DMG:
  95. https://github.com/ad-repo/nullplayer/releases/latest/download/NullPlayer.dmg
  96. Requires macOS 14 Sonoma or newer.
  97. NullPlayer is signed with an Apple Developer ID and notarized by Apple, so it passes Gatekeeper's developer and notarization checks. macOS may still ask you to confirm the first launch.
  98. 1. Open `NullPlayer.dmg`.
  99. 2. Drag `NullPlayer.app` to Applications.
  100. 3. Open NullPlayer from Applications.
  101. See [docs/download.md](docs/download.md) for the same install steps in a short download-only page.
  102. ### Install with Homebrew
  103. [Homebrew](https://brew.sh/) is a free package manager for macOS. Installing with it makes updates a single command.
  104. **New to Homebrew? Here's the whole thing, start to finish:**
  105. 1. Open **Terminal** — press `Cmd + Space`, type `Terminal`, and press Return.
  106. 2. Install Homebrew by pasting this line and pressing Return. It asks for your Mac login password (the cursor stays still while you type — that's normal) and takes a few minutes:
  107. ```bash
  108. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  109. ```
  110. Already have Homebrew? Skip this step.
  111. 3. Add Homebrew to your shell so the `brew` command is found. The installer finishes by printing a **Next steps** section — run the two commands it lists. On Apple Silicon Macs (M1/M2/M3/M4) they are:
  112. ```bash
  113. echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
  114. eval "$(/opt/homebrew/bin/brew shellenv)"
  115. ```
  116. On older Intel Macs, replace `/opt/homebrew` with `/usr/local`. If `brew` already worked before you started, skip this step.
  117. 4. Add the NullPlayer tap (one-time configuration):
  118. ```bash
  119. brew tap ad-repo/nullplayer
  120. ```
  121. 5. Install NullPlayer:
  122. ```bash
  123. brew install --cask ad-repo/nullplayer/nullplayer
  124. ```
  125. 6. Open NullPlayer from your Applications folder or Launchpad.
  126. **Updating to a new release:**
  127. ```bash
  128. brew update
  129. brew upgrade --cask ad-repo/nullplayer/nullplayer
  130. ```
  131. <details>
  132. <summary>Homebrew power-user notes</summary>
  133. Verify the tap is serving the latest version:
  134. ```bash
  135. brew livecheck --cask ad-repo/nullplayer/nullplayer
  136. ```
  137. `brew uninstall --cask --zap nullplayer` removes app data under `~/Library/Application Support/NullPlayer` and the app's preferences/caches, but **does not** remove Keychain entries for Plex/Subsonic/Jellyfin/Emby tokens. To clear those:
  138. ```bash
  139. security delete-generic-password -s com.nullplayer.app
  140. ```
  141. </details>
  142. ### Optional command-line launcher
  143. If you want to use NullPlayer as a scriptable command in terminal workflows or automation pipelines, the DMG includes:
  144. - `nullplayer` — launcher wrapper
  145. - `Install NullPlayer CLI.command` — one-click installer for `/usr/local/bin/nullplayer`
  146. Install flow:
  147. ```bash
  148. bash "/Volumes/NullPlayer/Install NullPlayer CLI.command"
  149. nullplayer --cli --help
  150. ```
  151. The launcher looks for:
  152. - `/Applications/NullPlayer.app`
  153. - `~/Applications/NullPlayer.app`
  154. ## Requirements
  155. - macOS 14.0 (Sonoma) or later
  156. ### Optional command-line tools
  157. The **YouTube source** and **Stream Ripper** features download and transcode media by shelling out to two command-line tools that are **not bundled** — install them via [Homebrew](https://brew.sh):
  158. ```bash
  159. brew install yt-dlp ffmpeg
  160. ```
  161. - **yt-dlp** — lists channel uploads and downloads audio/video. Required for any YouTube or Stream Ripper download.
  162. - **ffmpeg** — merges YouTube's separate video + audio streams into an MP4 and transcodes audio to FLAC/MP3. Without it, video downloads fail with `Postprocessing: ffmpeg not found` and audio downloads can't be converted.
  163. NullPlayer looks for both in the standard Homebrew/MacPorts locations (`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/usr/bin`). Keep them current with `brew upgrade yt-dlp ffmpeg` — an outdated `yt-dlp` may fail to list or download videos as YouTube changes.
  164. ## Building from Source
  165. Requires Xcode 15.0+ with Command Line Tools and Swift 5.9+.
  166. ```bash
  167. # Clone the repository
  168. git clone https://github.com/ad-repo/nullplayer.git
  169. cd nullplayer
  170. # Download required frameworks
  171. ./scripts/bootstrap.sh
  172. # Build and run
  173. ./scripts/kill_build_run.sh
  174. ```
  175. The bootstrap script downloads VLCKit and libprojectM from GitHub Releases with checksum verification.
  176. To open in Xcode:
  177. ```bash
  178. open Package.swift
  179. ```
  180. ## Dependencies
  181. | Library | Purpose |
  182. |---------|---------|
  183. | [ZIPFoundation](https://github.com/weichsel/ZIPFoundation) | .wsz / .wmz skin and Audion face `.zip` extraction |
  184. | [SQLite.swift](https://github.com/stephencelis/SQLite.swift) | Media library storage |
  185. | [AudioStreaming](https://github.com/dimitris-c/AudioStreaming) | HTTP audio streaming for Plex |
  186. | [FlyingFox](https://github.com/swhitty/FlyingFox) | Embedded HTTP server for local file casting |
  187. | [libprojectM](https://github.com/projectM-visualizer/projectm) | ProjectM visualizations |
  188. ## EQ Profiles and EQ Cast
  189. ### How it works
  190. The Equalizer window applies one curve to everything you play. An **EQ profile** is a separate,
  191. named curve that belongs to specific music: you assign it to a track, album or artist, and it is
  192. applied whenever that music plays.
  193. - A profile is a 31-band curve (ISO ⅓-octave, 20 Hz–20 kHz) plus a 4-band parametric stage
  194. (high-pass filter, LF, LMF, HMF, HF) and a preamp, with the left and right channels set
  195. separately.
  196. - Profiles are made and edited in **Windows ▸ Equalizer Studio**.
  197. - When a track plays, its own profile is used; if it has none, its album's; if the album has
  198. none, its artist's.
  199. - A profile runs before the Equalizer window. The two are independent: neither changes the other.
  200. - Profiles apply to local files, media-server tracks, radio stations and downloaded YouTube audio.
  201. They do not apply to video.
  202. **Casting.** Sonos and Chromecast fetch and decode the file themselves, so audio processing done in
  203. NullPlayer never reaches them. The Sonos app's own EQ is limited to bass, treble and loudness.
  204. **EQ Cast** applies the profile before casting: it renders the track with its profile into a new
  205. file and casts that file instead of the original.
  206. ### Quick start: EQ profiles
  207. Signal chain, playing locally and with EQ Cast:
  208. ```mermaid
  209. flowchart LR
  210. subgraph Cast["EQ Cast to Sonos / Chromecast"]
  211. direction LR
  212. S2[Track] --> P2[EQ profile] --> F["Rendered track<br/>in the cache folder"] --> R[Speaker plays the render]
  213. end
  214. subgraph Local["Playing on this Mac"]
  215. direction LR
  216. S1[Track] --> P1[EQ profile] --> T[Reference Tuning] --> E[Equalizer window] --> W["SRS<br/>WOW / TruBass"] --> O[Output device]
  217. end
  218. ```
  219. The Studio's analyser shows the signal after the profile for local files, and the final output for
  220. streams.
  221. 1. Play a track and open **Windows ▸ Equalizer Studio**. Your edits are heard on the playing
  222. track while the Studio is open.
  223. 2. Shape the curve. **GRAPHIC** shows the 31 faders; **PARAMETRIC** shows the high-pass filter and
  224. four bands with frequency, gain and Q dials. Both edit the same curve. With **LINK** lit, both
  225. channels move together; turn it off to set left and right separately. **BYPASS** plays a channel
  226. without the curve so you can compare.
  227. 3. Press **HEADROOM**. It lowers the preamp so the curve's highest boost peaks at 0 dB and does not
  228. clip.
  229. 4. Press **SAVE AS** and name the profile. Saving does not assign it. Once the Studio closes, a
  230. profile is heard only on music it is assigned to.
  231. 5. Right-click a track, album or artist in the Library, or a row in the queue, and choose
  232. **Assign EQ Profile ▸** *your profile*.
  233. 6. Queue rows playing with a profile show **∿** before the title, and **File Info** shows the
  234. profile and the level it came from, e.g. `EQ Profile: Warm (album)`.
  235. To change a profile later, play something it is assigned to and open the Studio: it opens on the
  236. playing track's profile. Edit it and press **SAVE**.
  237. **Assigning:**
  238. - **Inherit** removes the setting at that level, so the next level down applies. **Off** plays the
  239. item with no profile even if its album or artist has one.
  240. - Assigning to a playlist or folder assigns to the tracks in it at that moment; tracks added later
  241. get nothing.
  242. - An assignment matches the file path, tag or server ID it was made on. Moving or renaming a file,
  243. or retagging its album or artist, stops it matching.
  244. - **Playback ▸ EQ Profiles** turns all profiles off without removing any assignments.
  245. ### Quick start: EQ Cast
  246. 1. Assign profiles to what you want to cast (above).
  247. 2. Turn on **Output ▸ EQ Cast ▸ Enabled** and choose a folder for the rendered files. Don't
  248. choose a folder your library watches, or the renders will be imported as duplicate tracks.
  249. 3. Start a cast to Sonos or Chromecast from the Output menu as usual.
  250. 4. The first track starts once it is rendered; a progress bar at the top of the main window shows
  251. how far along it is. Server tracks are downloaded first. The next three tracks are rendered in
  252. the background while you listen.
  253. **What to know:**
  254. - Only the profile is rendered. The Equalizer window and other effects (SRS, Reference Tuning,
  255. playback speed) are not applied.
  256. - Supported: local files and Plex, Jellyfin, Emby and Navidrome/Subsonic tracks. Cast as the
  257. original file: radio, tracks from a cue sheet, video, sources with more than two channels, and tracks with
  258. no profile or set to **Off**.
  259. - A render is reused while the assigned profile and its curve are unchanged. Editing a profile re-renders the tracks
  260. coming up next.
  261. - Renders are 16-bit. A curve with large boosts can clip; press **HEADROOM** in the Studio and
  262. save.
  263. - The folder is not cleared automatically, and every render is a full copy of the track.
  264. **Output ▸ EQ Cast** shows the cache size; **Delete Cache…** removes every render except the one
  265. being cast.
  266. ## Media Library
  267. Library data is stored as a SQLite database at `~/Library/Application Support/NullPlayer/library.db`.
  268. **Backup & Restore API** (`MediaLibrary.swift`):
  269. | Function | Description |
  270. |----------|-------------|
  271. | `backupLibrary(customName:)` | Creates timestamped `.db` backup, returns URL |
  272. | `restoreLibrary(from:)` | Restores from backup (auto-backs up current first) |
  273. | `listBackups()` | Returns backup URLs sorted newest first |
  274. | `deleteBackup(at:)` | Deletes a backup file |
  275. Backups are stored in `~/Library/Application Support/NullPlayer/Backups/`.
  276. ## Skins
  277. NullPlayer has seven looks — Modern, Classic, Original, Original-Metal, Windows Media Player, Audion Faces, and Sonique — selectable from the right-click context menu under **Skins**. Switching between them happens **live, with no restart** — playback, casting, and the open playlist continue uninterrupted while the windows rebuild in the new look:
  278. At the bottom of the Skins menu, **Browse NullPlayer Certified Skins** opens the [nullplayer.fyi skin gallery](https://nullplayer.fyi/skins/), the record of every skin tested working on NullPlayer, and **Report a Skin Bug** opens the [bug report page](https://nullplayer.fyi/report-a-bug/) for a skin that draws or behaves wrong.
  279. ### Winamp Modern (`.wal`) / ClassicPro
  280. ClassicPro skins (such as cPro-Bento, cPro2 Dark Aluminum, and the cPro Insomnis family) depend on the **ClassicPro plug-in**, which ships in a Windows installer. NullPlayer extracts that installer internally — no Wine, no external tools — but you must supply the installer. You can download it directly from **Skins > Modern > Download ClassicPro Engine...** and that will open a browser to the Softpedia download page.
  281. **Only `ClassicPro_2.01.exe` is supported.** Other versions or builds are not recognized; importing them shows a clear warning and the engine stays inactive.
  282. To set up:
  283. 1. Open **Skins > Modern > Download ClassicPro Engine...** to fetch `ClassicPro_2.01.exe`.
  284. 2. Import the installer via **Skins > Modern > Import ClassicPro Engine…** (it stays as a single private copy and is not run as a program).
  285. 3. Import a ClassicPro skin via **Skins > Modern > Load Skin...**, then select it from **Skins > Modern**.
  286. NullPlayer's Winamp Modern support is built through clean-room reverse engineering, verified against a corpus of real-world skins. The [skin compatibility report](docs/winamp-modern/skin-compatibility.md) is the current corpus of `.wal` skins tested in that effort — every Winamp 5.x skin the engine has been measured against, its compatibility grade, and what is still known to be outstanding on it. It is updated as the engine improves and new skins are measured.
  287. ### Windows Media Player (`.wmz`)
  288. NullPlayer is the only Mac app that runs Windows Media Player skins. The `.wmz` skins made for WMP 7 through 12 — shaped windows, multiple views, compact/full modes, and the JScript that animates them — load in a clean-room engine and drive NullPlayer's own playback, EQ, SRS enhancements, and visualizers. A fresh install opens in NullPlayer's built-in unskinned WMP player until you import a skin.
  289. 1. Choose **Import WMZ…** on the unskinned player, or **Skins > Media Player > Load Skin...**. **Get More Skins...** in the same menu opens the Internet Archive's Windows Media Player skins collection.
  290. 2. Pick an installed skin from **Skins > Media Player**; a skin with several views lists them under **Views**.
  291. 3. **Remove “name”...** deletes NullPlayer's installed copy of the current skin (never your download) and returns to the built-in player.
  292. Skin scripts run in a restricted, sandboxed object model: ActiveX, registry and shell access, DLLs, WMP plug-ins, and skin-authored HTML are not supported. See the [WMP skin guide](skills/wmp-skin-guide/reference/user-guide.md) and the [compatibility reference](docs/wmp-skin/compatibility.md) for the supported surface.
  293. ### Audion Faces
  294. Panic Audion faces (a folder of `index.json` and PNGs) are drawn by a port of Panic's own FaceKit viewer, checked against it face by face. No faces are bundled; with none selected NullPlayer shows a plain Audion player.
  295. 1. **Skins > Audion Faces > Get More Faces...** opens Panic's download page for the 2021 face archive.
  296. 2. **Load Face...** installs a face folder, or a `.zip` holding any number of them, then switches to it.
  297. 3. Pick an installed face from **Skins > Audion Faces**; **Remove “name”...** deletes NullPlayer's copy and returns to the plain player.
  298. See the [Audion faces guide](skills/audion-face-guide/reference/user-guide.md).
  299. ### Sonique (`.sgf`)
  300. Sonique 1.x skins are drawn in all three of Sonique's modes — the navigator, mid and small — and checked against real Sonique 1.96 skin by skin. No third-party skins are bundled; until you install one, NullPlayer shows its own built-in Sonique skin, which also fills in any part a skin leaves out.
  301. 1. **Skins > Sonique > Get More Skins...** opens the Internet Archive's Sonique collection (its torrent file pulls the large skin archive most reliably). Only the skins work; Sonique's plugins are not supported.
  302. 2. **Load Skin...** installs an `.sgf` and switches to it.
  303. 3. Pick an installed skin from **Skins > Sonique**, and a mode from **Skins > Sonique > Mode**; **Remove “name”...** deletes NullPlayer's copy and returns to the built-in skin.
  304. The navigator's menu screen opens NullPlayer's Playlist Editor, Library Browser and other windows; the visual mode screen shows NullPlayer's effects, stepped with the up/down rocker; the drawer is the equalizer.
  305. ### Winamp Classic Mode
  306. Classic `.wsz` skin support. The app starts with a native macOS appearance and ships with one original NullPlayer skin (Silver). To apply a skin, use **Skins > Load Skin...** to open a `.wsz` file, or place skin files in `~/Library/Application Support/NullPlayer/Skins/` and select them from the Skins menu. Thousands of community-created skins can be downloaded from the **Skins > Get More Skins...** menu link, which opens the [Winamp Skin Museum](https://skins.webamp.org).
  307. ### Nullplayer Original Mode
  308. A custom skin engine built from scratch with a neon cyberpunk aesthetic. Original skins are JSON-configured and support:
  309. - **Color palette theming** -- define 12 named colors and the entire UI adapts
  310. - **Custom PNG image assets** -- optionally replace any UI element with your own artwork
  311. - **Procedural grid backgrounds** -- configurable Tron-style perspective grids
  312. - **Bloom/glow post-processing** -- Metal-based glow effects on bright UI elements
  313. - **Custom fonts** -- bundle TTF/OTF fonts or use any system font
  314. - **Animations** -- sprite frame cycling and parametric effects (pulse, glow, rotate, color cycle)
  315. The bundled default skin ("NullPlayer-Orange") is palette-driven apart from one gradient background image.
  316. **Creating a skin is as simple as writing a single JSON file.** See [SKINNING.md](SKINNING.md) for the complete guide.
  317. **Skin installation**: Place skin folders or `.nsz` bundles in the compatibility directory `~/Library/Application Support/NullPlayer/ModernSkins/`, then right-click the player and select your skin from **Skins > Original**.
  318. ### Nullplayer Original-Metal Mode
  319. A hi-fi hardware faceplate look, selected from **Skins > Original-Metal**, with seven finishes — Brushed Steel, Aluminum, Gunmetal, Anodized Black, Brass, Bronze, and Copper. Each finish restyles the whole player (chrome, panels, sliders, transport, and EQ) with a backlit-green LCD for the time and track displays and a spectrum analyzer matched to the finish.
  320. ## CLI Mode
  321. NullPlayer includes a first-class headless CLI mode for browsing, querying, playing, and routing media entirely from the terminal. It is designed to work as a scriptable command in automation pipelines: resolve media from multiple sources, pick a local output or cast target, then hand off playback without opening the GUI.
  322. This is not just a hidden debug flag. `nullplayer` is a supported command surface for:
  323. - querying and searching local, Plex, Subsonic/Navidrome, Jellyfin, Emby, and radio sources
  324. - starting playback from those sources with a stable command-line interface
  325. - routing playback to local outputs or casting to Sonos, Chromecast, and UPnP/DLNA devices
  326. - casting local, Plex, Jellyfin, and Emby video to Chromecast or DLNA TV targets
  327. - emitting machine-friendly query output with `--json`
  328. ```bash
  329. nullplayer --cli [OPTIONS]
  330. ```
  331. ### Multi-source media control
  332. `nullplayer` can act as a scriptable media control command for automation pipelines, connecting multiple media sources to multiple playback targets.
  333. Supported media sources include:
  334. - local files and library
  335. - Plex
  336. - Subsonic / Navidrome
  337. - Jellyfin
  338. - Emby
  339. - internet radio
  340. Supported playback targets include:
  341. - local audio output devices
  342. - Sonos
  343. - Chromecast
  344. - UPnP / DLNA
  345. Typical automation shape:
  346. ```bash
  347. nullplayer --cli --source plex --playlist "All Music" --cast "Living Room" --cast-type sonos
  348. nullplayer --cli --source local --artist "Courtney Barnett" --output "MacBook Pro Speakers"
  349. nullplayer --cli --source radio --station "Radio Paradise: Mellow Mix" --cast "Kitchen Speaker" --cast-type chromecast
  350. nullplayer --cli --source plex --library Movies --movie "Alien: Romulus" --cast "Living Room TV" --cast-type chromecast
  351. nullplayer --cli --file "/path/to/video.mkv" --cast "Samsung QN90BA 75" --cast-type dlna
  352. ```
  353. > **Audio and video scope.** Music playback supports local output, Sonos, Chromecast, and DLNA targets. Video is cast-only in CLI mode: use `--file` for local video files or `--movie` / `--show` / `--episode` for Plex, Jellyfin, and Emby video libraries. Video requires `--cast` and supports Chromecast or DLNA TV targets; Sonos is audio-only.
  354. ### Query commands (print results and exit)
  355. ```bash
  356. nullplayer --cli --list-sources # show configured sources
  357. nullplayer --cli --list-libraries --source plex # list Plex libraries
  358. nullplayer --cli --list-artists --source plex --library AD-FLAC # list artists in a Plex library
  359. nullplayer --cli --list-albums --source plex --library AD-FLAC --artist "Soundgarden"
  360. nullplayer --cli --list-albums --source local # list local albums
  361. nullplayer --cli --list-tracks --source local --artist "Rush" # list tracks
  362. nullplayer --cli --list-genres --source local # list local genres
  363. nullplayer --cli --list-artists --source subsonic # Navidrome/Subsonic artists
  364. nullplayer --cli --list-albums --source jellyfin --artist "3rd Bass" # Jellyfin albums by artist
  365. nullplayer --cli --list-libraries --source emby # Emby libraries
  366. nullplayer --cli --list-playlists --source plex # list playlists
  367. nullplayer --cli --list-stations # list internet radio stations
  368. nullplayer --cli --list-queue --source local --radio genre --genre "Reggae" # print the queue a radio mode would play
  369. nullplayer --cli --list-eq # list EQ presets
  370. nullplayer --cli --list-outputs # list audio output devices
  371. nullplayer --cli --list-devices # list cast devices
  372. nullplayer --cli --search "soundgarden" --source plex --library AD-FLAC # search a library
  373. nullplayer --cli --list-artists --source plex --library AD-FLAC --json # JSON output
  374. ```
  375. > **Selecting a Plex library.** Plex servers often expose several music libraries (e.g. `AD-FLAC`, `AD-MP3`, `Classical-FLAC`). Pass `--library <name>` to pick one. If you omit it, the CLI uses your last-selected music library; if that is ambiguous it prints the available music libraries so you can choose. Run `nullplayer --cli --list-libraries --source plex` to see the exact names.
  376. ### Playback
  377. ```bash
  378. # Local library
  379. nullplayer --cli --source local --artist "Courtney Barnett"
  380. nullplayer --cli --source local --album "Dub Side Of The Moon"
  381. nullplayer --cli --source local --genre "Reggae" --repeat-all
  382. nullplayer --cli --source local --artist "Rush" --shuffle
  383. # Local library radio (track|library|genre|decade|artist); track radio scores by tags, --artist disambiguates
  384. nullplayer --cli --source local --radio track --track "Tom Sawyer" --artist "Rush"
  385. nullplayer --cli --source local --radio library
  386. # Plex — pick a music library with --library (omit to use your last-selected one)
  387. nullplayer --cli --source plex --library AD-FLAC --artist "Soundgarden" --album "SuperUnknown"
  388. nullplayer --cli --source plex --library AD-FLAC --artist "AC/DC" --shuffle
  389. nullplayer --cli --source plex --library AD-FLAC --artist "AC/DC" --album "Black Ice" --tuning 432
  390. nullplayer --cli --source plex --playlist "All Music"
  391. # Subsonic / Navidrome (music-only server; --library selects a music folder)
  392. nullplayer --cli --source subsonic --artist "ZZ Top" --album "Eliminator"
  393. nullplayer --cli --source subsonic --artist "ZZ Top" --shuffle
  394. # Jellyfin (--library selects a music library; omit to use the current one)
  395. nullplayer --cli --source jellyfin --library "Music" --artist "3rd Bass" --album "The Cactus Album"
  396. nullplayer --cli --source jellyfin --artist "3rd Bass" --shuffle
  397. # Emby
  398. nullplayer --cli --source emby --library "Music" --artist "ZZ Top" --album "La Futura"
  399. nullplayer --cli --source emby --artist "ZZ Top"
  400. # Internet radio
  401. nullplayer --cli --source radio --station "Radio Paradise: Mellow Mix"
  402. nullplayer --cli --source radio --station "Heart 80s UK"
  403. # Outputs and casting
  404. nullplayer --cli --source local --artist "Augustus Pablo" --output "MacBook Pro Speakers"
  405. nullplayer --cli --source plex --playlist "Recently Added" --cast "Living Room" --cast-type sonos
  406. nullplayer --cli --source plex --library AD-FLAC --artist "Soundgarden" --album "Louder Than Love" --library AD-FLAC --cast "Dining Room" --cast-type sonos
  407. # Sonos multi-room: the first name is the group coordinator, the rest are grouped onto it
  408. nullplayer --cli --source plex --playlist "Recently Added" --cast "Living Room,Kitchen,Office" --cast-type sonos
  409. # (equivalent to --cast "Living Room" --sonos-rooms "Kitchen,Office")
  410. ```
  411. ### Video casting
  412. Video commands require `--cast` and route to Chromecast or DLNA TV targets. Use `nullplayer --cli --list-devices` to get the exact device names on your network.
  413. Local video files are served through NullPlayer's embedded local media server on port `8765`. If the main NullPlayer app is already open, it may already own that port; quit the app UI or stop the other NullPlayer process before retrying the CLI cast. Videos added with **Add Video Files...** stay at their original file paths; cast them from the CLI with `--file`.
  414. ```bash
  415. # Local video file
  416. nullplayer --cli --file "/path/to/video.mkv" --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  417. nullplayer --cli --file "/path/to/video.mkv" --cast "Samsung QN90BA 75" --cast-type dlna
  418. # Local video file from Downloads
  419. nullplayer --cli --file "$HOME/Downloads/My Movie.mp4" --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast --verbose
  420. nullplayer --cli --file "$HOME/Downloads/My Movie.mp4" --cast "Samsung QN90BA 75" --cast-type dlna --verbose
  421. # Plex movies
  422. nullplayer --cli --source plex --library Movies --movie "Alien: Romulus" --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  423. nullplayer --cli --source plex --library Movies --movie "Alien: Romulus" --cast "Samsung QN90BA 75" --cast-type dlna
  424. # Plex TV episodes
  425. nullplayer --cli --source plex --library "TV Shows" --show "Alien: Earth" --episode "Neverland" --season 1 --number 1 --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  426. nullplayer --cli --source plex --library "TV Shows" --show "Alien: Earth" --episode "Neverland" --season 1 --number 1 --cast "Samsung QN90BA 75" --cast-type dlna
  427. # Emby movies
  428. nullplayer --cli --source emby --library Movies --movie "Alien: Romulus" --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  429. nullplayer --cli --source emby --library Movies --movie "Alien: Romulus" --cast "Samsung QN90BA 75" --cast-type dlna
  430. # Emby TV episodes
  431. nullplayer --cli --source emby --library "TV shows" --show "Abbott Elementary" --episode "Ava & Fest" --season 5 --number 21 --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  432. nullplayer --cli --source emby --library "TV shows" --show "Abbott Elementary" --episode "Ava & Fest" --season 5 --number 21 --cast "Samsung QN90BA 75" --cast-type dlna
  433. # Jellyfin movies and TV episodes
  434. nullplayer --cli --source jellyfin --library "Movies" --movie "Alien: Romulus" --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  435. nullplayer --cli --source jellyfin --library "Movies" --movie "Alien: Romulus" --cast "Samsung QN90BA 75" --cast-type dlna
  436. nullplayer --cli --source jellyfin --library "TV Shows" --show "Alien: Earth" --episode "Neverland" --season 1 --number 1 --cast "Chromecast-Ultra-91a086b76d0c422dd9dd9cda078e4911" --cast-type chromecast
  437. nullplayer --cli --source jellyfin --library "TV Shows" --show "Alien: Earth" --episode "Neverland" --season 1 --number 1 --cast "Samsung QN90BA 75" --cast-type dlna
  438. ```
  439. DLNA video devices do not report reliable end-of-stream status, so press `q` to stop the CLI when the video ends. Chromecast video exits automatically after playback ends and the cast session is torn down.
  440. ### Volume control
  441. Set the initial playback volume at launch:
  442. ```bash
  443. nullplayer --cli --source local --artist "Rush" --volume 80
  444. nullplayer --cli --source plex --playlist "All Music" --cast "Living Room" --cast-type sonos --volume 35
  445. ```
  446. During playback:
  447. - `↑` increases volume by 5%
  448. - `↓` decreases volume by 5%
  449. - `m` toggles mute
  450. For audio casting, the same CLI volume control path is used for the cast target as well.
  451. ### Reference Tuning
  452. Reference Tuning pitch-shifts local output to a selected reference frequency, such as retuning A=440 content to A=432. In the app, use **Playback > Options > Reference Tuning** for Off, 432 Hz, 440 Hz, or custom source/target Hz. It applies to local files and HTTP streams from Plex, Subsonic/Navidrome, Jellyfin, Emby, and internet radio. It is unavailable while casting because Sonos, Chromecast, and DLNA renderers receive the media URL directly.
  453. CLI overrides are session-only:
  454. ```bash
  455. nullplayer --cli --source local --artist "Rush" --tuning 432
  456. nullplayer --cli --source plex --library AD-FLAC --artist "Soundgarden" --tuning 432 --tuning-source 440
  457. nullplayer --cli --source radio --station "Radio Paradise: Mellow Mix" --tuning-offset-cents -31.766
  458. ```
  459. ### Keyboard controls (during playback)
  460. | Key | Action |
  461. |-----|--------|
  462. | `Space` | Pause/Resume |
  463. | `q` | Quit |
  464. | `>` / `<` | Next / Previous track |
  465. | `→` / `←` | Seek forward / backward 10s |
  466. | `↑` / `↓` | Volume up / down |
  467. | `s` | Toggle shuffle |
  468. | `r` | Cycle repeat (off → all → one) |
  469. | `m` | Toggle mute |
  470. | `i` | Show track info |
  471. For video casting, `Space` pauses/resumes the cast, `→` / `←` seek on the cast session, and `q` stops casting before exiting. Track navigation, shuffle, repeat, mute, and volume controls are audio-only.
  472. ### Terminal display
  473. During music playback the CLI shows album art in the terminal. The render mode is auto-detected from the terminal's color support and can be forced:
  474. - default: color half-block art on color-capable terminals (truecolor or 256-color), otherwise a monochrome character-ramp
  475. - `--color-art`: force color art
  476. - `--ascii-art`: force the monochrome character-ramp — use this if your terminal reports color but renders the art as flat blocks
  477. - `--no-art`: disable album art
  478. ```bash
  479. nullplayer --cli --source local --artist "Rush" --ascii-art
  480. ```
  481. If a terminal misreports its color support (some shell profiles `export COLORTERM=truecolor` globally, making every terminal claim color it can't paint), set a per-terminal default in that terminal's shell profile instead of passing a flag each time:
  482. ```sh
  483. export NULLPLAYER_ART=ascii # or: color, auto (default). Flags still override.
  484. ```
  485. Framework log output is suppressed by default so the session stays clean. Pass `--verbose` to keep it for debugging:
  486. ```bash
  487. nullplayer --cli --source plex --playlist "All Music" --cast "Living Room" --cast-type sonos --verbose
  488. ```
  489. See `nullplayer --cli --help` for the full flag reference.
  490. ## Development
  491. See [AGENTS.md](AGENTS.md) for documentation links and key source files.
  492. **Note:** This project will never support Spotify, Youtube, Apple or Amazon. Please do not submit PRs for this type of integration.
  493. ## Credits
  494. App icon by **Allan Nyholm Nielsen** ([#488](https://github.com/ad-repo/nullplayer/issues/488)).
  495. Default Winamp Modern skin, **iTunes Miniplayer**, by **[spacecowgoesmoo](https://github.com/spacecowgoesmoo)** ([Old-iTunes-Miniplayer](https://github.com/spacecowgoesmoo/Old-iTunes-Miniplayer), [#540](https://github.com/ad-repo/nullplayer/issues/540)).
  496. ## Privacy
  497. NullPlayer does not collect or transmit personal data to the developer. Playback
  498. and usage history is stored only in the app's local SQLite database. See the
  499. [Privacy Policy](PRIVACY.md) for details about local storage and user-directed
  500. network features.
  501. ## License
  502. This project is open source. Because it bundles GPL-licensed components
  503. (aubio, the PeppyMeter meter templates and the FaceKit port), the combined application is
  504. distributed under the terms of the **GNU GPL v3.0 only**. (The video engine
  505. is VLCKit/libVLC, which is LGPL — see below.)
  506. The **NullPlayer** name, logo, icon, and other brand identifiers are not licensed
  507. for use by modified distributions. Forks, derivative works, and redistributed
  508. builds must use a different application name and replace or remove NullPlayer
  509. branding from user-facing product names, bundle names, bundle identifiers,
  510. executable names, icons, and public marketing materials unless they have prior
  511. written permission. Accurate attribution such as "based on NullPlayer" is allowed
  512. when it does not imply endorsement.
  513. The full text of every third-party notice ships inside the app bundle at
  514. `Contents/Resources/ThirdPartyLicenses/` (aggregated in `ThirdPartyNotices.txt`,
  515. with the individual license texts alongside it). `scripts/build_dmg.sh` runs
  516. `scripts/validate_notices.sh` to fail the release if any bundled dependency is
  517. missing its notice. See [docs/third-party-notices.md](docs/third-party-notices.md)
  518. for the refresh process and `scripts/third_party_components.tsv` for the
  519. authoritative component/version/license list.
  520. Bundled third-party components:
  521. **Swift packages (compiled into the binary)**
  522. - **SQLite.swift** (MIT) + **swift-toolchain-sqlite** (Apache-2.0) / **SQLite** (public domain) — media library
  523. - **ZIPFoundation** (MIT) — `.wsz`/`.nps`/`.wmz` and Audion face `.zip` extraction
  524. - **AudioStreaming** (MIT) — streaming audio engine
  525. - **FlyingFox** (MIT) — local HTTP server for casting
  526. **Bundled frameworks / dynamic libraries**
  527. - **VLCKit / libVLC** (LGPL-2.1+) — video playback engine (MKV/MP4/etc.)
  528. - **libprojectM** (LGPL-2.1) — ProjectM/MilkDrop visualizations
  529. - **aubio** (GPL-3.0) — BPM/tempo detection
  530. - **libsndfile** (LGPL-2.1), **FLAC** (BSD-3), **libogg** (BSD-3), **libvorbis** (BSD-3), **Opus** (BSD-3), **LAME** (LGPL-2.0+), **mpg123** (LGPL-2.1) — audio codecs
  531. **Native ports (compiled into the binary)**
  532. - **vis_classic** (MIT) — Winamp AVS classic port
  533. - **Geiss** (BSD-3) — Geiss visualization port
  534. - **Tripex** (MIT) — Winamp-era visualization port by Ben Marsh
  535. - **Advanced Visualization Studio / libavs** (BSD-3) — AVS engine, from [grandchild/vis_avs](https://github.com/grandchild/vis_avs), with its vendored **EEL2** (Zlib), **nlohmann/json** (MIT), **stb_image** (MIT), and **pevents** (MIT); **sse2neon** (MIT) for arm64
  536. - **Goom** (LGPL-2.1) — the Goom2k26 visualizer core, from [j3k0/goom](https://github.com/j3k0/goom); Goom by Jean-Christophe Hoelt and Guillaume Borios
  537. - **Corona** (GPL-2.0-or-later) — libvisual's port of the Sonique visualizer, from [Libvisual/libvisual](https://github.com/Libvisual/libvisual); Corona by Richard Ashburn, libvisual port by Jean-Christophe Hoelt and Dennis Smit
  538. - **Smear** (BSD-style, with a source-access clause) — Smear 1.2 for Sonique and its scripts, from [the XMPlay support site](https://support.xmplay.com/files/11/smear.source.zip?v=791201); copyright Michael Landers and Samuel Graenacher
  539. - **FaceKit** (GPL-3.0-or-later) — Panic's Audion face viewer, adapted
  540. - **Nullsoft FFT** (BSD-3) — spectrum analysis
  541. **Fonts & assets**
  542. - **Departure Mono** (SIL OFL-1.1) — bundled font
  543. - **MilkDrop / projectM presets** — community-authored (attribution in preset filenames)
  544. - **AVS presets** — the presets shipped with upstream vis_avs (attribution in preset filenames)
  545. - **PeppyMeter meter templates** (GPL-3.0) — analog VU meter artwork, from [project-owner/PeppyMeter](https://github.com/project-owner/PeppyMeter)
  546. - **Viridis colormap** (CC0 / public domain) — spectrogram color ramp, by Stéfan van der Walt and Nathaniel Smith
  547. - **Bundled skins** — original NullPlayer assets

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.