Skip to content

FISCFED9/CLI / .agents/skills/plugins/antigravity-awesome-skills-claude/skills/earllm-build

earllm-build

Verified

Build, maintain, and extend the EarLLM One Android project — a Kotlin/Compose app that connects Bluetooth earbuds to an LLM via voice pipeline.

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

ModulePurposeKey Files
core-loggingStructured logging, performance trackingEarLogger.kt, PerformanceTracker.kt
bluetoothBT discovery, pairing, A2DP/HFP profilesBluetoothController.kt, BluetoothState.kt, BluetoothPermissions.kt
audioAudio routing (SCO/BLE), capture, headset buttonsAudioRouteController.kt, VoiceCaptureController.kt, HeadsetButtonController.kt
voiceSTT (SpeechRecognizer + Vosk stub), TTS, pipelineSpeechToTextController.kt, TextToSpeechController.kt, VoicePipeline.kt
llmLLM interface, stub, OpenAI-compatible clientLlmClient.kt, StubLlmClient.kt, RealLlmClient.kt, SecureTokenStore.kt
appUI, ViewModel, Service, Settings, all screensMainViewModel.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

DeviceModelKey Details
PhoneSamsung Galaxy S24 UltraAndroid 14, One UI 6.1, Snapdragon 8 Gen 3
EarbudsXiaomi Redmi Buds 6 ProBT 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:

  1. 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.

  2. startBluetoothSco() is deprecated since Android 12 (API 31). Use AudioManager.setCommunicationDevice(AudioDeviceInfo) and clearCommunicationDevice() instead. The project already implements both paths in AudioRouteController.kt.

  3. 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.

  4. 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.

  5. Android 14+ requires FOREGROUND_SERVICE_MICROPHONE permission and foregroundServiceType="microphone" in the service declaration. RECORD_AUDIO must be granted before startForeground().

  6. 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.

  7. 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

  1. Identify which module(s) are affected
  2. Read existing code in those modules first
  3. Follow the StateFlow pattern — expose state via MutableStateFlow / StateFlow
  4. Update MainViewModel.kt if the feature needs UI integration
  5. Add unit tests in the module's src/test/ directory
  6. 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

EngineSizeWERStreamingBest For
Vosk small-en40 MB~10%YesReal-time mobile
Vosk lgraph128 MB~8%YesBetter accuracy
Whisper tiny40 MB~10-12%No (batch)Post-utterance polish
Android SpeechRecognizer0 MBvariesYesOnline, 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
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexVerifiedInstall