https://github.com/cod-e-codes/tuitar
Terminal-based guitar tablature editor with modal Vim-style editing, real-time visual feedback, and MIDI playback — built in Go with Bubble Tea.
https://github.com/cod-e-codes/tuitar
bubbletea developer-tools editor go guitar midi music playback tabs terminal tui vim
Last synced: 16 days ago
JSON representation
Terminal-based guitar tablature editor with modal Vim-style editing, real-time visual feedback, and MIDI playback — built in Go with Bubble Tea.
- Host: GitHub
- URL: https://github.com/cod-e-codes/tuitar
- Owner: Cod-e-Codes
- License: mit
- Created: 2025-08-12T06:23:20.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-20T00:42:21.000Z (9 months ago)
- Last Synced: 2025-08-20T02:38:52.557Z (9 months ago)
- Topics: bubbletea, developer-tools, editor, go, guitar, midi, music, playback, tabs, terminal, tui, vim
- Language: Go
- Homepage: https://github.com/Cod-e-Codes/tuitar
- Size: 205 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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):**
```bash
# 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:**
```bash
sudo apt-get install libasound2-dev
```
### Pre-built Binaries (Recommended)
Download the latest release for your platform:
- **Windows AMD64**: [tuitar-windows-amd64.exe](https://github.com/Cod-e-Codes/tuitar/releases/latest/download/tuitar-windows-amd64.exe)
- **Linux AMD64**: [tuitar-linux-amd64](https://github.com/Cod-e-Codes/tuitar/releases/latest/download/tuitar-linux-amd64)
### From Source
```bash
# Install from source
git clone https://github.com/Cod-e-Codes/tuitar
cd tuitar
go build -o tuitar
```
```bash
# Or install directly
go install github.com/Cod-e-Codes/tuitar@latest
```
## Usage
```bash
# 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
```bash
# Clone the repository
git clone https://github.com/Cod-e-Codes/tuitar
cd tuitar
```
```bash
# Install dependencies (ensure audio libraries are installed first)
go mod tidy
```
```bash
# Build
go build -o tuitar
```
```bash
# Run
./tuitar
```
## Dependencies
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
- [modernc.org/sqlite](https://modernc.org/sqlite) - Pure Go SQLite driver (CGO-free)
- [gopxl/beep](https://github.com/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
```bash
# 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](https://github.com/Cod-e-Codes/tuitar/releases) for the latest version and changelog.
## Roadmap
- [x] Audio playback (fully implemented with Karplus-Strong string synthesis)
- [x] Visual playback highlighting
- [x] Measure management (add/remove measures dynamically)
- [x] Advanced navigation (page scrolling, measure jumping)
- [x] 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