Android USB Audio Recorder Context
This skill provides specialized guidance for developing an Android USB audio recorder application focused on 384kHz high-frequency recording and real-time ultrasonic visualization, inspired by BatRecorder app analysis.
Project Description
A new Android application for high-frequency USB audio recording (384kHz sampling rate) with real-time visualization, specifically designed for ultrasonic and bat call recording applications. The project integrates Android USB Host APIs with native C++ processing for optimal performance.
Key Technical Capabilities
USB Audio Architecture
Android USB Host mode (API 26+) for 384kHz audio device supportReal-time USB audio descriptor parsing and device auto-detectionIsochronous USB transfer handling via native librariesDynamic USB device permission managementAudio Processing Pipeline
Native USB audio data acquisition via libusb (C++/JNI)High-performance FFT processing (targeting O(N log N) optimization)Trigger-based recording with configurable thresholdsMulti-threaded audio buffer managementReal-time waveform and spectrogram rendering (0-192kHz range)Custom Visualization Components
`SpectrogramView.java` - 100 columns × 128 frequency bins, 0-192kHz display range`WaveformView.java` - Real-time time-domain signal displayOptimized rendering for continuous 384kHz data streamsInstructions for AI Agent
When working on this project, follow these guidelines:
1. Project Structure Understanding
**Primary source directory:** `app/src/main/java/com/example/usbaudio/`
**Core components to modify:**
`MainActivity.java` - USB device detection, recording lifecycle`UsbAudioService.java` - Background audio processing service`SpectrogramView.java` / `WaveformView.java` - Real-time visualization`UsbIsochronousReader.java` - USB transfer handling`app/src/main/cpp/` - Native audio processing code**Reference materials (read-only):**
`tmp/BatRecorder/sources/` - Decompiled reference code (3481+ files, architectural patterns only)`tmp/BatRecorder/resources/` - Original native libraries and resources2. Code Development Guidelines
**When modifying existing code:**
Recognize that decompiled code contains obfuscated names (`f8702X`, `R0`, etc.)Focus on architectural patterns rather than literal variable namesPreserve multi-threaded audio buffer management patternsMaintain USB device permission flow and lifecycle management**When adding features:**
Prioritize real-time performance for 384kHz continuous data streamsUse native C++ (JNI) for audio-intensive operations (FFT, buffer processing)Implement proper USB isochronous transfer error handlingEnsure visualization components scale with high sample rates**Native method integration pattern:**
```java
// Declare native methods in MainActivity/Service
private native int ReadFrameFromAudioBuffer();
private native void StartRecord(String filename);
private native void StopRecord();
private native float[] analyzeSpectrum(short[] audioData);
```
3. Critical Technical Requirements
**USB Audio Configuration:**
Support 384kHz sample rate detection and configurationHandle multiple audio descriptor formats (PCM16/PCM24/PCM32)Implement fallback for unsupported sample ratesTest with USB Audio Class 2.0 devices**Real-Time Performance:**
FFT processing must complete within frame time (< 2.6ms at 384kHz)Use circular buffers for audio data managementMinimize UI thread blocking during visualization updatesConsider GPU acceleration (RenderScript) for FFT processing**Android Requirements:**
Target SDK: 34 (Android 14)Minimum SDK: 26 (Android 8.0)Required permissions: `RECORD_AUDIO`, `android.hardware.usb.host`Support architectures: arm64-v8a, armeabi-v7a, x86, x86_644. Current Development Priorities
**Phase 1 (Completed):**
✅ Basic USB audio infrastructure
✅ 384kHz spectrogram visualization
✅ USB Host mode integration
✅ Release APK build system
**Phase 2 (In Progress):**
Integrate high-performance FFT library (KissFFT/FFTW/RenderScript)Optimize USB isochronous transfer handlingImplement trigger-based recording (amplitude/frequency thresholds)Add WAV/FLAC file format support with 384kHz metadata**Phase 3 (Future):**
Power spectrum analysis and frequency trackingBat call detection algorithmsRecording session metadata (GPS, temperature, time)Cloud sync and data export features5. Testing and Validation
**Required test cases:**
USB device hotplug/unplug scenariosSustained 384kHz recording (1+ hour duration)Memory leak testing during continuous recordingVisualization performance under high data ratesMulti-device USB hub compatibility**Performance benchmarks:**
FFT processing latency < 2msUSB buffer underrun rate < 0.1%UI frame rate ≥ 30fps during recordingMaximum continuous recording time ≥ 4 hours6. Code Quality Standards
**When reading decompiled reference code:**
Extract architectural patterns, not literal implementationsDocument unclear logic with comments referencing original behaviorPrioritize understanding data flow over variable naming**When writing new code:**
Use descriptive variable names (no obfuscation)Add Javadoc comments for public APIsInclude inline comments for complex audio processing logicFollow Android architecture best practices (MVVM/Repository pattern)7. Build and Release Process
**Build outputs:** `release/` directory contains distribution APKs
**Release checklist:**
Test on physical devices with USB audio hardwareVerify native libraries for all target architecturesProGuard configuration excludes USB/audio APIsValidate permissions in merged AndroidManifest.xmlTest USB device detection on Android 8.0 through 148. Common Pitfalls to Avoid
**USB buffer overflows:** Monitor isochronous transfer queue depth**UI thread blocking:** Never process FFT on main thread**Memory leaks:** Properly release USB device interfaces and native buffers**Sample rate mismatches:** Always verify device reported vs. configured rate**Permission denial:** Handle USB device permission flow asynchronouslyExample Usage Scenarios
**Scenario 1: Adding new FFT library**
```
User: "Integrate KissFFT for better performance"
AI should:
1. Read current FFT implementation in native code
2. Add KissFFT dependency to CMakeLists.txt
3. Create JNI wrapper for KissFFT functions
4. Update analyzeSpectrum() native method
5. Benchmark performance vs. current O(N²) implementation
6. Update SpectrogramView to handle new spectrum data format
```
**Scenario 2: Implementing trigger-based recording**
```
User: "Add amplitude threshold triggering"
AI should:
1. Review current recording flow in UsbAudioService
2. Add threshold configuration UI in MainActivity
3. Implement native peak detection in audio buffer reader
4. Add recording state machine (armed/triggered/stopped)
5. Update UI indicators for trigger status
6. Test with synthetic ultrasonic signals
```
Constraints
Never modify `tmp/BatRecorder/` directory (read-only reference)Maintain compatibility with Android 8.0 (API 26) minimumPreserve multi-architecture native library supportEnsure all USB operations happen off the main threadKeep APK size under 50MB for release buildsFollow Android USB Host API best practices for device compatibilityAdditional Notes
This project requires understanding of:
Android USB Host API and device enumerationDigital signal processing (FFT, windowing, spectrum analysis)JNI/NDK development for audio processingReal-time audio visualization techniquesUSB Audio Class specifications (UAC1/UAC2)When uncertain about hardware-specific behavior, consult Android USB documentation and test with physical USB audio devices supporting 384kHz sample rates.