libspotifyctl

Read state from and control the Spotify desktop app on Windows — from C++, C, Python, Node, or your shell. Offline. No Web API.

PyPI npm GitHub stars MIT

Install

Python 3.9+

pip install libspotifyctl

Node.js 18+

npm install libspotifyctl

C++ / C / CLI (build from source)

git clone https://github.com/ColdMeekly/spotifyctl
cd spotifyctl
cmake --preset release
cmake --build --preset release

Quickstart

Python

from libspotifyctl import SpotifyClient

with SpotifyClient() as c:
    c.on_state_changed(
        lambda s: print(f"[{s.status.name}] {s.artist} — {s.title}"),
        replay=True,
    )
    input()

Node.js

const { SpotifyClient } = require('libspotifyctl');
const c = new SpotifyClient();
c.on('stateChanged', (s) => console.log(`${s.artist} — ${s.title}`));
c.start();

Shell

spotifyctl now-playing --json
spotifyctl events | jq 'select(.type == "track_changed") | .current.title'
spotifyctl seek 1:23

Why

Offline No Spotify Web API, no OAuth, no client id, no network. Reads SMTC and Core Audio directly.
Native C++20 core compiled to a single DLL. Microseconds to query state. Push events from the OS.
Multi-language Same API across C++, C, Python, Node, and a CLI. Pick your stack.
Full surface State, transport, per-app volume/mute, smooth position, track and ad edges, album art.

Documentation