How joaoreisa/guitar_tuner works
Project type and purpose
• This is a Go-based command-line interface (CLI) application whose sole purpose is to turn your terminal into a real-time guitar tuner.
• It captures live audio from your microphone, runs an FFT-based frequency analysis pipeline, maps the dominant frequency to a musical note, and displays a styled, interactive CLI using BubbleTea/Lipgloss.
File structure
• Top level:
• main.go: application entry point
• cmd/: Cobra command definitions (root.go, tune.go)
• internal/: code organized by clean-architecture layers
– internal/data/service: audio_input.go (PortAudio adapter)
– internal/domain/entities & usecase: core music theory logic (notes & frequency mapping)
– internal/presentation: BubbleTea model & Lipgloss styles
• utils/: cross-cutting helpers (e.g., FFT wrapper, window functions)
• bin/: compiled binary location
• go.mod/go.sum, README.md, LICENSE, .vscode
Key insights from README
• Uses Cobra for CLI commands (tune command)
• Uses PortAudio for low-level audio capture
• Audio pipeline: normalize → Hanning window → FFT → extract fundamental frequency
• Uses domain logic to map frequency to nearest guitar note
• BubbleTea drives the interactive state loop, Lipgloss handles styling
Main components
a. Entrypoint/CLI Layer
• Cobra’s root and tune commands in cmd/
b. Audio Capture Adapter
• PortAudio stream (internal/data/service/audio_input.go)
c. Audio Processing Pipeline
• Utils module: normalization, windowing, FFT
d. Domain Core
• Entities: Note, NoteSymbol enum
• Usecases: frequency → note calculation
e. Presentation Adapter
• BubbleTea model, Lipgloss styling (internal/presentation)
f. External Dependencies
• PortAudio native library
• Third-party Go modules (Cobra, BubbleTea, Lipgloss)
Relationships and data flow
1. User invokes guitar_tuner tune (CLI layer)
2. CLI layer calls Audio Capture Adapter
3. PortAudio pushes raw PCM buffer → sent to Audio Processing Pipeline
4. FFT library processes buffer → outputs dominant frequency
5. Frequency passed to Domain Core usecase → returns note entity
6. Domain result forwarded to Presentation Adapter → updates CLI UI
7. Loop back to step 2 until user quits
Architectural patterns and design principles
• Clean/Hexagonal architecture: separation between domain core and external adapters
• Single Responsibility: each package (data, domain, presentation, utils) owns a distinct concern
• Dependency Inversion: domain layer has no imports from data/presentation
• Event loop pattern (BubbleTea) in presentation