diff --git a/.github/workflows/ci-android.yml b/.github/workflows/ci-android.yml index 9d098a30..269b6700 100644 --- a/.github/workflows/ci-android.yml +++ b/.github/workflows/ci-android.yml @@ -19,7 +19,17 @@ on: type: string workflow_call: -jobs: +jobs: + linting: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: use DavidAnson/markdownlint-action + uses: DavidAnson/markdownlint-cli2-action@v21 + continue-on-error: true + with: + globs: '**/*.md' build-debug-apk: runs-on: ubuntu-latest steps: diff --git a/.github/workflows/ci-linux-rust.yml b/.github/workflows/ci-linux-rust.yml index 8766299f..35a51919 100644 --- a/.github/workflows/ci-linux-rust.yml +++ b/.github/workflows/ci-linux-rust.yml @@ -12,6 +12,16 @@ on: workflow_dispatch: jobs: + linting: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: use DavidAnson/markdownlint-action + uses: DavidAnson/markdownlint-cli2-action@v21 + continue-on-error: true + with: + globs: '**/*.md' build: runs-on: ubuntu-latest diff --git a/.github/workflows/ci-linux.yml b/.github/workflows/ci-linux.yml index a26b3ba1..eec6dba7 100644 --- a/.github/workflows/ci-linux.yml +++ b/.github/workflows/ci-linux.yml @@ -7,6 +7,17 @@ on: # - '*' jobs: + linting: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: use DavidAnson/markdownlint-action + uses: DavidAnson/markdownlint-cli2-action@v21 + continue-on-error: true + with: + globs: '**/*.md' + build-linux: runs-on: ubuntu-latest diff --git a/AAP Definitions.md b/AAP Definitions.md index 87b23d90..344b8110 100644 --- a/AAP Definitions.md +++ b/AAP Definitions.md @@ -2,35 +2,42 @@ AAP runs on top of L2CAP, with a PSM of 0x1001 or 4097. -# Handshake +## Handshake + This packet is necessary to establish a connection with the AirPods. Or else, the AirPods will not respond to any packets. ```plaintext 00 00 04 00 01 00 02 00 00 00 00 00 00 00 00 00 ``` -# Setting specific features for AirPods Pro 2 +## Setting specific features for AirPods Pro 2 > *may work for airpods 4 anc also, not tested* -Since apple likes to wall off some features behind specific OS versions, and apple silicon devices, some packets are necessary to enable these features. +Since Apple likes to wall off some features behind specific OS versions, and Apple silicon devices, some packets are +necessary to enable these features. -I captured the following packet only accidentally, because Apple being Apple decided to hide *this* and *the handshake* from packetlogger, but sometimes it shows up. +I captured the following packet only accidentally, because Apple being Apple decided to hide *this* and *the +handshake* from packetlogger, but sometimes it shows up. *Captured using PacketLogger on an Intel Mac running macOS Sequoia 15.0.1* + ```plaintext 04 00 04 00 4d 00 ff 00 00 00 00 00 00 00 ``` This packet enables conversational awareness when playing audio. (CA works without this packet only when no audio is playing) -It also enables the Adaptive Transparency feature. (We can set Adaptive Transparency, but it doesn't respond with the same packet See [Noise Cancellation](#changing-noise-control)) +It also enables the Adaptive Transparency feature. (We can set Adaptive Transparency, but it doesn't respond with the +same packet See [Noise Cancellation](#changing-noise-control)) -# Requesting notifications +## Requesting notifications -This packet is necessary to receive notifications from the AirPods like ear detection, noise control mode, conversational awareness, battery status, etc. +This packet is necessary to receive notifications from the AirPods like ear detection, noise control mode, +conversational awareness, battery status, etc. *Captured using PacketLogger on an Intel Mac running macOS Sequoia 15.0.1* + ```plaintext 04 00 04 00 0F 00 FF FF FE FF ``` @@ -41,7 +48,7 @@ This packet also works. 04 00 04 00 0F 00 FF FF FF FF ``` -# Notifications +## Notifications ## Battery @@ -64,7 +71,6 @@ AirPods occasionally send battery status packets. The packet format is as follow | Discharging | 02 | | Disconnected | 04 | - Example packet from AirPods Pro 2 ```plaintext @@ -92,7 +98,8 @@ Example packet from AirPods Pro 2 ## Noise Control -The AirPods Pro 2 send noise control packets when the noise control mode is changed (either by a stem long press or by the connected device, see [Changing noise control](#changing-noise-control)). The packet format is as follows: +The AirPods Pro 2 send noise control packets when the noise control mode is changed (either by a stem long press or +by the connected device, see [Changing noise control](#changing-noise-control)). The packet format is as follows: ```plaintext 04 00 04 00 09 00 0D [mode] 00 00 00 @@ -108,11 +115,13 @@ The AirPods Pro 2 send noise control packets when the noise control mode is chan ## Ear Detection AirPods send ear detection packets when the ear detection status changes. The packet format is as follows: + ```plaintext 04 00 04 00 06 00 [primary pod] [secondary pod] ``` -If primary is removed, mic will be changed and the secondary will be the new primary, so the primary will be the one in the ear, and the packet will be sent again. +If primary is removed, mic will be changed and the secondary will be the new primary, so the primary will be the one +in the ear, and the packet will be sent again. | Pod Status | Byte value | |------------|------------| @@ -134,9 +143,11 @@ AirPods send conversational awareness packets when the person wearing them start | 03 | Person Stopped Speaking; increase volume back to normal | | Intermediate values | Intermediate volume levels | | 08/09 | Normal Volume | + ### Reading Conversational Awareness State -After requesting notifications, the AirPods send a packet indicating the current state of Conversational Awareness (CA). This packet is only sent once after notifications are requested, not when the CA state is changed. +After requesting notifications, the AirPods send a packet indicating the current state of Conversational Awareness +(CA). This packet is only sent once after notifications are requested, not when the CA state is changed. The packet format is: @@ -145,14 +156,16 @@ The packet format is: ``` - `[status]` is a single byte at offset 7 (zero-based), immediately after the header. - - `0x01` — Conversational Awareness is **enabled** - - `0x02` — Conversational Awareness is **disabled** - - Any other value — Unknown/undetermined state + - `0x01` — Conversational Awareness is **enabled** + - `0x02` — Conversational Awareness is **disabled** + - Any other value — Unknown/undetermined state **Example:** + ```plaintext 04 00 04 00 09 00 28 01 00 00 00 ``` + Here, `01` at the 8th byte (offset 7) means CA is enabled. ## Metadata @@ -166,7 +179,7 @@ This packet contains device information like name, model number, etc. The packet The strings are null-terminated UTF-8 strings in the following order: 1. Bluetooth advertising name (varies in length) -2. Model number +2. Model number 3. Manufacturer 4. Serial number 5. Firmware version @@ -180,15 +193,16 @@ The strings are null-terminated UTF-8 strings in the following order: 13. Additional encrypted data Example packet: + ```plaintext 040004001d0002d5000400416972506f64732050726f004133303438004170706c6520496e632e0051584e524848595850360036312e313836383034303030323030303030302e323731330036312e313836383034303030323030303030302e3237313300312e302e3000636f6d2e6170706c652e6163636573736f72792e757064617465722e6170702e3731004859394c5432454632364a59004833504c5748444a32364b3000363335373533360089312a6567a5400f84a3ca234947efd40b90d78436ae5946748d70273e66066a2589300035333935303630363400``` The packet contains device identification and version information followed by some encrypted data whose format is not known. ``` -# Writing to the AirPods +## Writing to the AirPods -## Changing Noise Control +### Changing Noise Control We can send a packet to change the noise control mode. The packet format is as follows: @@ -205,7 +219,8 @@ We can send a packet to change the noise control mode. The packet format is as f The airpods will respond with the same packet after the mode has been changed. -> But if your airpods support Adaptive Transparency, and you haven't sent that [special packet](#setting-specific-features-for-airpods-pro-2) to enable it, the airpods will respond with the same packet but with a different mode (like 0x02). +> But if your airpods support Adaptive Transparency, and you haven't sent that [special packet](#setting-specific-features-for-airpods-pro-2) +to enable it, the airpods will respond with the same packet but with a different mode (like 0x02). ## Renaming AirPods @@ -217,9 +232,11 @@ We can send a packet to rename the AirPods. The packet format is as follows: ## Toggle case charging sounds -> *This feature is only for cases with a speaker, i.e. the AirPods Pro 2 and the new AirPods 4. Tested only on AirPods Pro 2* +> *This feature is only for cases with a speaker, i.e. the AirPods Pro 2 and the new AirPods 4. Tested only on +AirPods Pro 2* -We can send a packet to toggle if sounds should be played when the case is connected to a charger. The packet format is as follows: +We can send a packet to toggle if sounds should be played when the case is connected to a charger. The packet +format is as follows: ```plaintext 12 3A 00 01 00 08 [setting] @@ -234,7 +251,9 @@ We can send a packet to toggle if sounds should be played when the case is conne > *This feature is only for AirPods Pro 2 and the new AirPods 4 with ANC. Tested only on AirPods Pro 2* -We can send a packet to toggle Conversational Awareness. If enabled, the AirPods will switch to Transparency mode when the person wearing them starts speaking (and sends packet for notifying the device to reduce volume). The packet format is as follows: +We can send a packet to toggle Conversational Awareness. If enabled, the AirPods will switch to Transparency mode +when the person wearing them starts speaking (and sends packet for notifying the device to reduce volume). The +packet format is as follows: ```plaintext 04 00 04 00 09 00 28 [setting] 00 00 00 @@ -249,22 +268,27 @@ We can send a packet to toggle Conversational Awareness. If enabled, the AirPods > *This feature is only for AirPods Pro 2 and the new AirPods 4 with ANC. Tested only on AirPods Pro 2* -The new firmware `7A305` for app2 has a new feature called Adaptive Audio Noise. This allows us to control how much noise is passed through the AirPods when the noise control mode is set to Adaptive. The packet format is as follows: +The new firmware `7A305` for app2 has a new feature called Adaptive Audio Noise. This allows us to control how +much noise is passed through the AirPods when the noise control mode is set to Adaptive. The packet format is as follows: ```plaintext 04 00 04 00 09 00 2E [level] 00 00 00 ``` -The level can be any value between 0 and 100, 0 to allow maximum noise (i.e. minimum noise filtering), and 100 to filter out more noise. +The level can be any value between 0 and 100, 0 to allow maximum noise (i.e. minimum noise filtering), and 100 to +filter out more noise. > This feature is only effective when the noise control mode is set to Adaptive. -*I find it quite funny how I have greater control over the noise control on the AirPods on non-Apple devices than on Apple devices, becuase on Apple Devices, there are just 3 options More Noise (0), Midway through (50), and Less Noise (100), but here I can set any value between 0 and 100.* +*I find it quite funny how I have greater control over the noise control on the AirPods on non-Apple devices than +on Apple devices, becuase on Apple Devices, there are just 3 options More Noise (0), Midway through (50), and Less +Noise (100), but here I can set any value between 0 and 100.* ## Accessiblity Settings ## Headphone Accomodation -``` + +```plaintext 04 00 04 00 53 00 84 00 02 02 [Phone] [Media] [EQ1][EQ2][EQ3][EQ4][EQ5][EQ6][EQ7][EQ8] duplicated thrice for some reason @@ -278,7 +302,7 @@ duplicated thrice for some reason ## Customize Transparency mode -``` +```plaintext 12 18 00 [enabled] [EQ1][EQ2][EQ3][EQ4][EQ5][EQ6][EQ7][EQ8] @@ -289,8 +313,8 @@ duplicated thrice for some reason ``` - All values are formatted as IEEE 754 floats in little endian order. + | Data | Type | Range | |-------------------------|---------------|-------| | Enabled | IEEE754 Float | 0/1 | @@ -304,12 +328,16 @@ All values are formatted as IEEE 754 floats in little endian order. > [!IMPORTANT] > Also send the [Headphone Accomodation](#headphone-accomodation) after this. - ## Configure Stem Long Press -I have noted all the packets sent to configure what the press and hold of the steam should do. The packets sent are specific to the current state. And are probably overwritten everytime the AirPods are connected to a new (apple) device that is not synced with icloud (i think)... So, for non-Apple devices too, the configuration needs to be stored and overwritten everytime the AirPods are connected to the device. That is the only way to keep the configuration. +I have noted all the packets sent to configure what the press and hold of the steam should do. The packets sent +are specific to the current state. And are probably overwritten everytime the AirPods are connected to a new +(Apple) device that is not synced with icloud (i think)... So, for non-Apple devices too, the configuration needs +to be stored and overwritten everytime the AirPods are connected to the device. That is the only way to keep the +configuration. -This is also the only way to control the configuration as the previous state needs to be known, and then the new state can be set. +This is also the only way to control the configuration as the previous state needs to be known, and then the new +state can be set. The packets sent (based on the previous states) are as follows: @@ -375,11 +403,12 @@ The packets sent (based on the previous states) are as follows: > *i do hate apple for not hardcoding these, like there are literally only 4^2 - ${\binom{4}{1}}$ - $\binom{4}{2}$* -# Head Tracking +## Head Tracking -## Start Tracking +### Start Tracking -This packet initiates head tracking. When sent, the AirPods begin streaming head tracking data (e.g. orientation and acceleration) for live plotting and analysis. +This packet initiates head tracking. When sent, the AirPods begin streaming head tracking data (e.g. orientation +and acceleration) for live plotting and analysis. ```plaintext 04 00 04 00 17 00 00 00 10 00 10 00 08 A1 02 42 0B 08 0E 10 02 1A 05 01 40 9C 00 00 @@ -392,6 +421,7 @@ This packet stops the head tracking data stream. ```plaintext 04 00 04 00 17 00 00 00 10 00 11 00 08 7E 10 02 42 0B 08 4E 10 02 1A 05 01 00 00 00 00 ``` + ## Received Head Tracking Sensor Data Once tracking is active, the AirPods stream sensor packets with the following common structure: diff --git a/CHANGELOG.md b/CHANGELOG.md index 51c6fa8f..4a51127b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,3 @@ ## LibrePods root module changelog + _[See here](https://github.com/kavishdevar/librepods/releases)_ diff --git a/README.md b/README.md index 69a7cbf7..1746f8a1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,10 @@ ## What is LibrePods? -LibrePods unlocks Apple's exclusive AirPods features on non-Apple devices. Get access to noise control modes, adaptive transparency, ear detection, hearing aid, customized transparency mode, battery status, and more - all the premium features you paid for but Apple locked to their ecosystem. +Troubleshooting +LibrePods unlocks Apple's exclusive AirPods features on non-Apple devices. Get access to noise control modes, +adaptive transparency, ear detection, hearing aid, customized transparency mode, battery status, and more - all the +premium features you paid for but Apple locked to their ecosystem. ## Device Compatibility @@ -13,12 +16,15 @@ LibrePods unlocks Apple's exclusive AirPods features on non-Apple devices. Get a | ✅ | AirPods Max | Fully supported (client shows unsupported features) | | ⚠️ | Other AirPods models | Basic features (battery status, ear detection) should work | -Most features should work with any AirPods. Currently, I've only got AirPods Pro 2 to test with. But, I believe the protocol remains the same for all other AirPods (based on analysis of the bluetooth stack on macOS). +Most features should work with any AirPods. Currently, I've only got AirPods Pro 2 to test with. But, I believe the +protocol remains the same for all other AirPods (based on analysis of the bluetooth stack on macOS). ## Key Features -- **Noise Control Modes**: Easily switch between noise control modes without having to reach out to your AirPods to long press -- **Ear Detection**: Controls your music automatically when you put your AirPods in or take them out, and switch to phone speaker when you take them out +- **Noise Control Modes**: Easily switch between noise control modes without having to reach out to your AirPods to +long press +- **Ear Detection**: Controls your music automatically when you put your AirPods in or take them out, and switch to +phone speaker when you take them out - **Battery Status**: Accurate battery levels - **Head Gestures**: Answer calls just by nodding your head - **Conversational Awareness**: Volume automatically lowers when you speak @@ -36,7 +42,20 @@ Most features should work with any AirPods. Currently, I've only got AirPods Pro ## Platform Support ### Linux -for the old version see the [Linux README](./linux/README.md). (doesn't have many features, maintainer didn't have time to work on it) + +#### How to install LibrePods on Linux? + +First, you need to clone the entire Git repository. After this, create a build folder inside `linux/` **not in the +root of the repository.** + +Once the folder structure is prepared, run CMake inside the build directory, pointing to the `CMakeLists.txt` file +located in the `linux` folder. + +Next, compile the generated Makefiles created by the previous step. After the compilation finishes, you should have a +`librepods` executable. Running this file completes the setup and starts LibrePods. + +If you need more help, check the [Linux README](./linux/README.md), which provides a more detailed, +copy-and-paste-ready instruction. (doesn't have many features, maintainer didn't have time to work on it) new version in development ([#241](https://github.com/kavishdevar/librepods/pull/241)) @@ -54,51 +73,69 @@ new version in development ([#241](https://github.com/kavishdevar/librepods/pull | ![Customizations 2](./android/imgs/customizations-2.png) | ![accessibility](./android/imgs/accessibility.png) | ![transparency](./android/imgs/transparency.png) | | ![hearing-aid](./android/imgs/hearing-aid.png) | ![hearing-test](./android/imgs/hearing-test.png) | ![hearing-aid-adjustments](./android/imgs/hearing-aid-adjustments.png) | - here's a very unprofessional demo video https://github.com/user-attachments/assets/43911243-0576-4093-8c55-89c1db5ea533 #### Root Requirement -If you are using ColorOS/OxygenOS 16, you don't need root except for customizing transparency mode, setting up hearing aid, and use Bluetooth Multipoint. Changing ANC, conversational awareness, ear detection, and other customizations will work without root. For everyone else: +If you are using ColorOS/OxygenOS 16, you don't need root except for customizing transparency mode, setting up +hearing aid, and use Bluetooth Multipoint. Changing ANC, conversational awareness, ear detection, and other +customizations will work without root. For everyone else: > [!CAUTION] -> **You must have a rooted device with Xposed to use LibrePods on Android.** This is due to a [bug in the Android Bluetooth stack](https://issuetracker.google.com/issues/371713238). Please upvote the issue by clicking the '+1' icon on the IssueTracker page. I don't know a fix for Android versions <13 either. So, this needs a phone running A13+. -> +> **You must have a rooted device with Xposed to use LibrePods on Android.** This is due to a [bug in the Android +Bluetooth stack](https://issuetracker.google.com/issues/371713238). Please upvote the issue by clicking the '+1' icon +on the IssueTracker page. I don't know a fix for Android versions <13 either. So, this needs a phone running A13+. +> > There are **no exceptions** to the root requirement until Google/your OEM figures out a fix. -Until then, you must xposed. I used to provide a non-xposed method too, where the module used overlayfs to replace the bluetooth library with a locally patched one, but that was broken due to how various devices handled overlayfs and a patched library. With xposed, you can also enable the DID hook enabling a few extra features. +Until then, you must Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace +the bluetooth library with a locally patched one, but that was broken due to how various devices handled overlayfs +and a patched library. With xposed, you can also enable the DID hook enabling a few extra features. ## Changing VendorID in the DID profile to that of Apple Turns out, if you change the VendorID in DID Profile to that of Apple, you get access to several special features! -You can do this on Linux by editing the DeviceID in `/etc/bluetooth/main.conf`. Add this line to the config file `DeviceID = bluetooth:004C:0000:0000`. For android you can enable the `act as Apple device` setting in the app's settings. +You can do this on Linux by editing the DeviceID in `/etc/bluetooth/main.conf`. Add this line to the config file +`DeviceID = bluetooth:004C:0000:0000`. For android you can enable the `act as Apple device` setting in the app's settings. ### Multi-device Connectivity -Upto two devices can be simultaneously connected to AirPods, for audio and control both. Seamless connection switching. The same notification shows up on Apple device when Android takes over the AirPods as if it were an Apple device ("Move to iPhone"). Android also shows a popup when the other device takes over. +Upto two devices can be simultaneously connected to AirPods, for audio and control both. Seamless connection +switching. The same notification shows up on Apple device when Android takes over the AirPods as if it were an Apple +device ("Move to iPhone"). Android also shows a popup when the other device takes over. ### Accessibility Settings and Hearing Aid -Accessibility settings like customizing transparency mode (amplification, balance, tone, conversation boost, and ambient noise reduction), and loud sound reduction can be configured. +Accessibility settings like customizing transparency mode (amplification, balance, tone, conversation boost, and +ambient noise reduction), and loud sound reduction can be configured. -All hearing aid customizations can be done from Android (linux soon), including setting the audiogram result. The app doesn't provide a way to take a hearing test because it requires much more precision. It is much better to use an already available audiogram result. +All hearing aid customizations can be done from Android (linux soon), including setting the audiogram result. The app +doesn't provide a way to take a hearing test because it requires much more precision. It is much better to use an +already available audiogram result. #### A few notes -- Due to recent AirPods' firmware upgrades, you must enable `Off listening mode` to switch to `Off`. This is because in this mode, loud sounds are not reduced. +- Due to recent AirPods' firmware upgrades, you must enable `Off listening mode` to switch to `Off`. This is because +in this mode, loud sounds are not reduced. -- If you have take both AirPods out, the app will automatically switch to the phone speaker. But, Android might keep on trying to connect to the AirPods because the phone is still connected to them, just the A2DP profile is not connected. The app tries to disconnect the A2DP profile as soon as it detects that Android has connected again if they're not in the ear. +- If you have take both AirPods out, the app will automatically switch to the phone speaker. But, Android might keep +on trying to connect to the AirPods because the phone is still connected to them, just the A2DP profile is not +connected. The app tries to disconnect the A2DP profile as soon as it detects that Android has connected again if +they're not in the ear. -- When renaming your AirPods through the app, you'll need to re-pair them with your phone for the name change to take effect. This is a limitation of how Bluetooth device naming works on Android. +- When renaming your AirPods through the app, you'll need to re-pair them with your phone for the name change to take +effect. This is a limitation of how Bluetooth device naming works on Android. -- If you want the AirPods icon and battery status to show in Android Settings app, install the app as a system app by using the root module. +- If you want the AirPods icon and battery status to show in Android Settings app, install the app as a system app by +using the root module. ## Supporters A huge thank you to everyone supporting the project! + - @davdroman - @tedsalmon - @wiless @@ -107,6 +144,7 @@ A huge thank you to everyone supporting the project! - @ressiwage ## Special thanks + - @tyalie for making the first documentation on the protocol! ([tyalie/AAP-Protocol-Definition](https://github.com/tyalie/AAP-Protocol-Defintion)) - @rithvikvibhu and folks over at lagrangepoint for helping with the hearing aid feature ([gist](https://gist.github.com/rithvikvibhu/45e24bbe5ade30125f152383daf07016)) - @devnoname120 for helping with the first root patch @@ -141,4 +179,5 @@ 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 . -All trademarks, logos, and brand names are the property of their respective owners. Use of them does not imply any affiliation with or endorsement by them. All AirPods images, symbols, and the SF Pro font are the property of Apple Inc. +All trademarks, logos, and brand names are the property of their respective owners. Use of them does not imply any +affiliation with or endorsement by them. All AirPods images, symbols, and the SF Pro font are the property of Apple Inc. diff --git a/linux/README.md b/linux/README.md index e405b90e..63511959 100644 --- a/linux/README.md +++ b/linux/README.md @@ -9,8 +9,10 @@ A native Linux application to control your AirPods, with support for: - Battery monitoring - Auto play/pause on ear detection - Hearing Aid features - - Supports adjusting hearing aid- amplification, balance, tone, ambient noise reduction, own voice amplification, and conversation boost - - Supports setting the values for left and right hearing aids (this is not a hearing test! you need to have an audiogram to set the values) + - Supports adjusting hearing aid- amplification, balance, tone, ambient noise reduction, own voice amplification, and + conversation boost + - Supports setting the values for left and right hearing aids (this is not a hearing test! you need to have an audiogram + to set the values) - Seamless handoff between Android and Linux ## Prerequisites @@ -31,6 +33,7 @@ A native Linux application to control your AirPods, with support for: sudo dnf install qt6-qtbase-devel qt6-qtconnectivity-devel \ qt6-qtmultimedia-devel qt6-qtdeclarative-devel ``` + 3. OpenSSL development headers ```bash @@ -43,6 +46,7 @@ A native Linux application to control your AirPods, with support for: # For Fedora sudo dnf install openssl-devel ``` + 4. Libpulse development headers ```bash @@ -55,6 +59,7 @@ A native Linux application to control your AirPods, with support for: # For Fedora sudo dnf install pulseaudio-libs-devel ``` + 5. Cmake ```bash @@ -70,16 +75,26 @@ A native Linux application to control your AirPods, with support for: ## Setup -1. Build the application: +1. **Create the build directory** + + Inside the `linux/` folder, create a build directory and enter it: + + ```bash + mkdir build && cd build + ``` + +2. **Build the application** + + Generate the build files using CMake, then compile the application: ```bash - mkdir build - cd build cmake .. make -j $(nproc) ``` -2. Run the application: +3. **Run the application** + + After the compilation has finished, execute the generated script: ```bash ./librepods @@ -89,7 +104,8 @@ A native Linux application to control your AirPods, with support for: ### 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: +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) @@ -131,17 +147,24 @@ systemctl --user enable --now mpris-proxy ## Hearing Aid -To use hearing aid features, you need to have an audiogram. To enable/disable hearing aid, you can use the toggle in the main app. But, to adjust the settings and set the audiogram, you need to use a different script which is located in this folder as `hearing_aid.py`. You can run it with: +To use hearing aid features, you need to have an audiogram. To enable/disable hearing aid, you can use the toggle in +the main app. But, to adjust the settings and set the audiogram, you need to use a different script which is located +in this folder as `hearing_aid.py`. You can run it with: ```bash python3 hearing_aid.py ``` -The script will load the current settings from the AirPods and allow you to adjust them. You can set the audiogram by providing the values for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and right ears. There are also options to adjust amplification, balance, tone, ambient noise reduction, own voice amplification, and conversation boost. +The script will load the current settings from the AirPods and allow you to adjust them. You can set the audiogram by +providing the values for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and right +ears. There are also options to adjust amplification, balance, tone, ambient noise reduction, own voice +amplification, and conversation boost. -AirPods check for the DeviceID characteristic to see if the connected device is an Apple device and only then allow hearing aid features. To set the DeviceID characteristic, you need to add this line to your bluetooth configuration file (usually located at `/etc/bluetooth/main.conf`): +AirPods check for the DeviceID characteristic to see if the connected device is an Apple device and only then allow +hearing aid features. To set the DeviceID characteristic, you need to add this line to your bluetooth configuration +file (usually located at `/etc/bluetooth/main.conf`): -``` +```bash DeviceID = bluetooth:004C:0000:0000 ``` @@ -153,10 +176,17 @@ sudo systemctl restart bluetooth Here, you might need to re-pair your AirPods because they seem to cache this info. -### Troubleshooting +### Airpods disconnect after a time -It is possible that the AirPods disconnect after a short period of time and play the disconnect sound. This is likely due to the AirPods expecting some information from an Apple device. Since I have not implemented everything that an Apple device does, the AirPods may disconnect. You don't need to reconnect them manually; the script will handle reconnection automatically for hearing aid features. So, once you are done setting the hearing aid features, change back the `DeviceID` to whatever it was before. +It is possible that the AirPods disconnect after a short period of time and play the disconnect sound. This is likely +due to the AirPods expecting some information from an Apple device. Since I have not implemented everything that an +Apple device does, the AirPods may disconnect. You don't need to reconnect them manually; the script will handle +reconnection automatically for hearing aid features. So, once you are done setting the hearing aid features, change +back the `DeviceID` to whatever it was before. ### Why a separate script? -Because I discovered that QBluetooth doesn't support connecting to a socket with its PSM, only a UUID can be used. I could add a dependency on BlueZ, but then having two bluetooth interfaces seems unnecessary. So, I decided to use a separate script for hearing aid features. In the future, QBluetooth will be replaced with BlueZ native calls, and then everything will be in one application. +Because I discovered that QBluetooth doesn't support connecting to a socket with its PSM, only a UUID can be used. I +could add a dependency on BlueZ, but then having two bluetooth interfaces seems unnecessary. So, I decided to use a +separate script for hearing aid features. In the future, QBluetooth will be replaced with BlueZ native calls, and +then everything will be in one application.