From 28ffd217d643f525f940528addcff78846434635 Mon Sep 17 00:00:00 2001
From: "Mathias S." <enzooocf@gmail.com>
Date: Thu, 2 Oct 2025 17:07:52 +0200
Subject: [PATCH] docs: add troubleshooting section for media controls not
 working (#224)

---
 linux/README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/linux/README.md b/linux/README.md
index 2414a2d..6fcbf56 100644
--- a/linux/README.md
+++ b/linux/README.md
@@ -55,6 +55,40 @@ A native Linux application to control your AirPods, with support for:
    ./librepods
    ```
 
+## Troubleshooting
+
+### Media Controls (Play/Pause/Skip) Not Working
+
+If tap gestures on your AirPods aren't working for media control, you need to enable AVRCP support. The solution depends on your audio stack:
+
+#### PipeWire/WirePlumber (Recommended)
+
+Create `~/.config/wireplumber/wireplumber.conf.d/51-bluez-avrcp.conf`:
+
+```conf
+monitor.bluez.properties = {
+  # Enable dummy AVRCP player for proper media control support
+  # This is required for AirPods and other devices to send play/pause/skip commands
+  bluez5.dummy-avrcp-player = true
+}
+```
+
+Then restart WirePlumber:
+
+```bash
+systemctl --user restart wireplumber
+```
+
+**Note:** Do NOT run `mpris-proxy` with WirePlumber - it will conflict and break media controls.
+
+#### PulseAudio
+
+If you're using PulseAudio instead of PipeWire, enable and start `mpris-proxy`:
+
+```bash
+systemctl --user enable --now mpris-proxy
+```
+
 ## Usage
 
 - Left-click the tray icon to view battery status