EarLLM One — Build & Maintain
Overview
Build, maintain, and extend the EarLLM One Android project — a Kotlin/Compose app that connects Bluetooth earbuds to an LLM via voice pipeline.
When to Use This Skill
- When the user mentions "earllm" or related topics
- When the user mentions "earbudllm" or related topics
- When the user mentions "earbud app" or related topics
- When the user mentions "voice pipeline kotlin" or related topics
- When the user mentions "bluetooth audio android" or related topics
- When the user mentions "sco microphone" or related topics
Do Not Use This Skill When
- The task is unrelated to earllm build
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise
How It Works
EarLLM One is a multi-module Android app (Kotlin + Jetpack Compose) that captures voice from Bluetooth earbuds, transcribes it, sends it to an LLM, and speaks the response back.
Project Location
C:\Users\renat\earbudllm
Module Dependency Graph
app ──→ voice ──→ audio ──→ core-logging
│ │
├──→ bluetooth ──→ core-logging
└──→ llm ──→ core-logging
Modules And Key Files
| Module |
Purpose |
Key Files |
| core-logging |
Structured logging, performance tracking |
EarLogger.kt, PerformanceTracker.kt |
| bluetooth |
BT discovery, pairing, A2DP/HFP profiles |
BluetoothController.kt, BluetoothState.kt, BluetoothPermissions.kt |
| audio |
Audio routing (SCO/BLE), capture, headset buttons |
AudioRouteController.kt, VoiceCaptureController.kt, HeadsetButtonController.kt |
| voice |
STT (SpeechRecognizer + Vosk stub), TTS, pipeline |
SpeechToTextController.kt, TextToSpeechController.kt, VoicePipeline.kt |
| llm |
LLM interface, stub, OpenAI-compatible client |
LlmClient.kt, StubLlmClient.kt, RealLlmClient.kt, SecureTokenStore.kt |
| app |
UI, ViewModel, Service, Settings, all screens |
MainViewModel.kt, EarLlmForegroundService.kt, 6 Compose screens |
Build Configuration
- SDK: minSdk 26, targetSdk 34, compileSdk 34
- Build tools: AGP 8.2.2, Kotlin 1.9.22, Gradle 8.5
- Compose BOM: 2024.02.00
- Key deps: OkHttp, AndroidX Security (EncryptedSharedPreferences), DataStore, Media
Target Hardware
| Device |
Model |
Key Details |
| Phone |
Samsung Galaxy S24 Ultra |
Android 14, One UI 6.1, Snapdragon 8 Gen 3 |
| Earbuds |
Xiaomi Redmi Buds 6 Pro |
BT 5.3, A2DP/HFP/AVRCP, ANC, LDAC |
Critical Technical Facts
These are verified facts from official documentation and device testing. Treat them as ground truth when making decisions:
Bluetooth SCO is limited to 8kHz mono input on most devices. Some support 16kHz mSBC. BLE Audio (Android 12+, TYPE_BLE_HEADSET = 26) supports up to 32kHz stereo. Always prefer BLE Audio when available.
startBluetoothSco() is deprecated since Android 12 (API 31). Use AudioManager.setCommunicationDevice(AudioDeviceInfo) and clearCommunicationDevice() instead. The project already implements both paths in AudioRouteController.kt.
Samsung One UI 7/8 has a known HFP corruption bug where A2DP playback corrupts the SCO link. The app handles this with silence detection and automatic fallback to the phone's built-in mic.
Redmi Buds 6 Pro tap controls must be set to "Default" (Play/Pause) in the Xiaomi Earbuds companion app. If set to ANC or custom functions, events are handled internally by the earbuds and never reach Android.
Android 14+ requires FOREGROUND_SERVICE_MICROPHONE permission and foregroundServiceType="microphone" in the service declaration. RECORD_AUDIO must be granted before startForeground().
VOICE_COMMUNICATION audio source enables AEC (Acoustic Echo Cancellation), which is critical to prevent TTS audio output from feeding back into the STT microphone input. Never change this source without understanding the echo implications.
Never play TTS (A2DP) while simultaneously recording via SCO. The correct sequence is: stop playback → switch to HFP → record → switch to A2DP → play response.
Data Flow
Headset button tap
→ MediaSession (HeadsetButtonController)
→ TapAction.RECORD_TOGGLE
→ VoicePipeline.toggleRecording()
→ VoiceCaptureController captures PCM (16kHz mono)
→ stopRecording() returns ByteArray
→ SpeechToTextController.transcribe(pcmData)
→ LlmClient.chat(messages)
→ TextToSpeechController.speak(response)
→ Audio output via A2DP to earbuds
Adding A New Feature
- Identify which module(s) are affected
- Read existing code in those modules first
- Follow the StateFlow pattern — expose state via
MutableStateFlow / StateFlow
- Update
MainViewModel.kt if the feature needs UI integration
- Add unit tests in the module's
src/test/ directory
- Update docs if the feature changes behavior
Modifying Audio Capture
VoiceCaptureController.kt handles PCM recording at 16kHz mono
- WAV headers use hex byte values (not char literals) to avoid shell quoting issues
- VU meter: RMS calculation → dB conversion → normalized 0-1 range
- Buffer size:
getMinBufferSize().coerceAtLeast(4096)
Changing Bluetooth Behavior
BluetoothController.kt manages discovery, pairing, profile proxies
- Earbuds detection uses name heuristics: "buds", "earbuds", "tws", "pods", "ear"
- Always handle both Bluetooth Classic and BLE Audio paths
Modifying The Llm Integration
LlmClient.kt defines the interface — keep it generic
StubLlmClient.kt for offline testing (500ms simulated delay)
RealLlmClient.kt uses OkHttp to call OpenAI-compatible APIs
- API keys stored in
SecureTokenStore.kt (EncryptedSharedPreferences)
Generating A Build Artifact
After code changes, regenerate the ZIP:
## From Project Root
powershell -Command "Remove-Item 'EarLLM_One_v1.0.zip' -Force -ErrorAction SilentlyContinue; Compress-Archive -Path (Get-ChildItem -Exclude '*.zip','_zip_verify','.git') -DestinationPath 'EarLLM_One_v1.0.zip' -Force"
Running Tests
./gradlew test --stacktrace # Unit tests
./gradlew connectedAndroidTest # Instrumented tests (device required)
Phase 2 Roadmap
- Real-time streaming voice conversation with LLM through earbuds
- Smart assistant: categorize speech into meetings, shopping lists, memos, emails
- Vosk offline STT integration (currently stubbed)
- Wake-word detection to avoid keeping SCO open continuously
- Streaming TTS (Android built-in TTS does NOT support streaming)
Stt Engine Reference
| Engine |
Size |
WER |
Streaming |
Best For |
| Vosk small-en |
40 MB |
~10% |
Yes |
Real-time mobile |
| Vosk lgraph |
128 MB |
~8% |
Yes |
Better accuracy |
| Whisper tiny |
40 MB |
~10-12% |
No (batch) |
Post-utterance polish |
| Android SpeechRecognizer |
0 MB |
varies |
Yes |
Online, no extra deps |
Best Practices
- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis
Common Pitfalls
- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
1---2name: earllm-build3description: "Build, maintain, and extend the EarLLM One Android project — a Kotlin/Compose app that connects Bluetooth earbuds to an LLM via voice pipeline."4risk: safe5source: community6date_added: '2026-03-06'7author: renat8tags:9- android10- kotlin11- bluetooth12- llm13- voice14tools:15- claude-code16- antigravity17- cursor18- gemini-cli19- codex-cli20metadata:21 source: https://skillmd.com/skills/mhassan0000/earllm-build22---2324# EarLLM One — Build & Maintain2526## Overview2728Build, maintain, and extend the EarLLM One Android project — a Kotlin/Compose app that connects Bluetooth earbuds to an LLM via voice pipeline.2930## When to Use This Skill3132- When the user mentions "earllm" or related topics33- When the user mentions "earbudllm" or related topics34- When the user mentions "earbud app" or related topics35- When the user mentions "voice pipeline kotlin" or related topics36- When the user mentions "bluetooth audio android" or related topics37- When the user mentions "sco microphone" or related topics3839## Do Not Use This Skill When4041- The task is unrelated to earllm build42- A simpler, more specific tool can handle the request43- The user needs general-purpose assistance without domain expertise4445## How It Works4647EarLLM One is a multi-module Android app (Kotlin + Jetpack Compose) that captures voice from Bluetooth earbuds, transcribes it, sends it to an LLM, and speaks the response back.4849## Project Location5051`C:\Users\renat\earbudllm`5253## Module Dependency Graph5455```56app ──→ voice ──→ audio ──→ core-logging57 │ │58 ├──→ bluetooth ──→ core-logging59 └──→ llm ──→ core-logging60```6162## Modules And Key Files6364| Module | Purpose | Key Files |65|--------|---------|-----------|66| **core-logging** | Structured logging, performance tracking | `EarLogger.kt`, `PerformanceTracker.kt` |67| **bluetooth** | BT discovery, pairing, A2DP/HFP profiles | `BluetoothController.kt`, `BluetoothState.kt`, `BluetoothPermissions.kt` |68| **audio** | Audio routing (SCO/BLE), capture, headset buttons | `AudioRouteController.kt`, `VoiceCaptureController.kt`, `HeadsetButtonController.kt` |69| **voice** | STT (SpeechRecognizer + Vosk stub), TTS, pipeline | `SpeechToTextController.kt`, `TextToSpeechController.kt`, `VoicePipeline.kt` |70| **llm** | LLM interface, stub, OpenAI-compatible client | `LlmClient.kt`, `StubLlmClient.kt`, `RealLlmClient.kt`, `SecureTokenStore.kt` |71| **app** | UI, ViewModel, Service, Settings, all screens | `MainViewModel.kt`, `EarLlmForegroundService.kt`, 6 Compose screens |7273## Build Configuration7475- **SDK**: minSdk 26, targetSdk 34, compileSdk 3476- **Build tools**: AGP 8.2.2, Kotlin 1.9.22, Gradle 8.577- **Compose BOM**: 2024.02.0078- **Key deps**: OkHttp, AndroidX Security (EncryptedSharedPreferences), DataStore, Media7980## Target Hardware8182| Device | Model | Key Details |83|--------|-------|-------------|84| Phone | Samsung Galaxy S24 Ultra | Android 14, One UI 6.1, Snapdragon 8 Gen 3 |85| Earbuds | Xiaomi Redmi Buds 6 Pro | BT 5.3, A2DP/HFP/AVRCP, ANC, LDAC |8687## Critical Technical Facts8889These are verified facts from official documentation and device testing. Treat them as ground truth when making decisions:90911. **Bluetooth SCO is limited to 8kHz mono input** on most devices. Some support 16kHz mSBC. BLE Audio (Android 12+, `TYPE_BLE_HEADSET = 26`) supports up to 32kHz stereo. Always prefer BLE Audio when available.92932. **`startBluetoothSco()` is deprecated since Android 12 (API 31).** Use `AudioManager.setCommunicationDevice(AudioDeviceInfo)` and `clearCommunicationDevice()` instead. The project already implements both paths in `AudioRouteController.kt`.94953. **Samsung One UI 7/8 has a known HFP corruption bug** where A2DP playback corrupts the SCO link. The app handles this with silence detection and automatic fallback to the phone's built-in mic.96974. **Redmi Buds 6 Pro tap controls must be set to "Default" (Play/Pause)** in the Xiaomi Earbuds companion app. If set to ANC or custom functions, events are handled internally by the earbuds and never reach Android.98995. **Android 14+ requires `FOREGROUND_SERVICE_MICROPHONE` permission** and `foregroundServiceType="microphone"` in the service declaration. `RECORD_AUDIO` must be granted before `startForeground()`.1001016. **`VOICE_COMMUNICATION` audio source enables AEC** (Acoustic Echo Cancellation), which is critical to prevent TTS audio output from feeding back into the STT microphone input. Never change this source without understanding the echo implications.1021037. **Never play TTS (A2DP) while simultaneously recording via SCO.** The correct sequence is: stop playback → switch to HFP → record → switch to A2DP → play response.104105## Data Flow106107```108Headset button tap109 → MediaSession (HeadsetButtonController)110 → TapAction.RECORD_TOGGLE111 → VoicePipeline.toggleRecording()112 → VoiceCaptureController captures PCM (16kHz mono)113 → stopRecording() returns ByteArray114 → SpeechToTextController.transcribe(pcmData)115 → LlmClient.chat(messages)116 → TextToSpeechController.speak(response)117 → Audio output via A2DP to earbuds118```119120## Adding A New Feature1211221. Identify which module(s) are affected1232. Read existing code in those modules first1243. Follow the StateFlow pattern — expose state via `MutableStateFlow` / `StateFlow`1254. Update `MainViewModel.kt` if the feature needs UI integration1265. Add unit tests in the module's `src/test/` directory1276. Update docs if the feature changes behavior128129## Modifying Audio Capture130131- `VoiceCaptureController.kt` handles PCM recording at 16kHz mono132- WAV headers use hex byte values (not char literals) to avoid shell quoting issues133- VU meter: RMS calculation → dB conversion → normalized 0-1 range134- Buffer size: `getMinBufferSize().coerceAtLeast(4096)`135136## Changing Bluetooth Behavior137138- `BluetoothController.kt` manages discovery, pairing, profile proxies139- Earbuds detection uses name heuristics: "buds", "earbuds", "tws", "pods", "ear"140- Always handle both Bluetooth Classic and BLE Audio paths141142## Modifying The Llm Integration143144- `LlmClient.kt` defines the interface — keep it generic145- `StubLlmClient.kt` for offline testing (500ms simulated delay)146- `RealLlmClient.kt` uses OkHttp to call OpenAI-compatible APIs147- API keys stored in `SecureTokenStore.kt` (EncryptedSharedPreferences)148149## Generating A Build Artifact150151After code changes, regenerate the ZIP:152```powershell153154## From Project Root155156powershell -Command "Remove-Item 'EarLLM_One_v1.0.zip' -Force -ErrorAction SilentlyContinue; Compress-Archive -Path (Get-ChildItem -Exclude '*.zip','_zip_verify','.git') -DestinationPath 'EarLLM_One_v1.0.zip' -Force"157```158159## Running Tests160161```bash162./gradlew test --stacktrace # Unit tests163./gradlew connectedAndroidTest # Instrumented tests (device required)164```165166## Phase 2 Roadmap167168- Real-time streaming voice conversation with LLM through earbuds169- Smart assistant: categorize speech into meetings, shopping lists, memos, emails170- Vosk offline STT integration (currently stubbed)171- Wake-word detection to avoid keeping SCO open continuously172- Streaming TTS (Android built-in TTS does NOT support streaming)173174## Stt Engine Reference175176| Engine | Size | WER | Streaming | Best For |177|--------|------|-----|-----------|----------|178| Vosk small-en | 40 MB | ~10% | Yes | Real-time mobile |179| Vosk lgraph | 128 MB | ~8% | Yes | Better accuracy |180| Whisper tiny | 40 MB | ~10-12% | No (batch) | Post-utterance polish |181| Android SpeechRecognizer | 0 MB | varies | Yes | Online, no extra deps |182183## Best Practices184185- Provide clear, specific context about your project and requirements186- Review all suggestions before applying them to production code187- Combine with other complementary skills for comprehensive analysis188189## Common Pitfalls190191- Using this skill for tasks outside its domain expertise192- Applying recommendations without understanding your specific context193- Not providing enough project context for accurate analysis194195## Limitations196- Use this skill only when the task clearly matches the scope described above.197- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.198- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.