kavishdevar
Proposal: Create an Official Project Roadmap (Including Technical Debt Items)
Hi, all!
LibrePods has made huge progress recently, with new features, better stability, and growing community involvement. As the project continues to expand across Android versions, devices, Bluetooth stacks, and AirPods generations, I’d like to propose creating an official Roadmap to help guide future development.
A roadmap would help:
clarify short-term vs long-term priorities
give contributors a clear understanding of where help is most useful
make ongoing development more predictable
organise and surface technical debt items that are already known
give new users and potential contributors a big-picture view of where the project is heading
This issue is intended as a friendly suggestion to begin drafting such a roadmap.
🎯 1. High-Level Goals for LibrePods (Proposed Outline)
These could form the top section of the roadmap:
✔ Deliver the best possible AirPods experience on Android & Linux
Including:
reliable connectivity
stable L2CAP channel behaviour
accurate feature emulation
cross-platform parity where possible
✔ Improve user experience and reduce friction
simplify setup (both root and rootless paths)
clearer logs and diagnostics
a unified UI for status, gestures, ANC, battery, etc.
✔ Strengthen maintainability & contributor friendliness
clearer architecture boundaries
better documentation
CI, testing, linting
well-defined release process
✔ Expand device & firmware compatibility
wider Android version support
support for more AirPods models
reduced dependence on root where possible
🔧 2. Incorporate Technical Debt Items Into the Roadmap
The roadmap should also explicitly integrate the existing technical debt categories (summarised from the TECHNICAL DEBT issue). Below is a structured version that fits a roadmap layout.
🧩 A. Architecture & Structure
Refactor platform-specific integrations away from core protocol logic
Introduce a documented module layout / architecture overview
Isolate brittle or experimental code paths (especially root-dependent logic)
🧪 B. Testing & Quality
Build a proper test suite (core protocol + integration tests)
Add CI pipelines for Android, Linux, and root module builds
Improve testability of Bluetooth/L2CAP behaviours (mock or simulate where possible)
📚 C. Documentation & Contributor Experience
Improve developer documentation and build instructions
Add/expand CONTRIBUTING.md
Provide architecture diagrams, lifecycle flows, and code-path explanations
Provide a “How to debug / how to collect logs” guide
🛑 D. Error Handling, Logs & Diagnostics
Improve structured logging
Add debug modes for Bluetooth + protocol flows
Provide troubleshooting documentation
Add consistent error codes or categories for reproducible issues
🚀 E. Release, Versioning & Maintenance
Define stable vs experimental release tracks
Document backward-incompatibility when changes require migrations
Provide a compatibility matrix (now already proposed!)
🗺 3. Suggested Roadmap Structure
If this suggestion is accepted, the roadmap could be published in the repo as either:
ROADMAP.md in the root
a GitHub Projects board
a Wiki page with versioned goals
Structure idea:
Short Term (0–3 months)
CI + linting + static analysis
compatibility matrix
diagnostics improvements
architecture overview documentation
Medium Term (3–9 months)
refactoring core protocol modules
reducing root dependency where possible
stabilising L2CAP on more devices
improving gesture + ANC behaviour on more AirPods models
Long Term (9–18 months)
a unified UX/UI experience
full-feature parity for AirPods Pro 2 where feasible
Linux client maturity
broadened device support via community reporting
long-term maintenance planning
📌 4. Closing Thoughts
Creating an official roadmap would make development clearer for contributors and users, and help prioritise the many excellent ideas already raised. It would also give structure to the technical debt items so they can be tracked in a forward-looking way rather than only as isolated tasks.
Draft roadmap.md
Below is a complete, polished ROADMAP.md that you can drop straight into the repository. It’s written in a friendly, community-oriented style and aligns with:
the project’s goals
the technical debt list
the direction implied by current issues
realistic development phases
You can copy/paste it exactly as-is, if that's easiest?
LibrePods Roadmap
Last updated: (insert date)
This document outlines the planned direction for LibrePods, covering high-level goals, upcoming development milestones, and known areas of technical debt. It is a living document and will evolve as new hardware, Android versions, and community contributions shape the project.
🎯 1. Project Vision
LibrePods aims to provide the best possible AirPods experience outside the Apple ecosystem, while remaining:
Open-source
Cross-platform (Android + Linux)
Customisable
Respectful of user choice (rooted, rootless, and everything in between)
Long-term, the goal is to make LibrePods:
more reliable
easier to install
easier to debug
more feature-complete
more robust across diverse hardware and OEM Bluetooth stacks
🧭 2. Roadmap Overview
The roadmap is divided into:
Short-term goals (0–3 months)
Medium-term goals (3–9 months)
Long-term goals (9–18 months)
Ongoing efforts (continuous work)
Each section links to relevant technical debt items or GitHub issues where appropriate.
🚀 3. Short-Term Goals (0–3 months)
✔ Improve Project Health & Infrastructure
Add CI setup for:
Android build
Linux build
Root module build
Introduce static analysis / linting tools across languages
Add basic unit tests (protocol parsing, state machines, feature flags)
(Related: Technical Debt – Repo Health / CI / Testing)
✔ Documentation & Contributor Experience
Draft full architecture overview
Provide developer setup instructions for:
Android
Linux
Root environment
Add/expand CONTRIBUTING.md
(Technical Debt – Documentation & Architecture)
✔ Diagnostics & Logging Improvements
Add structured logging for Bluetooth, L2CAP, and protocol events
Document how to collect logs and submit good bug reports
Add a “debug mode” toggle for verbose diagnostics
(Technical Debt – Error Handling & Diagnostics)
✔ Compatibility Tracking
Publish a Compatibility Matrix (AirPods model × Device × Android version × Root status)
Add a user-reporting template for consistency
(Already underway thanks to community suggestions!)
⚙️ 4. Medium-Term Goals (3–9 months)
✔ Architecture Refinement
Separate core protocol logic from platform-specific code
Encapsulate brittle system patches / root-only hacks
Reduce cross-module dependencies for easier testing and maintenance
(Technical Debt – Architecture)
✔ Improve Bluetooth & L2CAP Stability
Investigate device-specific instability patterns (Samsung, MIUI, etc.)
Implement fallback or alternate connection strategies
Improve error recovery logic
✔ More Feature Completeness for AirPods
Depending on hardware feasibility:
Improved ANC / Transparency switching
More reliable gesture detection
Spatial audio metadata (presentation only; full support may be limited by OS)
Better firmware information extraction
Adaptive Noise Control (supported models)
(Some of these may require deep reverse engineering or Bluetooth experimentation.)
✔ Reduce Root Dependency Where Possible
Evaluate which features can be made rootless
Document unavoidable root-only features
Experiment with new techniques for Bluetooth metadata extraction
🌟 5. Long-Term Goals (9–18 months)
✔ Unified UX / UI Enhancements
A stable, unified UI for:
mode switching
battery reporting
gestures
status indicators
Improved accessibility and theming
✔ Linux Client Evolution
Improve pairing, status reporting, and feature support on Linux
Work towards distro packaging or Flatpak
Standardise Linux BT integration where possible
✔ Wider Device & Firmware Coverage
Expand and maintain a database of:
device support
problematic chipsets
OEM quirks
Better mitigate differences in Bluetooth stack behaviour
✔ Long-Term Maintainability
Formalise release channels:
Stable
Beta
Nightly / Experimental
Maintain versioned docs
Mature test suite (greater coverage, regression prevention)
🔁 6. Ongoing Efforts
These items are continuous rather than milestone-based:
Respond to Bluetooth stack changes in new Android versions
Investigate regression reports and device-specific edge cases
Integrate community feedback and test results
Keep documentation, compatibility matrix, and troubleshooting guides updated
Ensure root, Magisk, LSPosed, and rootless paths remain functional as ecosystems evolve
🤝 7. How the Community Can Help
Submit logs when reporting issues
Share test results to expand the compatibility matrix
Contribute documentation improvements
Help test features on diverse devices and AirPods models
Participate in discussions around architecture and design
Review pull requests if comfortable with Kotlin / Android internals / Bluetooth
📌 8. Notes & Disclaimer
LibrePods relies on behaviours of proprietary hardware and fragmented Android Bluetooth stacks. Some limitations may be:
hardware-based
firmware-based
undocumented
or blocked by OS/OEM customisations
The roadmap reflects best-effort goals, but feature feasibility may vary.
📝 End of Roadmap
