Headless Mode

Headless mode runs the Now Playing desktop app with no window, no tray icon, and no dock icon. It is designed for setups where the app needs to run as a background service — a server computer dedicated to streaming, a small NUC tucked into a DJ booth, or an automated rig.

When Headless Mode Makes Sense

• You have a dedicated machine that runs only Now Playing, and you do not want a visible window taking up screen space or resources.
• You want to run Now Playing under a process manager like launchd, systemd, or pm2 (with standard OS-level supervision).
• You are scripting a setup that starts Now Playing from a shell and wants clean, parseable output on stdout.
• You want trace-level logging written to a file for troubleshooting.

If you just want to minimise the normal app to the tray, you do not need headless mode — use the standard UI with the window hidden.

Requirements

You must have signed in with the GUI at least once before running headless. Headless mode reads the stored authentication from auth.json and does not have a way to run an OAuth login flow. If no session is found, the app exits with a clear error message asking you to sign in normally first.

Running It

On macOS:

"/Applications/Now Playing 3.app/Contents/MacOS/Now Playing 3" --headless

On Windows:

"C:\Program Files\Now Playing 3\Now Playing 3.exe" --headless

Once running, the process stays in the foreground until you interrupt it (Ctrl+C) or send a SIGTERM.

Command-Line Flags

Flag	Purpose
--headless	Run without a window, tray icon, or dock presence
--verbose	Enable DEBUG-level logging
--trace	Enable TRACE-level logging (requires --verbose)
--log=FILE	Write logs to the given file instead of stdout
--no-color	Disable ANSI colour codes in log output
--help	Print usage information and exit
--version	Print the version and exit

Startup Output

On a successful start, headless mode prints a short banner to stdout:

12:34.56p INFO [Desktop] Now Playing 3.0.0 darwin-arm64 (headless)
12:34.57p INFO [Desktop] Logged in as userId=abc123

Running in headless mode (no UI)
Control your settings at: https://app.nowplayingapp.com/dashboard
Press Ctrl+C to quit.

From there, the standard track pipeline runs exactly as it would with a window: DJ software is polled, controllers are captured via the MIDI Bridge, and tracks are sent to the cloud for overlay delivery. You manage settings from the web dashboard rather than the desktop UI.

Signal Handling

Headless mode handles two shutdown signals cleanly:

• SIGINT (Ctrl+C) — stop, disconnect gracefully.
• SIGTERM (sent by launchd, systemd, kill) — stop, disconnect gracefully.

Both paths close the Socket.IO connection, stop watchers and connectors, and exit with status 0. This makes Now Playing safe to run as a supervised service: a restart under a process manager does not leak resources or leave orphaned connections.

Log Output

With no flags, headless mode writes INFO-level messages to stdout. With --verbose, DEBUG messages are added; with --trace, TRACE messages are added. For long-running sessions it is common to combine --verbose --log= to avoid flooding stdout while still keeping a detailed log file.

What Headless Mode Is Not

• Not a daemon. The process runs in the foreground until stopped. If you want daemonisation, use a process manager.
• Not a lightweight build. The same Electron runtime and all the same connectors run as in GUI mode. The “headless” part is the window, not the code path.
• Not a configuration surface. All settings are managed through the web dashboard while the headless app is running.