librepods icon indicating copy to clipboard operation
librepods copied to clipboard
Published 2 weeks ago • verified publisher icon kavishdevar

Create a Compatibility Matrix & User-Reporting Template (Based on Key Features)

Open chrisdebian opened this issue 1 month ago • 1 comments

As LibrePods continues to grow across different Android versions, devices, and AirPods models, it’s becoming increasingly important to have a clear overview of what works where, especially since the project already implements a wide range of features (as listed in the README).

Right now, many issues arise from device-specific behaviour or incomplete support on certain AirPods generations. A structured Compatibility Matrix, combined with a User-Reporting Template, would make it much easier for users to self-diagnose, and for maintainers to identify recurring patterns.

🎯 Why this is useful

  • Users can quickly check compatibility before opening an issue.

  • Maintainers get consistent, structured data in bug reports.

  • Makes it easier to identify trends such as:

    • “ANC not working on AirPods Pro 2 + Android 14 on Samsung devices”
    • “Case battery not reported on certain chipsets”

  • Helps steer development by highlighting where gaps exist.

📘 Incorporating the Project’s Key Features

The README lists the following key features:

  • Automatic Ear Detection (AED)
  • Automatic ANC and Transparency Mode Control
  • Battery Level and Case Detection
  • Double/Triple Tap Gesture Support
  • Spatial Audio Support (if applicable)
  • Device Status Reporting
  • AirPods Firmware Information
  • Adaptive Noise Control (on supported models)

To help users understand which of these work on their setup, the compatibility matrix should reflect the support status of each feature per:

  • Device model
  • Android version
  • Root / Magisk / LSPosed / rootless status
  • AirPods model (Gen1/2/3, Pro/Pro2, Max)
  • LibrePods version

✅ Suggested Actions

⬜ 1. Add a Compatibility Matrix to the documentation

The matrix could cover the following:

Columns (features):

  • Automatic Ear Detection
  • ANC / Transparency Controls
  • Automatic Mode Switching
  • Battery Levels (L / R / Case)
  • Gesture Controls
  • Spatial Audio Indicators / Settings
  • Firmware Info Support
  • Adaptive Noise Control
  • L2CAP-dependent features
  • Root-only enhancements

Rows (environment):

  • Phone model
  • Chipset
  • Android version
  • Root/no-root
  • AirPods model

A file such as: /docs/compatibility.md or a GitHub Wiki page would work well.

⬜ 2. Add a User-Reporting Template for issue submissions

A structured template will ensure bug reports are complete and actionable.

Suggested template:

### Device & Environment
**Device model:**  
**Chipset (if known):**  
**Android version:**  
**Root status:** (Root / Magisk / LSPosed / Rootless)  
**Bluetooth stack modifications (if any):**  
**LibrePods version:**  

### AirPods Information
**AirPods model:**  
**Firmware version (if shown):**  

### Expected behaviour:
<describe what you expected to happen>

### Actual behaviour:
<describe what happened instead>

### Features affected:
- [ ] Automatic Ear Detection  
- [ ] ANC / Transparency  
- [ ] Gesture controls  
- [ ] Battery reporting  
- [ ] Spatial Audio features  
- [ ] Firmware info  
- [ ] Adaptive Noise Control  
- [ ] Other:

### Logs (if available):
<attach or paste>

⬜ 3. Add a brief “How to collect logs” guide

This will reduce repetitive questions and improve debugging quality.

📌 Closing Thoughts

By aligning the Compatibility Matrix with the README’s key feature list, users and contributors get a clear, accurate picture of real-world support. It will also reduce friction in bug reports and make the maintenance burden lighter overall.

chrisdebian avatar Dec 04 '25 15:12 chrisdebian

An example of a a clean, readable Markdown Compatibility Matrix designed specifically for LibrePods and the AirPods feature set listed in the README.

You can paste this into:

  • docs/compatibility.md

  • the project Wiki

It’s designed so you can extend rows as community reports come in.

📊 LibrePods Compatibility Matrix

This matrix helps track feature support across devices, Android versions, and AirPods models.
Rows can be added as users report their setups.

Legend

Symbol Meaning
✅ Fully works
⚠️ Partially works / inconsistent
❌ Not supported
? Unknown / untested

Device & Feature Support Matrix

Table 1 — AirPods Feature Support by Device / OS / Root Status

(This is a template — fill in as reports arrive)

| Device Model | Android Version | Root Status | AirPods Model | AED | ANC/Transparency | Auto Mode Switch | Battery Levels | Case Battery | Gestures | Spatial Audio | Firmware Info | Adaptive Noise Control | Notes |
|--------------|-----------------|-------------|----------------|-----|------------------|------------------|----------------|--------------|----------|----------------|----------------|-------------------------|-------|
| Pixel 6      | 14              | Rootless    | AirPods Pro 2  | ⚠️  | ⚠️               | ❌               | ✅             | ⚠️           | ⚠️       | ❌             | ⚠️            | ❌                      | Example row |
| Pixel 7 Pro  | 14              | Magisk + LSPS | AirPods Pro   | ✅  | ✅               | ⚠️               | ✅             | ⚠️           | ⚠️       | ❌             | ⚠️            | ❌                      | L2CAP stable |
| Samsung S22  | 13              | Rootless    | AirPods Gen 2  | ⚠️  | ❌               | ❌               | ⚠️           | ❌           | ⚠️       | ❌             | ⚠️            | ❌                      | Vendor BT stack limitations |
| OnePlus 9    | 14              | Root        | AirPods 3      | ⚠️  | ⚠️               | ⚠️               | ⚠️           | ⚠️           | ⚠️       | ❌             | ❌             | ❌                      | Requires logs |

Table 2 — Feature Definitions (for contributors)

| Feature | Definition |
|---------|------------|
| AED | Automatic Ear Detection; triggers pausing/resuming media. |
| ANC/Transparency | Manual or automatic toggling of noise control modes. |
| Auto Mode Switch | Automatic switching between ANC <-> Transparency based on usage. |
| Battery Levels | Reporting L/R earbuds battery. |
| Case Battery | Reporting charging case battery. |
| Gestures | Double/triple tap or squeeze gestures. |
| Spatial Audio | Detecting spatial-audio capability or showing relevant status. |
| Firmware Info | Retrieving firmware version and hardware identifiers. |
| Adaptive Noise Control | Apple’s dynamic noise adaptation on newer models. |

Table 3 — Bluetooth Stack / Integration Notes

If you want a table specifically for debugging OS-level integration:

| Device | Bluetooth Stack | Vendor Customizations | L2CAP Behaviour | Notes |
|--------|------------------|------------------------|------------------|-------|
| Pixel 7 | AOSP | None | Stable | Good baseline |
| Samsung S22 | Samsung OneUI stack | Heavy modifications | ⚠️ frequent L2CAP failures | Known issue path |
| Xiaomi Poco F5 | MIUI | Medium | ⚠️ unstable | Logs needed |

Optional — Community Submission Template

This goes above or below the matrix to standardize reports:

### Add Your Device (Copy & Fill In)





Device Model
Android Version
Root Status
AirPods Model
AED
ANC/Transparency
Auto Mode Switch
Battery Levels
Case Battery
Gestures
Spatial Audio
Firmware Info
Adaptive Noise Control
Notes






<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>

chrisdebian avatar Dec 04 '25 16:12 chrisdebian