tuitar

A terminal-based guitar tablature editor built with Go and Bubble Tea.

Features

• Intuitive Terminal Interface: Vim-like keyboard navigation with modal editing
• Real-time Tab Editing: Create and edit guitar tabs with instant visual feedback
• Modal Editing: Separate Normal and Insert modes for efficient editing workflow
• Audio Playback: Real-time audio playback with Karplus-Strong string synthesis and visual highlighting
• Measure Management: Add and remove measures dynamically with smart display wrapping
• Advanced Navigation: Page scrolling, measure jumping, and intuitive cursor movement
• Local Storage: SQLite-based tab management with auto-save functionality (CGO-free)
• Tab Browser: Browse, delete, and organize your tabs with easy navigation
• Keyboard-driven: Efficient workflows without mouse dependency
• Cross-platform: Pre-built binaries for Windows and Linux
• CGO-free: Uses pure Go dependencies for better cross-compilation and deployment

Screenshots

Installation

System Requirements

Linux (including Arch):

# For audio support, install ALSA libraries
sudo pacman -S alsa-lib

# Or if using PulseAudio/PipeWire
sudo pacman -S libpulse pipewire-pulse pipewire-alsa

Ubuntu/Debian:

sudo apt-get install libasound2-dev

Pre-built Binaries (Recommended)

Download the latest release for your platform:

• Windows AMD64: tuitar-windows-amd64.exe
• Linux AMD64: tuitar-linux-amd64

From Source

# Install from source
git clone https://github.com/Cod-e-Codes/tuitar
cd tuitar
go build -o tuitar

# Or install directly
go install github.com/Cod-e-Codes/tuitar@latest

Usage

# Start the application
./tuitar

# The application will create a tabs.db SQLite database in the current directory

Key Bindings

Global

• q / Ctrl+C - Quit application
• ? - Toggle help
• Ctrl+N - Create new tab
• Ctrl+S - Save current tab

Browser Mode

• j / ↓ - Move down
• k / ↑ - Move up
• Enter - Edit selected tab
• d - Delete selected tab

Editor Mode (Normal)

• h / ← - Move cursor left
• j / ↓ - Move cursor down (to next string)
• k / ↑ - Move cursor up (to previous string)
• l / → - Move cursor right
• w - Move to next measure boundary
• b - Move to previous measure boundary
• g - Move to beginning of current measure
• $ - Move to end of current measure
• Home - Move to beginning of string
• End - Move to end of string
• PgUp / PgDn - Page up/down scrolling
• x - Delete fret (replace with dash)
• Space - Play/pause tab (with real audio output)
• m - Add new measure
• M - Remove last measure
• i - Switch to insert mode
• Tab - Return to browser
• Esc - Stay in normal mode

Editor Mode (Insert)

• 0-9 - Insert fret number (auto-advances cursor)
• - - Insert rest/dash (auto-advances cursor)
• Backspace - Delete previous character and move back
• Arrow keys / hjkl - Navigate while in insert mode
• Esc - Return to normal mode

Editing Workflow

Tuitar uses a modal editing system inspired by Vim:

1. Normal Mode (default): Navigate and perform editing commands

   • Use arrow keys or hjkl to move the cursor
   • Press i to enter Insert mode at the current position
   • Press x to delete the fret number at cursor (replaces with -)
   • Press Space to play/pause the tab with audio output

2. Insert Mode: Type fret numbers and navigate

   • Type 0-9 to insert fret numbers
   • Type - to insert rests
   • The cursor automatically advances after inserting
   • Use Backspace to delete and move backward
   • Press Esc to return to Normal mode

3. Visual Feedback:

   • Current cursor position is highlighted
   • Insert mode shows with yellow highlighting
   • Normal mode shows with blue highlighting
   • Playback positions are highlighted in cyan
   • Mode indicator shows current editing mode

Audio Playback

Tuitar features real-time audio playback using the Karplus-Strong string synthesis algorithm:

• Realistic Guitar Sound: Uses Karplus-Strong algorithm for authentic plucked string timbre
• Accurate Frequencies: Standard guitar tuning with proper fret calculations
• Real-time Highlighting: Visual feedback shows currently playing notes
• Tempo Control: Respects tab tempo settings (default 120 BPM)
• Multiple Strings: Plays chords and multi-string passages correctly
• Natural Decay: String-specific damping for realistic sound decay
• High Quality: 44.1kHz sample rate with volume control

Project Structure

The application follows a clean architecture pattern:

• internal/models/ - Core data structures and business logic
• internal/storage/ - Data persistence layer (SQLite with modernc.org/sqlite)
• internal/ui/ - Bubble Tea UI components and views
• internal/audio/ - Real-time audio playback using gopxl/beep library
• internal/midi/ - MIDI playback functionality (basic implementation)

Building from Source

# Clone the repository
git clone https://github.com/Cod-e-Codes/tuitar
cd tuitar

# Install dependencies (ensure audio libraries are installed first)
go mod tidy

# Build
go build -o tuitar

# Run
./tuitar

Dependencies

• Bubble Tea - TUI framework
• Bubbles - TUI components
• Lipgloss - Terminal styling
• modernc.org/sqlite - Pure Go SQLite driver (CGO-free)
• gopxl/beep - Audio playback library (updated fork)

Tips & Tricks

• Quick Start: Press Ctrl+N to create a new tab and start editing immediately
• Save Often: Use Ctrl+S to save your work - changes are highlighted when unsaved
• Navigation: Use hjkl keys for faster navigation without leaving home row
• Measure Navigation: Use w/b to jump between measures, g/$ for measure boundaries
• Page Scrolling: Use PgUp/PgDn for fast scrolling through long tabs
• Measure Management: Use m to add measures, M to remove them - they display side by side
• Insert Flow: In Insert mode, type fret numbers quickly - the cursor advances automatically
• Error Correction: Use x in Normal mode for quick deletions, or Backspace in Insert mode
• Mode Awareness: Watch the mode indicator to know which editing mode you're in
• Tab Management: Use d in browser mode to delete unwanted tabs
• Audio Playback: Press Space to hear your tabs played back with Karplus-Strong string synthesis
• Volume Control: Audio is automatically balanced to prevent distortion

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Setup

The project uses GitHub Actions for CI/CD:

• Automated Testing: Runs tests and linting on every push and PR
• Multi-platform Builds: Automatically builds for Windows, Linux, and macOS
• Automated Releases: Creates releases with proper versioning and changelogs
• Manual Releases: Use the "Manual Release" workflow for semantic versioning

Building for Development

# Run tests
go test ./...

# Run linter
golangci-lint run

# Build for your platform
go build -o tuitar

# Build for specific platform
GOOS=windows GOARCH=amd64 go build -o tuitar.exe

License

MIT License - see LICENSE file for details

Releases

Check out the Releases page for the latest version and changelog.

Roadmap

• Audio playback (fully implemented with Karplus-Strong string synthesis)
• Visual playback highlighting
• Measure management (add/remove measures dynamically)
• Advanced navigation (page scrolling, measure jumping)
• Tab deletion functionality
• Advanced tab notation (bends, slides, hammer-ons, pull-offs)
• Multi-instrument support (bass, drums, etc.)
• Tab sharing
• MIDI export functionality
• Custom tuning support
• Metronome functionality