MediaRemote Adapter

The adapter works by leveraging the fact that processes with a bundle identifier starting with com.apple. are granted permission to access the MediaRemote framework.

Because the adapter uses a mechanism that identifies as a com.apple.* bundle (similar to how /usr/bin/perl identifies as com.apple.perl), it can bypass the restrictions introduced in macOS 15.4 that prevent direct loading of the MediaRemote framework from within standard third-party applications.

Starting with macOS 15.4, the MediaRemote framework has become non-functional when loaded directly from within a third-party application.

This project provides a functional alternative to allow developers to:

• Read 'now playing' information.
• Control media playback on the device.
• Access song artwork (which is not possible via osascript / AppleScript solutions).
• Receive real-time updates (which is not possible via osascript / AppleScript solutions).

You can build the MediaRemoteAdapter.framework and the MediaRemoteAdapterTestClient using CMake. The resulting binaries support x86_64 and arm64 architectures.

$ git clone https://github.com/ungive/mediaremote-adapter.git
$ cd mediaremote-adapter
$ mkdir build && cd build
$ cmake ..
$ cmake --build .
$ cd ..

# To run a stream immediately after building:
$ FRAMEWORK_PATH=$(realpath ./build/MediaRemoteAdapter.framework)
$ /usr/bin/perl ./bin/mediaremote-adapter.pl "$FRAMEWORK_PATH" stream

# To run a test immediately after building:
$ HELPER_PATH=$(realpath ./build/MediaRemoteAdapterTestClient)
$ /usr/bin/perl ./bin/mediaremote-adapter.pl "$FRAMEWORK_PATH" "$HELPER_PATH" test

The MediaRemote Adapter provides a Perl script (mediaremote-adapter.pl) that acts as a CLI interface to read now playing information and control media players.

To use it, you must bundle the mediaremote-adapter.pl script and the MediaRemoteAdapter.framework with your application. The framework should be passed as a script argument but must not be linked against your application. The script uses /usr/bin/perl to load the framework dynamically, leveraging system entitlements to access the MediaRemote framework.

/usr/bin/perl /path/to/mediaremote-adapter.pl /path/to/MediaRemoteAdapter.framework COMMAND

To see the MediaRemote Adapter in action, you can install the media-control CLI tool via Homebrew. This tool demonstrates how to stream now playing information on macOS.

$ brew tap ungive/media-control
$ brew install media-control
$ media-control stream

To verify if the adapter is functional (for example, to decide whether to fall back to AppleScript), you can use the test command. This requires the MediaRemoteAdapterTestClient executable to be bundled with your app and passed as an argument. An exit code of 0 indicates the adapter is functional and safe to use.

# Using the test client path as an argument
/usr/bin/perl /path/to/mediaremote-adapter.pl /path/to/MediaRemoteAdapter.framework /path/to/MediaRemoteAdapterTestClient test

# Alternatively, passing the test client path directly
/usr/bin/perl /path/to/mediaremote-adapter.pl /path/to/MediaRemoteAdapter.framework /path/to/MediaRemoteAdapterTestClient COMMAND

The mediaremote-adapter.pl script is a CLI entrypoint used to interact with the MediaRemote framework. It allows you to stream real-time playback updates, fetch current metadata, or send playback commands.

Basic Usage Pattern: mediaremote-adapter.pl FRAMEWORK_PATH [TEST_CLIENT_PATH] FUNCTION [PARAMS|OPTIONS...]

• FRAMEWORK_PATH: The absolute path to the MediaRemoteAdapter.framework directory.
• TEST_CLIENT_PATH: (Optional) The absolute path to the MediaRemoteAdapterTestClient executable. This is only used when calling the test function.
• FUNCTION: The specific action to perform (e.g., stream, get, send, seek, etc.).

mediaremote-adapter.pl /path/to/MediaRemoteAdapter.framework stream --no-diff

The get command prints the current now playing metadata once as a JSON object.

Mandatory Keys:

• bundleIdentifier
• playing (boolean)
• title

If any mandatory keys cannot be determined, the command prints null. Media without a title is considered invalid unless the --allow-missing-title flag is used.

Important Metadata Notes:

• artworkData and artworkMimeType may take time to load and are not guaranteed to be present in a single get call. Use stream or poll get regularly to capture them.
• mediaType values include MRMediaRemoteMediaTypeMusic and kMRMediaRemoteNowPlayingInfoTypeAudio.

# Example usage (assuming paths are set)
/usr/bin/perl mediaremote-adapter.pl /path/to/MediaRemoteAdapter.framework /path/to/MediaRemoteAdapterTestClient get

Use these commands to manipulate playback state:

• seek POSITION: Seeks to a specific timeline position. POSITION must be a positive integer representing microseconds.
• shuffle MODE: Sets shuffle behavior. MODE IDs:
  • 1: Disable
  • 2: Shuffle albums
  • 3: Shuffle tracks
• repeat MODE: Sets repeat behavior. MODE IDs:
  • 1: Disable
  • 2: Repeat track
  • 3: Repeat playlist
• speed SPEED: Sets playback speed. SPEED must be a positive integer.

Sends a specific control command to the currently active media player. The COMMAND must be one of the following integer IDs: