Home

Bragi: Real-Time Audio Engine & Practice Companion

Welcome to the official Bragi documentation wiki. Named after the Norse god of poetry and music, Bragi is a cross-platform desktop application designed for real-time guitar pitch detection, chord verification, chromatic tuning, and adaptive fretboard training.

Executive Overview

Bragi combines real-time Digital Signal Processing (DSP) with responsive UI rendering to deliver zero-latency feedback for fretted instrument players. Powered by Python, Aubio, SoundDevice, and Flet, Bragi captures live audio input, isolates pitch frequencies, matches harmonic structures, and provides feedback on fretboard position, pitch accuracy, and chord execution.

Bragi's Core Philosophy: Audio-first performance with uncompromised threading isolation. Audio capture never drops frames, and UI rendering never locks the audio buffer stream.

Key Features & Capabilities

1. Centralized Real-Time DSP Engine

YIN Pitch Extraction: Leverages the Aubio library's YIN algorithm with customizable buffer sizes ($2048$ frames) and hop sizes ($1024$ frames) at $44.1\text{ kHz}$ sample rates.
Relaxed Resonance Thresholds: Optimized silence floor ($-65.0\text{ dBFS}$) and lowered Aubio pitch confidence requirements ($0.30$) to accurately capture natural guitar body resonance, decaying notes, and light fingerpicking.
Hardware Hardware Isolation: Centralized singleton AudioManager owns the sounddevice.InputStream, eliminating hardware stream contention across views and OS-level PortAudio locks.

2. Chromatic Tuner Subview

High-Precision Pitch Tracking: Displays exact detected pitch classes ($C, C\sharp, D, \dots, B$), octave designations, and frequency in Hertz ($0.1\text{ Hz}$ resolution).
Cents Deviation Gauge: Visual gauge indicating cents offset from $-50\text{ cents}$ (Flat) to $+50\text{ cents}$ (Sharp) with color-coded status badges ($in\text{ }tune \le \pm 5\text{ cents}$).
Standard Reference Row: Quick-reference pitch benchmarks for standard guitar tuning ($E2, A2, D3, G3, B3, E4$).

3. Flashcard & Chord Trainer Engine

Chromatic Key Support: Generates random flashcards across all 12 chromatic root keys ($C$ through $B$) and major/minor qualities.
Arpeggio Accumulator Mode: Solves monophonic microphone limitations during strummed chords by capturing note pitch classes sequentially into a rolling $1.8\text{-second}$ memory buffer.
Instantaneous Match Evaluation: Zero-hold validation ($0.0\text{s}$) triggers target completion the exact millisecond all required pitch classes are detected in memory, clearing the buffer for seamless transition to the next chord card.

4. Dynamic Device & System Management

Native Device Enumeration: Filters out MME/DirectSound virtual duplicates and displays active physical inputs based on system primary host APIs (WASAPI on Windows, CoreAudio on macOS).
Auto-Fallback Safeguard: Automatically falls back to the system default microphone if a persisted device index becomes offline or invalid.

Technical Architecture

                                  +-----------------------+
                                  |   Hardware Audio In   |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |    sounddevice Stream |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |     PitchDetector     |
                                  | (Aubio YIN / dBFS)    |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |   AudioManager Thread |
                                  |  (~40 FPS Queue Drain)|
                                  +-----+-----------+-----+
                                        |           |
                     +------------------+           +------------------+
                     |                                                 |
                     v                                                 v
        +-------------------------+                       +-------------------------+
        |   AudioWorker Engine    |                       | Flet Main Thread Loop   |
        |  (Evaluators & Buffers) |                       | (~25 FPS UI Render)     |
        +-------------------------+                       +-------------------------+

Component Breakdown

Module | Location | Primary Responsibility -- | -- | -- PitchDetector | src/audio/pitch_detector.py | Manages C-level PortAudio streams, Aubio pitch extraction, RMS dBFS calculation, and device switching. AudioManager | src/services/audio_manager.py | Singleton hardware owner. Polls PitchDetector at $40\text{ FPS}$ on a background thread and broadcasts state events. AudioWorker | src/audio/audio_worker.py | Background evaluator processing note matches and accumulating pitch-class sets into ArpeggioBuffer. TunerView | src/views/subviews/tuner_view.py | Chromatic tuner UI driven by an active main-thread asyncio render loop ($25\text{ FPS}$). TrainerView | src/views/trainer_view.py | Main flashcard/practice view supporting speed drills and chord evaluation visualizers.

Application Status

Bragi is currently in Phase 1 Complete (Core Engine & Stability).

Recent Technical Milestones

Queue Contention Resolution: Eliminated dual-queue stealing by designating AudioManager as the sole consumer of PitchDetector queue frames.
Main-Thread UI Loop: Integrated asyncio.create_task rendering loops bound to view mount lifecycles, bypassing background thread WebSocket buffering issues in Flet.
Optimized Chord Accumulation: Transitioned default chord verification to an $1.8\text{-second}$ Arpeggio Accumulator with zero-hold triggers, making chord detection fast and reliable during natural strums.
Full Chromatic Flashcards: Unlocked the random practice generator across all 12 musical keys and qualities.

Development Roadmap

Phase 1: Core Engine & Tuning (Completed)
├── Singleton Audio Pipeline
├── Chromatic Tuner Subview
└── Arpeggio Accumulator Engine
Phase 2: Extended Practice Modes (In Progress)
├── CAGED Position Challenge
├── Custom Scale & Arpeggio Generators
└── Adaptive Speed Flashcards (BPM/Timer-based)
Phase 3: Deep DSP & Tuning Presets (Planned)
├── Alternate Tunings (Drop D, DADGAD, Open G)
├── Harmonic Overstone Spectrum Visualizer
└── Polyphonic Chord Fingerprinting
Phase 4: Analytics & Customization (Future)
├── Practice Session Analytics & Streak Metrics
├── Pitch Accuracy Heatmaps
└── Custom Instrument Profiles (Bass, Ukulele, Mandolin)

Detailed Phase Planning

Phase 2: Extended Practice Modes (Current Focus)

CAGED Position Filtering: Restrict chord practice cards to specific neck regions (Position 1 through 5) or CAGED shapes.
Adaptive Flashcards: Dynamic auto-advancing cards that decrease display timer intervals as player accuracy increases.
Ear Training Drills: Play a random reference pitch/chord and evaluate the user's ability to locate and repeat it on the fretboard.

Phase 3: Advanced DSP & Tuning Presets

Custom Instrument Tuning Profiles: Support for alternate guitar tunings ($Drop\text{ }D, DADGAD, Open\text{ }G$) with adjusted pitch reference targets and fretboard map translation.
Spectrum Analysis Integration: Visual FFT frequency waterfall display for analyzing string timbre and overtone distribution.

Phase 4: Persistence & User Progression

Local SQLite Progress Database: Log daily practice duration, note accuracy rates, and chord transition speeds.
Custom Theme Engine: Personalizable visual accents and dark/light UI modes built on top of ThemeManager.

Getting Started

Prerequisites

Python: 3.10+
Dependencies: flet, sounddevice, aubio, numpy, pydantic

Installation & Launch

Bash

# Clone the repository
git clone https://github.com/your-username/Bragi.git
cd Bragi
# Install dependencies
pip install -r requirements.txt
# Launch the application
python main.py

Navigation Menu

Repository navigation