Unlock Your AirPods. Break Free from Apple's Ecosystem.
Full-featured AirPods integration for Android and Linux through reverse-engineered Apple protocols
Features • Installation • Architecture • Contributing • Support
- What is LibrePods?
- How It Works
- Features
- Device Compatibility
- Platform Support
- Installation
- Architecture
- Advanced Features
- FAQ
- Contributing
- License
- Supporters
LibrePods is a reverse-engineered implementation of Apple's proprietary AirPods protocols, enabling full-featured integration with Android and Linux devices. Access all the premium features you paid for—noise control, adaptive transparency, ear detection, hearing aid functionality, and more—without being locked into Apple's ecosystem.
- 🔓 Freedom: Use your AirPods with any device
- 💰 Value: Access features you already paid for
- 🛠️ Customization: Advanced settings beyond what Apple offers
- 🌐 Open Source: Community-driven, transparent development
- 🔬 Innovation: Multi-device connectivity, custom controls
LibrePods communicates with AirPods using two Bluetooth protocols:
AirPods → BLE Broadcast → LibrePods
- Battery levels (left, right, case)
- Ear detection status (in/out of ear)
- Lid state (open/closed)
- Charging status
- No pairing required, read-only
LibrePods ←→ L2CAP Socket (PSM 0x1001) ←→ AirPods
- Noise control mode changes
- Rename AirPods
- Configure long-press actions
- Head gesture detection
- Conversational awareness
- Requires connection, bidirectional
LibrePods ←→ L2CAP Socket (PSM 0x001F) ←→ AirPods
- Hearing aid audiogram configuration
- Custom transparency mode settings
- Adaptive features
Technical Deep Dive: See ARCHITECTURE.md for detailed protocol specifications, packet formats, and system design.
- Active Noise Cancellation (ANC): Full ANC with transparency blend
- Transparency Mode: Hear your surroundings clearly
- Adaptive Mode: Automatically adjusts to environment (AirPods Pro 2)
- Off Mode: Disable all processing for maximum battery
- One-Bud ANC: Enable ANC even with one AirPod
- Auto Play/Pause: Music automatically pauses when you remove AirPods
- Smart Phone Switching: Seamlessly switches to phone speaker
- Configurable Behavior:
- Pause when one removed
- Pause when both removed
- Disabled
- Real-time Updates: Live battery levels for left, right, and case
- Charging Status: Know when each component is charging
- Notifications: Battery notifications with accurate percentages
- Widgets: Home screen widget showing battery status
- System Integration: Battery shown in Android settings (when installed as system app)
- Conversational Awareness: Volume lowers automatically when you speak
- Personalized Volume: Adaptive volume based on environment
- Adaptive Strength: Customize noise cancellation strength
- Custom Transparency:
- Amplification levels
- Tone adjustment
- Balance control
- Conversation boost
- Ambient noise reduction
- Audiogram Import: Use professional hearing test results
- Custom Frequency Adjustments: Precise hearing aid tuning
- Live Adjustments: Real-time audio compensation
- Professional Grade: Medical-grade audio processing
- Head Gestures: Answer/reject calls with head nods and shakes
- Stem Controls: Customize single-press, double-press, long-press
- Quick Settings Tile: Change noise control mode from notification shade
- Widget Controls: Quick access to common functions
- Simultaneous Connections: Connect to Android + Linux at the same time
- Automatic Switching: Seamlessly switch between devices
- Move Notification: See when another device takes over (just like on Apple devices)
- Coordinated Control: Both devices can control AirPods
- Rename AirPods: Give your AirPods any name (requires re-pairing)
- Custom Chime Volume: Adjust connection/disconnection sounds
- Accessibility Settings: Full access to Apple's accessibility features
- Long-Press Actions: Customize stem controls for each AirPod
- Noise Control
- Siri/Digital Assistant
- Play/Pause
- Skip Track
- Dynamic Island UI: iOS-like notification when connecting/disconnecting
- Quick Settings Dialog: Beautiful, native-looking control panel
- Material You: Adapts to your system theme
- Popup Notifications: Connection status, battery warnings, feature changes
* Requires acting as Apple device (See Advanced Features)
| Status | Device | Features |
|---|---|---|
| ✅ Fully Supported | AirPods Pro (2nd Gen USB-C) | All features tested and working |
| ✅ Fully Supported | AirPods Pro (2nd Gen) | All features tested and working |
| ✅ Fully Supported | AirPods Pro (3rd Gen) | All features except heart rate monitoring |
| ✅ Supported | AirPods Max | All features (some show as unsupported in UI) |
| AirPods 1/2/3/4 | Battery status, ear detection, basic controls |
Note: The protocol is largely universal across AirPods models. Most features should work on all devices, but extensive testing has only been done on AirPods Pro 2.
![]() |
![]() |
![]() |
| Settings Overview | Device Information | Debug Panel |
![]() |
![]() |
|
| Notification & QS Tile | Connection Popup | Head Gestures |
![]() |
![]() |
![]() |
| Home Screen Widget | Transparency Settings | Hearing Aid Adjustments |
Minimum: Android 13 (API 33)
Recommended: Android 14+ for best compatibility
Root Requirement:
⚠️ Most users need root access with Xposed
Due to an Android Bluetooth stack bug, root with Xposed is required to patch the Bluetooth library.
Exceptions (No root needed):
- ✅ ColorOS/OxygenOS 16: Most features work without root (except transparency customization, hearing aid setup, and Bluetooth multipoint)
- Root your device with Magisk or KernelSU
- Install Xposed framework (LSPosed recommended)
- Download LibrePods APK from Releases
- Install the app and grant required permissions
- Enable module in Xposed and restart Bluetooth
- Pair your AirPods normally through Android Bluetooth settings
- Open LibrePods and complete onboarding
Optional: Install as system app using provided Magisk module for full system integration.
demo-video.mp4
Note: The old QML-based version is available in the linux/ directory but is no longer actively maintained. A new version is under development (#241).
- ✅ Battery status monitoring
- ✅ Ear detection with media control
- ✅ Noise control mode switching
- ✅ System tray integration
- ✅ PulseAudio/Pipewire integration
- ✅ Auto-start on login
- ✅ Cross-device coordination
- Qt6 with QML
- CMake 3.22+
- Bluetooth development libraries
- D-Bus support
- PulseAudio or Pipewire
# Install dependencies (Ubuntu/Debian)
sudo apt install qt6-base-dev qt6-declarative-dev \
cmake libbluetooth-dev libdbus-1-dev \
libpulse-dev
# Clone repository
git clone https://github.com/kavishdevar/librepods.git
cd librepods/linux
# Build
mkdir build && cd build
cmake ..
make
# Run
./librepods- Pair AirPods through system Bluetooth settings
- Launch LibrePods - it will auto-detect connected AirPods
- System Tray Icon provides quick access to controls
- Main Window shows detailed status and settings
For detailed information, see linux/README.md
- Check Requirements: Android 13+, Rooted device, Xposed installed
- Download: Get the latest APK from Releases
- Install: Install APK and grant all permissions
- Configure Xposed: Enable LibrePods module in LSPosed
- Restart Bluetooth: Toggle Bluetooth or reboot
- Pair AirPods: Connect via Android Bluetooth settings
- Launch App: Complete onboarding wizard
# 1. Install dependencies
sudo apt install qt6-base-dev qt6-declarative-dev cmake libbluetooth-dev
# 2. Clone and build
git clone https://github.com/kavishdevar/librepods.git
cd librepods/linux && mkdir build && cd build
cmake .. && make
# 3. Run
./librepods# Requirements: Android Studio, Android NDK, Gradle
# Clone repository
git clone https://github.com/kavishdevar/librepods.git
cd librepods/android
# Build
./gradlew assembleRelease
# APK will be in app/build/outputs/apk/release/# Requirements: Qt6, CMake, Bluetooth libraries
cd librepods/linux
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
sudo make install # Optional: install system-wideLibrePods is built with a modular, protocol-driven architecture:
graph TB
subgraph "AirPods Hardware"
AP[AirPods]
AP_BLE[BLE Broadcaster]
AP_L2CAP[L2CAP Server<br/>PSM: 0x1001]
AP_ATT[ATT Server<br/>PSM: 0x001F]
AP --> AP_BLE
AP --> AP_L2CAP
AP --> AP_ATT
end
subgraph "Android App"
direction TB
subgraph "UI Layer"
MA[MainActivity<br/>Compose UI]
QS[QuickSettings Dialog]
WIDGET[Home Screen Widget]
NOTIF[Notifications]
end
subgraph "Service Layer"
APS[AirPodsService<br/>Foreground Service]
QSS[QuickSettings Tile]
end
subgraph "Protocol Managers"
BLE_MGR[BLEManager<br/>Scans BLE broadcasts]
AACP[AACPManager<br/>AACP Protocol Handler]
ATT_MGR[ATTManager<br/>Hearing Aid/Transparency]
CROSS[CrossDevice<br/>Multi-device sync]
end
subgraph "Feature Handlers"
BATTERY[BatteryNotification]
EAR_DET[Ear Detection]
GESTURE[GestureDetector<br/>Head Gestures]
MEDIA[MediaController<br/>Play/Pause Control]
ISLAND[IslandWindow<br/>Dynamic Island UI]
end
subgraph "System Hooks"
XPOSED[Xposed Module<br/>KotlinModule]
BT_HOOK[Bluetooth Stack Hook<br/>Native C++]
end
end
subgraph "Linux App"
direction TB
subgraph "UI Layer - QML"
MAIN_QML[Main.qml<br/>Settings UI]
TRAY[TrayIconManager<br/>System Tray]
end
subgraph "Core Logic"
TRAY_APP[AirPodsTrayApp<br/>Main Controller]
end
subgraph "Managers"
BLE_L[BleManager<br/>BLE Scanner]
MEDIA_L[MediaController<br/>PulseAudio/Pipewire]
BT_MON[BluetoothMonitor<br/>DBus Monitor]
SLEEP[SystemSleepMonitor]
end
subgraph "Data Models"
DEV_INFO[DeviceInfo<br/>State Management]
BATTERY_L[Battery Model]
end
end
subgraph "Cross-Platform Python Tools"
PROX[proximity_keys.py<br/>Pairing Keys]
HEAD_TRACK[head-tracking/<br/>Visualization Tools]
HEAR_AID[hearing-aid-adjustments.py<br/>Audiogram Config]
end
subgraph "Magisk Module"
ROOT_MOD[root-module/<br/>System Integration]
BUSYBOX[Busybox Tools]
end
%% Android Connections
MA --> APS
QS --> APS
APS --> BLE_MGR
APS --> AACP
APS --> ATT_MGR
APS --> CROSS
APS --> BATTERY
APS --> EAR_DET
APS --> GESTURE
APS --> MEDIA
APS --> ISLAND
XPOSED --> BT_HOOK
BT_HOOK -.->|Patches Bug| APS
%% Linux Connections
MAIN_QML --> TRAY_APP
TRAY --> TRAY_APP
TRAY_APP --> BLE_L
TRAY_APP --> MEDIA_L
TRAY_APP --> BT_MON
TRAY_APP --> DEV_INFO
DEV_INFO --> BATTERY_L
%% Communication with AirPods
BLE_MGR -->|Scans| AP_BLE
BLE_L -->|Scans| AP_BLE
AACP -->|Commands| AP_L2CAP
TRAY_APP -->|L2CAP Socket| AP_L2CAP
ATT_MGR -->|Hearing Aid Config| AP_ATT
HEAR_AID -->|Direct Connection| AP_ATT
%% Cross-Device Communication
CROSS <-.->|BLE Advertising<br/>L2CAP Relay| TRAY_APP
%% Python Tools
PROX -->|Generates Keys| AP_L2CAP
HEAD_TRACK -->|Reads Head Tracking| AP_L2CAP
%% Root Module
ROOT_MOD -.->|System App Installation| APS
style AP fill:#1d1d1f,stroke:#86868b,color:#f5f5f7
style AP_BLE fill:#2d2d2f,stroke:#86868b,color:#f5f5f7
style AP_L2CAP fill:#2d2d2f,stroke:#86868b,color:#f5f5f7
style AP_ATT fill:#2d2d2f,stroke:#86868b,color:#f5f5f7
style APS fill:#0071e3,stroke:#0077ed,color:#fff
style AACP fill:#34c759,stroke:#30d158,color:#fff
style XPOSED fill:#ff3b30,stroke:#ff453a,color:#fff
style TRAY_APP fill:#0071e3,stroke:#0077ed,color:#fff
sequenceDiagram
participant User
participant App as LibrePods App
participant BLE as BLE Scanner
participant Service as AirPodsService
participant AACP as AACP Manager
participant L2CAP as L2CAP Socket
participant AirPods
User->>App: Launch App
App->>Service: Start Foreground Service
Service->>BLE: Start BLE Scanning
loop Every 500ms
AirPods->>BLE: Broadcast BLE Advertisement<br/>(Battery, Ear Status)
BLE->>Service: Parse & Update UI
end
Note over AirPods,Service: Device Connection Phase
User->>Service: Pair AirPods
Service->>L2CAP: Create Socket (PSM 0x1001)
L2CAP->>AirPods: Connect
AirPods-->>L2CAP: Connected
Service->>AACP: Send Handshake
AACP->>L2CAP: 00 00 04 00 01 00 02 00...
L2CAP->>AirPods: Handshake Packet
Service->>AACP: Request Notifications
AACP->>L2CAP: 04 00 04 00 0F 00 FF FF...
Service->>AACP: Set Feature Flags
AACP->>L2CAP: 04 00 04 00 4D 00 FF 00...
Note over AirPods,Service: Normal Operation
loop Continuous Updates
AirPods->>L2CAP: Battery Update
L2CAP->>AACP: Parse Packet
AACP->>Service: Update Battery
Service->>User: Show Notification
AirPods->>L2CAP: Ear Detection Event
L2CAP->>AACP: Parse Packet
AACP->>Service: Left/Right In Ear Status
Service->>App: Play/Pause Media
end
Note over User,AirPods: User Changes Noise Control
User->>App: Tap Noise Control
App->>Service: Change ANC Mode
Service->>AACP: Build Control Packet
AACP->>L2CAP: 04 00 04 00 09 00 0D...
L2CAP->>AirPods: Set Noise Control
AirPods-->>L2CAP: Confirmation
L2CAP-->>AACP: Parse Response
AACP-->>Service: Update State
Service-->>App: Update UI
| Component | Responsibility | Key Files |
|---|---|---|
| AirPodsService | Main orchestrator, manages lifecycle | AirPodsService.kt |
| AACPManager | Handles AACP protocol, packet construction | AACPManager.kt |
| BLEManager | Scans for BLE advertisements | BLEManager.kt |
| ATTManager | Handles ATT protocol for hearing aid | ATTManager.kt |
| GestureDetector | Detects head nods/shakes for call control | GestureDetector.kt |
| CrossDevice | Enables multi-device connectivity | CrossDevice.kt |
| Xposed Module | Hooks Bluetooth stack to fix Android bug | KotlinModule.kt, native code |
| Component | Responsibility | Key Files |
|---|---|---|
| AirPodsTrayApp | Main controller, manages connections | main.cpp |
| BleManager | Scans BLE advertisements | ble/blemanager.cpp |
| MediaController | Controls PulseAudio/Pipewire | media/mediacontroller.cpp |
| BluetoothMonitor | Monitors DBus for Bluetooth events | BluetoothMonitor.cpp |
| TrayIconManager | System tray integration | trayiconmanager.cpp |
- Purpose: Broadcast battery, ear detection, lid state
- Manufacturer ID: 0x004C (Apple)
- Update Frequency: ~500ms
- No encryption required
- Transport: L2CAP Socket (PSM 0x1001)
- Direction: Bidirectional
- Features: Noise control, rename, settings, head tracking
- Packet Format:
04 00 04 00 [opcode] [payload_length] [payload]
- Transport: L2CAP Socket (PSM 0x001F)
- Purpose: Hearing aid configuration, transparency customization
- Handles: 0x18 (transparency), 0x1B (loud sound), 0x2A (hearing aid)
For complete protocol specifications, see ARCHITECTURE.md and AAP Definitions.md
- AAP Definitions.md: Complete AACP protocol specification
- Proximity Pairing Message.md: BLE broadcast format
- control_commands.md: Control command reference
To unlock special features (multi-device connectivity, hearing aid, custom transparency), you need to change your device's Bluetooth Device ID (DID) to Apple's.
- Open LibrePods Settings
- Enable "Act as Apple Device"
- Restart Bluetooth
Edit /etc/bluetooth/main.conf:
[General]
DeviceID = bluetooth:004C:0000:0000Then restart Bluetooth:
sudo systemctl restart bluetoothWhat this enables:
- ✅ Multi-device connectivity (connect to 2 devices simultaneously)
- ✅ Full hearing aid configuration
- ✅ Custom transparency mode settings
- ✅ Seamless device switching with "Move to [Device]" notifications
Once acting as an Apple device, you can connect your AirPods to both Android and Linux simultaneously!
How it works:
- Both devices advertise themselves as Apple devices
- AirPods maintain connections to both
- When one device starts playing audio, it takes control
- Other device receives a notification (just like on Apple devices)
- Cross-device protocol coordinates state between devices
Requirements: Android 10+ (API 29+)
Setup:
- Enable "Head Gestures" in settings
- Test gestures in the Head Tracking screen
- During incoming call:
- Nod Yes (down-up): Answer call
- Shake No (left-right): Reject call
How it works: LibrePods reads head tracking data from AirPods Pro and uses machine learning to detect intentional gestures.
python3 proximity_keys.py [AIRPODS_MAC_ADDRESS]Generates pairing keys for advanced features.
cd head-tracking
pip install -r requirements.txt
python plot.py [AIRPODS_MAC_ADDRESS]Real-time visualization of head movements (great for debugging gestures).
python linux/hearing-aid-adjustments.py [AIRPODS_MAC_ADDRESS]Configure audiogram and hearing aid settings from command line.
Q: Is this legal?
A: Yes. LibrePods uses publicly available Bluetooth protocols and reverse engineering for interoperability, which is legal in most jurisdictions.
Q: Will this damage my AirPods?
A: No. LibrePods only sends standard Bluetooth commands that AirPods are designed to receive.
Q: Can I still use my AirPods with Apple devices?
A: Absolutely! LibrePods doesn't modify your AirPods. They work normally with all devices.
Q: Why do I need root?
A: Android has a bug in the Bluetooth stack that prevents L2CAP connections to AirPods. Root + Xposed allows us to patch this bug at runtime.
Q: Will Android ever fix the bug?
A: We're actively reporting it to Google (Issue #371713238). Please upvote to help!
Q: What about non-root methods?
A: We previously supported overlayfs patching, but it was unreliable across devices. Xposed provides the most stable solution.
Q: Why does renaming require re-pairing?
A: The name is stored in Bluetooth cache. Android only refreshes this cache when you re-pair.
Q: Can I use this on Android 12 or below?
A: Not currently. The app requires Android 13+ APIs. We may add support in the future.
Q: Which desktop environments are supported?
A: LibrePods works on any DE with system tray support (GNOME with extension, KDE, XFCE, etc.).
Q: Does it work with Pipewire?
A: Yes! LibrePods supports both PulseAudio and Pipewire.
Q: Can I use it on Wayland?
A: Yes, fully compatible with Wayland.
Q: Do all features work on all AirPods models?
A: Most features are universal, but some (adaptive transparency, conversation awareness) require AirPods Pro 2.
Q: Why doesn't conversational awareness work sometimes?
A: Ensure you've sent the feature flags packet (done automatically after connection).
Q: Can I use hearing aid mode without professional hearing test?
A: Technically yes, but it's strongly recommended to use actual audiogram results for safety and effectiveness.
Q: Does multi-device work with iPhone?
A: No, only between LibrePods instances (Android ↔ Linux, Android ↔ Android).
We welcome contributions! LibrePods is a community-driven project.
- Report Bugs: Open an issue with details about your device and the problem
- Suggest Features: Share your ideas in discussions
- Improve Documentation: Help make our docs clearer
- Submit Code: Fork, branch, code, test, and open a PR
git clone https://github.com/kavishdevar/librepods.git
cd librepods/android
# Open in Android Studiogit clone https://github.com/kavishdevar/librepods.git
cd librepods/linux
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make- Kotlin: Follow Android Kotlin style guide
- C++: Follow Qt coding conventions
- Python: Follow PEP 8
- Test on multiple AirPods models if possible
- Verify all features work after changes
- Check for memory leaks (Android Profiler / Valgrind)
- Test cross-device scenarios
- 📱 Support for more Android versions
- 🐧 New Linux app development
- 🎧 Testing on different AirPods models
- 📝 Documentation improvements
- 🌍 Translations
- 🔬 Protocol reverse engineering
LibrePods is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0.
LibrePods - AirPods liberated from Apple's ecosystem
Copyright (C) 2025 LibrePods Contributors
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
A huge thank you to everyone supporting the project!
- Contributors: Everyone who has submitted code, bug reports, or ideas
- Testers: Users who help test new features and report issues
- Community: Everyone in discussions helping each other
- ⭐ Star this repository
- 🐛 Report bugs you encounter
- 💡 Share feature ideas
- 📣 Spread the word about LibrePods
- 💰 Sponsor development (See FUNDING.yml)
- GitHub: github.com/kavishdevar/librepods
- Releases: Latest APKs and builds
- Issues: Bug reports and feature requests
- Discussions: Community forum
- Protocol Docs: AAP Definitions | BLE Format
- Architecture: System Design
-
Bluetooth Toggle: If the app stops working, toggle Bluetooth off and on, or restart the Bluetooth service.
-
A2DP Re-connection: When AirPods are removed, the app disconnects A2DP to prevent Android from auto-reconnecting. This is normal behavior.
-
System App Installation: For full integration (battery in Android settings, icon in Bluetooth menu), install as system app using the provided Magisk module.
-
Loud Sound Reduction: Recent firmware requires enabling "Off listening mode" to use the "Off" noise control mode (loud sounds are NOT reduced in this mode).
-
Debug Logging: Enable debug logging in app settings to troubleshoot issues. Logs can be exported and shared with developers.









