AirPlay 2 remote control: the mechanism is sendMediaRemoteCommand on the session event channel

[sebastienbaedis]

The README says:

Remote Control is unfortunately not available for AirPlay 2 clients, as the system used has not been discovered.

I think I found it, and it works here — play, pause, next track and previous track all
take effect on the sending iPhone.

The message

POST /command RTSP/1.0
Content-Type: application/x-apple-binary-plist

{ "type": "sendMediaRemoteCommand",
  "modernMediaRemoteCommand": <n> }

sent with ap2_event_port_post_command() on the session's event channel — the same
one ap2_event_send_update_info() already uses.

<n> is a MediaRemote command number: 0 play, 1 pause, 2 toggle, 3 stop,
4 next track, 5 previous track. These are the same numbers the sender itself
advertises: on connect it POSTs updateMRSupportedCommands with
mrSupportedCommandsFromSender, which Shairport Sync already forwards to the metadata
pipe as ssnc copl. On my iPhone commands 0–5 are all reported as enabled, so the
receiver can even know in advance which ones will work.

One trap worth documenting

AirPlay 2 opens two connections here. Sending this on the audio/PTP connection's
event channel works. Sending it on the remote-control connection (SETUP (RC),
airplay_stream_category == remote_control_stream) does not — that channel carries
length-prefixed MediaRemote protobuf messages instead, which is a separate
mechanism. I spent a long evening on the protobuf path before realising the plist path
was the right one. Writing protobufs to the audio connection's event channel got my
receiver dropped from the session repeatedly.

Where it comes from

Not from guessing at the phone — from Apple's own code. On macOS 26,
AirPlayReceiver.framework lives only in the dyld shared cache. Searching it (with
grep -a; without -a grep silently reports nothing on binaries) for
updateMRSupportedCommands lands in a region that contains the whole receiver-side
vocabulary:

• airplayReqProcessor_requestProcessCommand with the commands a receiver accepts:
  duckAudio, unduckAudio, mute, unmute, changeRelativeVolume,
  performPWDKeyExchange, updateMRNowPlayingInfo, updateMRSupportedCommands,
  setMRInfo, mrInfo, setSenderDisplayLatencyMs, updateMRPlaybackState,
  updateMRNowPlayingClient, fadeAudio
• AirPlayReceiverSessionSendMediaRemoteCommand next to the strings
  sendMediaRemoteCommand and modernMediaRemoteCommand, and the log format
  "Sending MediaRemote command (MR: %lld) (AP: %'C) back to sender."
• AirPlayReceiverSessionSendCommandForObject next to POST, /command, RTSP/1.0,
  application/x-apple-binary-plist, startTicks, eventClientID

The plist shape (keys as siblings of type, not nested under params) is readable
from neighbouring commands in the same table: setScreenRecordingState/state,
updateMC2UCStatus/mc2ucProbeBurstID/mc2ucStatus/mc2ucPktCnt.

Incidentally: ap2_event_send_modern_media_remote_command() is already declared in
ap2_event_message_handler.h but never defined — the name matches the Apple string
exactly, so I suspect you had already seen it.

Implementation

ssize_t ap2_event_send_modern_media_remote_command(rtsp_conn_info *conn,
                                                   unsigned int command_number) {
  if (conn == NULL)
    return -1;
  ssize_t result = -1;
  plist_t command = plist_new_dict();
  if (command != NULL) {
    plist_dict_set_item(command, "type", plist_new_string("sendMediaRemoteCommand"));
    plist_dict_set_item(command, "modernMediaRemoteCommand",
                        plist_new_uint(command_number));
    result = ap2_event_port_post_command(conn, command);
    plist_free(command);
  }
  return result;
}

The only other thing needed is picking the right connection: one whose
event_channel_fd != 0 and whose airplay_stream_category is not
remote_control_stream.

Tested with

• Shairport Sync 5.2.2.2 (0c53cf5), --with-airplay-2, Alpine Linux x86
• Receiver: an Apple TV 1st generation (2007, Pentium M) running Linux
• Sender: iPhone 15 Pro Max, build 23G71

I have not tested other senders, older iOS versions, or macOS as a sender, and I have
not looked at what a SEND_COMMAND_RESULT would look like — nothing comes back beyond
the RTSP 200 OK.

Happy to open a PR if that is useful. I did not file this as an Issue since blank
issues are disabled and this is not a bug report.

[mikebrady]

Many thanks for this fantastic work! It's great to finally see progress on AirPlay 2 remote control.

Just in the last few days, we actually have announced remote control for AirPlay 2 on the development branch. We have implemented the commands you mention above, plus a few more, including volume, loop mode and shuffle, and integrated them back to the existing D-Bus, MPRIS and MQTT vocabularies, though not extensively tested. (Maybe we should update that note in the master branch... 😬)

The process of discovering these techniques has been, by times, frustrating, tedious and laborious, so your discoveries are really interesting. It may also be that our implementations are too complicated -- there hasn't been much experimentation done on simplifying them, and your code may be helpful there.

The command availability information you've identified will feed into the MPRIS CanPlay, etc. properties when we get around to them.

(BTW, the updated metadata reader and the updated D-Bus test client will pretty print the new command and metadata information.)

The Remote Control connections are a real puzzle, and we have made zero headway on that front; any ideas and results would be very welcome.

[sebastienbaedis]

Hi, thanks for the compliments!

I haven't actually looked at the dev branch yet, so will do that soon.

Great to hear even more commands will be available, I'll test them iut on my setup and keep you posted!

[frozenmartini]

Field report: AirPlay 2 remote control on 5.6-dev-156-gb45f15b3, driven by a Bluetooth amplifier's touchscreen.

Setup: a Raspberry Pi 4 on Raspberry Pi OS trixie (arm64) with the PipeWire backend, D-Bus on the session bus, and NQPTP 1.2.9-dev-16-g0a88cd7 (smi11). A Kohler Anthem+ amplifier's touchscreen sends AVRCP play/pause/next/previous over Bluetooth. Our daemon forwards them to org.gnome.ShairportSync.RemoteControl Play/Pause/Next/Previous. Senders were an iPhone on iOS 27.0 and an iPad (iPad8,11) on iPadOS 27.0.

Before (5.2.2), same receiver: AirPlay 2 sessions came with no DACP-ID/Active-Remote and no _dacp._tcp advert, and RemoteControl.Available was false, so the commands had no effect. In classic mode, DACP worked.

Results on 5.6-dev, AirPlay 2:

• Play, Pause, Next and Previous all take effect on the sender. Tested with Amazon Music, Apple Music, YouTube Music, the YouTube app, Audible and BookPlayer. In the audiobook apps, Next/Previous trigger their own skips (±30 s in BookPlayer).
• Multi-room with mixed versions works. The iPad played to a group of this receiver (5.6-dev, smi11) and another Pi on 5.2.2 (smi10). Both followed the iPad's clock, and Next from the amp on the 5.6-dev receiver skipped the group's track. Titles reached both receivers when the source had them.
• CommandInformation as reported (MediaRemote numbers):

App	Enabled	Disabled
Amazon Music	0, 1, 2, 3, 4	(5 absent)
BookPlayer	0, 1, 2, 4, 5, 8, 9, 10, 11, 17, 18	24
YouTube Music	0, 1, 2, 4, 5, 24, 25, 26	17, 18 (sometimes 4 and 5 too)
YouTube (app)	0, 1, 2, 4, 5, 24	17, 18

Observations that may help:

1. RemoteControl.Available stays false for the whole AirPlay 2 session, even while every command works.
2. Active goes false about 10 s after a pause, but the sender keeps its RTSP connection and accepts Play long afterwards. A controller that reads "inactive" as "no AirPlay" loses the Play.
3. BookPlayer reports Paused for about 30 ms during a Next/Previous. A controller that reacts to state (our amp answers with its own Play about 80 ms later) can leave the sender stopped.
4. YouTube Music sends no NowPlayingInformation. The YouTube app's titles depend on the video.
5. Volume: the Control Center slider updates arrive. After shairport-sync restarts, the iPhone's hardware volume buttons several times stopped reaching the receiver until the phone was restarted. We saw this on 5.2.2 as well, so it may be iOS.
6. Starting volume: with the software mixer's default 96 dB range, default_airplay_volume = -24 comes out at about -55 dB, which is inaudible on our amp. volume_range_db = 40 fixed it. This might deserve a note for PipeWire-backend users.

Thanks for the work on this. Happy to test further builds.

[mikebrady]

Great stuff -- many thanks for this report!

1. Yes, neither RemoteControl.Available nor AdvancedRemoteControl.Available have been hooked up to AirPlay 2 operation yet.
2. Yes, this is by design: Active means the player is playing or was playing recently, nothing more.
3. We'll need to check where that pause is originating -- maybe it's in BookPlayer.

Working on some other aspects of Shairport Sync right now, but we'll circle back soon.

[derangedabbot]

Thanks — the mechanism works for us too, and we got a full working recipe out of it. Build: shairport-sync 5.5.1, AirPlay 2, on a rooted Yandex Station (aarch64/musl).

Confirming your finding: the plist goes on the audio/PTP connection's event port. On the SETUP (RC) channel it is silently swallowed.

Two pitfalls that cost us a lot of time and are not obvious from the protocol alone:

1. dbus-send needs --print-reply. Our trigger was dbus-send --system ... PlayPause. It exits 0, the log is empty, nothing happens. With --print-reply the call is handled and the command reaches the sender. Without it the client disconnects right after writing the message and the handler is cancelled. Worth documenting — this looks exactly like "the mechanism doesn't work".

2. Two receiver instances = silent failure. If a second shairport-sync is started (e.g. by a supervisor), the D-Bus name is owned by whichever started first and the audio session lives in the other. Commands are accepted and disappear. We added an atomic mkdir lock in the launcher and a /proc-based process scan (busybox ps w truncates the long cmdline when the musl loader precedes the binary, so the supervisor no longer saw the live instance and kept spawning copies).

Smaller notes, in case someone builds it for musl:

• in 5.5.x configure does not know --with-dbus; the interface we use is --with-mpris-interface, which pulls libgio/libglib (10 extra libs in our tarball);
• the plumbing is small: ap2_event_send_modern_media_remote_command(conn, n) building {type: sendMediaRemoteCommand, modernMediaRemoteCommand: n} next to ap2_event_send_update_info(), a registry of the active connection filled in ap2_event_receiver.c (skip remote_control_stream), and the existing MPRIS Next/Previous/PlayPause/Play/Pause/Stop handlers calling it before falling back to DACP — classic AirPlay keeps working as before.

Verified on macOS and on iPhone: next/previous switch tracks, toggle pauses and resumes. We drive it from the speaker itself (a small script, a web panel and voice commands), so the receiver is the one issuing the command.

Our notes, including the code patch and the build script: https://github.com/derangedabbot/yandex-station-midi-airplay (docs/03-airplay.md, step 6, and scripts/build/airplay2/remote-control.patch). Thanks for digging into the framework — the updateMRSupportedCommands hint was what made us try the plist path instead of protobuf.

[mikebrady]

Many thanks for the update! A couple of things for other readers:

in 5.5.x configure does not know --with-dbus

The configuration flag is, in fact, --with-dbus-interface.

dbus-send needs --print-reply.

That is not the case on Debian / Ubunbtu / Raspberry Pi OS, etc. Perhaps it's a peculiarity of your OS or libraries?

the plumbing is small...

Our notes, including the code patch...

Just for clarity, as best I understand it, the plumbing and patching you refer to is of your system and scripts, not Shairport Sync itself. Is that correct?

Thanks again.

[derangedabbot]

Thanks Mike — all three corrections taken.

1. --with-dbus: you're right, and it's our build script that is wrong. scripts/build/airplay2/build3-mpris.sh passes both --with-dbus and --with-mpris-interface; configure ignored the first (we should have read the "unrecognized options" warning) and the D-Bus support we got came from the MPRIS flag. Switching it to --with-dbus-interface and fixing the docs. We will keep MPRIS anyway, because it is the control surface we drive from the speaker itself (script, web panel, voice), but it is good to know the plain flag exists and does not drag in glib.

2. dbus-send --print-reply: agreed — that is our environment, not the norm. We observed it with the musl/Alpine D-Bus build on the device; I'll narrow the wording to "on this build" instead of stating it as a general rule.

3. To your question — both, and I should have been clearer. What I called plumbing splits in two:

• device-side scripts of ours (sound owner, boot script, avahi keeper) — model-specific, nothing to do with Shairport Sync;
• the remote control itself is a patch to Shairport Sync: remote-control.patch, 192 lines (+81/−23), touching ap2_event_message_handler.c, ap2_event_receiver.c, mpris-service.c, player.h, rtsp.c. Precisely the three pieces I described: the new ap2_event_send_modern_media_remote_command(), a registry of the active AP2 event connection (skipping remote_control_stream), and MPRIS handlers that try the AP2 path first and fall back to DACP.

One correction to my own link: the repo is now derangedabbot/yandex-station-2-airplay (the old name redirects). Happy to send the patch as a PR if you want to look at it.

[mikebrady]

Thanks for the clarifications. I'll take a look at your changes, but there have been quite a few changes from 5.5 to 5.6, especially in the remote control area and integrating AirPlay 2 and classic AirPlay commands...

[derangedabbot]

Understood — and having now built development on the device, you are right that our patch is obsolete. Test report, in case it is useful for 5.6/5.7:

What we ran: development at b972e90 (5.7-dev), built for aarch64/musl in an Alpine container with --with-airplay-2 --with-dbus-interface --with-mpris-interface, on a rooted Yandex Station 2 (Amlogic AXG, 32-bit userspace layer, musl loader). Version string on the device: b972e90-AirPlay2-smi11-OpenSSL-Avahi-ALSA-soxr-metadata-dbus-mpris.

Result: AirPlay 2 playback works, and so does remote control — pause / next / previous from the sending iPhone, including commands issued from the receiver side (our panel buttons, voice commands and a small airplay-ctl.sh all go MPRIS → remote_simple_command() → ap2_event_send_simple_modern_media_remote_command()). So the remote/ refactoring covers exactly what our 5.5 patch did, and I will not send that patch.

Two notes that cost us time, possibly worth a line in the docs:

1. nqptp must match the receiver's smi version. Moving from 5.5.1 (smi10, nqptp 1.2.8) to development (smi11) without rebuilding nqptp gives *fatal error: The NQPTP service can not be found. NQPTP must be installed and running to provide AirPlay 2 service. — with nqptp running fine and healthy, just at the old interface version. After building nqptp 1.2.9 alongside, it started immediately.

2. In 5.6+ AirPlay 2 listens on the port from shairport-sync.conf, not the fixed 7000. Our port = 5000 was silently ignored by 5.5 for AirPlay 2 (it always used 7000). In development the session lands on 5000. Anything that detects an active session by looking for an established connection on 7000 breaks: our sound-owner script stopped seeing the session, so the vendor daemon kept the ALSA device and the receiver logged open_alsa_device: -16 / Resource busy — the classic "AirPlay connects, no sound". Worth mentioning if other people build session detection on top of the receiver.

Everything is written up in the repo (docs/03-airplay.md for the ownership/port details, docs/07-airplay2-build.md for the build and the smi pairing). Thanks again — the updateMRSupportedCommands hint and the discussion here saved us a lot of time.

[mikebrady]

Fantastic, thanks!

[mikebrady]

And just in case you might have missed it, the MPRIS progress property is working now...