djctl

Spotify

For users with access to a Spotify Premium account, djctl can monitor the currently playing track.

The Spotify source leverages Spotify’s Development Mode and consequently requires an active Spotify Premium subscription.

Setup Spotify integration

The integration currently leverages the authorization code flow which requires setting up a Client ID and Client Secret. To create a Spotify Client ID and Client Secret, follow these steps:

  • Visit https://developer.spotify.com/dashboard/applications.
  • Authenticate with your Spotify Premium account.
  • Click “Create an app”.
  • Enter “djctl” in the “App name” field.
  • Enter “dj control” in the “App description” field.
  • Enter “http://127.0.0.1:8888/callback” in the “Redirect URIs” field.
  • Select the checkboxes and submit.

Once created, the “Client ID” is displayed. Click on “Show client secret” to reveal the “Client secret” field. These values will need to be used later (along with a refresh token we will generate in the next step) so please make note of them.

Treat the client ID and secret as credentials. Never share them with anyone.

Authorize djctl

To get started, use the djctl Spotify setup wizard to authorize djctl access. Use the client ID and secret generated in the previous steps as command like arguments.

$ ./djctl spotify setup --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
time=2026-03-01T16:47:50.311-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:98 msg="Starting Spotify setup"

Open the following URL in your browser to authorize djctl:

  https://accounts.spotify.com/authorize?client_id=<redacted>&redirect_uri=http%3A%2F%2F127.0.0.1%3A8888%2Fcallback&response_type=code&scope=user-read-currently-playing

Waiting for callback on http://127.0.0.1:8888/callback ...

Copy the URL into your browser and press ENTER. Once the site loads, approve djctl access to the Spotify API.

Once authorized, djctl will output a refresh token. Take note of the token.

time=2026-03-01T16:51:00.600-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:218 msg="Received authorization code, exchanging for tokens..."
time=2026-03-01T16:51:00.834-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:225 msg="Received refresh token"
time=2026-03-01T16:51:00.836-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:231 msg="Saved token to disk" path=.spotify-token.json

Use --spotifysource.refresh="<REDACTED>" with "djctl start" to use the Spotify source.

Treat the Spotify refresh token as a sensitive credential. Never share it with anyone.

Authorize djctl (no local browser available)

If a local web browser is not available on the system where djctl runs, you can use a special “manual” mode to perform the setup.

$ ./djctl spotify setup --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET> --manual
time=2026-03-01T17:28:36.924-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:98 msg="Starting Spotify setup"

Open the following URL in your browser to authorize djctl:

  https://accounts.spotify.com/authorize?client_id=<redacted>&redirect_uri=http%3A%2F%2F127.0.0.1%3A8888%2Fcallback&response_type=code&scope=user-read-currently-playing

After authorizing, your browser will show a "connection refused" error.
Copy the full URL from the browser address bar and paste it below.

Paste redirect URL:

Copy the URL into a browser and press ENTER. Once the site loads, approve djctl access to the Spotify API. You will be redirected and see a “connection refused” error. Copy the URL and paste it back into the terminal window.

Paste redirect URL: http://127.0.0.1:8888/callback?code=<REDACTED_CODE>
time=2026-03-01T17:30:33.437-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:218 msg="Received authorization code, exchanging for tokens..."
time=2026-03-01T17:30:33.659-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:225 msg="Received refresh token"
time=2026-03-01T17:30:33.661-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/spotify.go:231 msg="Saved token to disk" path=.spotify-token.json

Use --spotifysource.refresh="<REDACTED>" with "djctl start" to use the Spotify source.

Once authorized, djctl will output a refresh token. Take note of the token.

Add Spotify tokens to configuration

Next, insert the Spotify tokens into your djctl conf.yaml configuration file. The following is a simple example of a configuration file:

---
license:
  key: "<INSERT YOUR DJCTL LICENSE>"
source: "spotify"
spotifysource:
  id: "<CLIENT_ID>"
  secret: "<CLIENT_SECRET>"
  refresh: "<REFRESH_TOKEN>"

See the djctl CLI usage guide for more information regarding configuration files.

Alternatively, you can launch djctl with the tokens provided as command line arguments. For example:

./djctl start --source=spotify --spotifysource.id="<CLIENT_ID>" --spotifysource.secret="<CLIENT_SECRET>" --spotifysource.refresh="<REFRESH_TOKEN>"

Launch djctl

The following launch examples assume a configuration file has been configured.

Mac or Linux

To launch on a Mac or Linux, use the following command:

./djctl start --source=spotify

### Windows

If you are on Windows, use the following command:

```sh
djctl.exe start --source=spotify

Output

If all goes well, output in the terminal window will resemble the following:

./djctl start --source=spotify
time=2026-03-01T17:01:48.285-08:00 level=INFO source=/Users/mhite/repo/denonctl/cmd/djctl/command/start.go:168 msg="Licensed to <redacted> for major version 1 until 2122-05-03"
time=2026-03-01T17:01:48.285-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/start.go:45 msg="Starting http listener" httpAddr=:9090
time=2026-03-01T17:01:48.398-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/publish.go:49 msg="track transition detected" artist="" song=""
time=2026-03-01T17:01:48.398-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/source.go:85 msg="Starting Spotify source"

Connect to the djctl web server

Connect to http://127.0.0.1:9090/.

Play music!

Start your favorite playlist. You’ll see track transitions automatically update in the browser view. You should also see track transition messages log to the terminal.

time=2026-03-01T17:01:49.242-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/publish.go:49 msg="track transition detected" artist="The Weeknd" song="The Hills"
time=2026-03-01T17:01:50.001-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/sink/websocket/pool.go:101 msg="Wrote featured track to websocket"

To exit, hit CTRL-C.

^Ctime=2026-03-01T17:03:44.068-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/start.go:107 msg="received shutdown signal" signal=interrupt
time=2026-03-01T17:03:44.068-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/start.go:114 msg=exiting
time=2026-03-01T17:03:44.068-08:00 level=INFO source=/Users/mhite/repo/denonctl/internal/app/start/start.go:53 msg="shutting down http server"
Prev
Serato
Next
Twitch