MediaRemote

MediaRemote is a private macOS framework that provides programmatic access to the system “Now Playing” information across all applications that integrate with macOS’s media center. The mediacontrol and mediacontroltcp sources allow djctl to monitor track information from any macOS application that uses this API (ie. Apple Music, Spotify, VLC, web browsers playing media, etc.).

Modes#

djctl supports two mediacontrol source modes:

• mediacontrol - Runs the media-control binary directly on the same machine as djctl
• mediacontroltcp- Receives media-control events over TCP, allowing the media-control binary to run on a different machine than djctl

mediacontrol#

This section covers media-control installed alongside djctl on a Mac.

Install media-control#

The media-control binary is required to use the MediaRemote API. Install it using Homebrew:

brew install media-control

By default, djctl expects the binary at /opt/homebrew/bin/media-control. If you install it elsewhere, you’ll need to specify the path using the --mediacontrol.binarypath flag.

Launch djctl#

After installing media-control, open a terminal window and switch to the directory containing the djctl binary. Launch it using the following command:

./djctl start --source=mediacontrol

Optional: Filter by application#

To monitor only specific applications (ie. only Spotify), use the --mediacontrol.bundleid flag:

./djctl start --source=mediacontrol --mediacontrol.bundleid=com.spotify.client

Refer to the table below for common bundle IDs.

Output#

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

time="2026-03-08T16:30:00-08:00" level=warning msg="No license key, running in demo mode"
time="2026-03-08T16:30:00-08:00" level=warning msg="Visit https://www.djctl.com/buy/ to purchase a license"
time="2026-03-08T16:30:00-08:00" level=info msg="Starting http listener" httpAddr=":9090"
time="2026-03-08T16:30:00-08:00" level=info msg="Starting media-control source"
time="2026-03-08T16:30:00-08:00" level=info msg="media-control stream started" binary="/opt/homebrew/bin/media-control" bundleID=""

Connect to the djctl web server#

Connect to http://127.0.0.1:9090/ in your web browser.

Play music!#

Start playing music in any macOS application that supports the MediaRemote API. djctl will automatically detect track changes and display the currently playing track.

mediacontroltcp#

The TCP source mode allows you to run the media-control binary on one macOS machine and djctl on another machine (which can be macOS, Linux, or Windows).

Launch djctl (any machine)#

On the machine where you want to run djctl (can be macOS, Linux, or Windows), open a terminal window and switch to the directory containing the djctl binary. Use the djctl start --source=mediacontroltcp command to start the TCP listener.

Mac or Linux#

./djctl start --source=mediacontroltcp

Windows#

djctl.exe start --source=mediacontroltcp

Optional: Filter by application#

To monitor only specific applications, use the --mediacontroltcp.bundleid flag:

./djctl start --source=mediacontroltcp --mediacontroltcp.bundleid=com.spotify.client

Install media-control (macOS machine)#

On your macOS machine, install media-control:

brew install media-control

Stream media-control events over TCP#

On your macOS machine, run media-control in stream mode and pipe the output to a TCP connection. Replace <DJCTL_HOST> with the IP address or hostname of the machine running djctl:

media-control stream --no-diff | nc <DJCTL_HOST> 9191

For example, if djctl is running on a machine at 192.168.1.100:

media-control stream --no-diff | nc 192.168.1.100 9191

Output#

If all goes well, output in the terminal window of the machine running djctl will resemble the following:

time="2026-03-08T16:30:00-08:00" level=warning msg="No license key, running in demo mode"
time="2026-03-08T16:30:00-08:00" level=warning msg="Visit https://www.djctl.com/buy/ to purchase a license"
time="2026-03-08T16:30:00-08:00" level=info msg="Starting http listener" httpAddr=":9090"
time="2026-03-08T16:30:00-08:00" level=info msg="Starting media-control TCP source"
time="2026-03-08T16:30:00-08:00" level=info msg="media-control TCP listener started" addr=":9191" bundleID=""

Once the macOS machine running media-control connects to djctl, you’ll see:

time="2026-03-08T16:30:15-08:00" level=info msg="media-control TCP connection accepted" remote="192.168.1.50:54321"

Connect to the djctl web server#

Connect to http://127.0.0.1:9090/.

Play music!#

Start playing music on your macOS machine (running media-control) in any application that supports the MediaRemote API. djctl will will receives updates from media-control and automatically detect track changes.

Important Notes#

• Artwork delay: This source requires –delay >= 1 to allow artwork events to arrive properly. djctl will automatically set this if not configured.
• Firewalls: When running djctl and media-control on separate machines, ensure network and endpoint firewalls do not block the connection.