{"id":30718249,"url":"https://github.com/cod-e-codes/tuitar","last_synced_at":"2026-05-07T00:34:46.713Z","repository":{"id":309494459,"uuid":"1036481070","full_name":"Cod-e-Codes/tuitar","owner":"Cod-e-Codes","description":"Terminal-based guitar tablature editor with modal Vim-style editing, real-time visual feedback, and MIDI playback — built in Go with Bubble Tea.","archived":false,"fork":false,"pushed_at":"2025-08-20T00:42:21.000Z","size":210,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-20T02:38:52.557Z","etag":null,"topics":["bubbletea","developer-tools","editor","go","guitar","midi","music","playback","tabs","terminal","tui","vim"],"latest_commit_sha":null,"homepage":"https://github.com/Cod-e-Codes/tuitar","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cod-e-Codes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T06:23:20.000Z","updated_at":"2025-08-20T00:42:24.000Z","dependencies_parsed_at":"2025-08-12T08:39:59.708Z","dependency_job_id":null,"html_url":"https://github.com/Cod-e-Codes/tuitar","commit_stats":null,"previous_names":["cod-e-codes/tuitar"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Cod-e-Codes/tuitar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Ftuitar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Ftuitar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Ftuitar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Ftuitar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cod-e-Codes","download_url":"https://codeload.github.com/Cod-e-Codes/tuitar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Ftuitar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273423958,"owners_count":25103146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","developer-tools","editor","go","guitar","midi","music","playback","tabs","terminal","tui","vim"],"created_at":"2025-09-03T09:48:24.585Z","updated_at":"2026-05-07T00:34:46.706Z","avatar_url":"https://github.com/Cod-e-Codes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tuitar\r\n\r\nA terminal-based guitar tablature editor built with Go and Bubble Tea.\r\n\r\n## Features\r\n\r\n- **Intuitive Terminal Interface**: Vim-like keyboard navigation with modal editing\r\n- **Real-time Tab Editing**: Create and edit guitar tabs with instant visual feedback\r\n- **Modal Editing**: Separate Normal and Insert modes for efficient editing workflow\r\n- **Audio Playback**: Real-time audio playback with Karplus-Strong string synthesis and visual highlighting\r\n- **Measure Management**: Add and remove measures dynamically with smart display wrapping\r\n- **Advanced Navigation**: Page scrolling, measure jumping, and intuitive cursor movement\r\n- **Local Storage**: SQLite-based tab management with auto-save functionality (CGO-free)\r\n- **Tab Browser**: Browse, delete, and organize your tabs with easy navigation\r\n- **Keyboard-driven**: Efficient workflows without mouse dependency\r\n- **Cross-platform**: Pre-built binaries for Windows and Linux\r\n- **CGO-free**: Uses pure Go dependencies for better cross-compilation and deployment\r\n\r\n## Screenshots\r\n\r\n\u003cp float=\"left\"\u003e\r\n  \u003cimg src=\"Screenshot_20250812_083727_Termux.jpg\" alt=\"Tuitar Browser\" style=\"max-width:600px; margin-right: 10px;\" /\u003e\r\n  \u003cimg src=\"Screenshot_20250812_083802_Termux.jpg\" alt=\"Tuitar Editor\" style=\"max-width:600px;\" /\u003e\r\n\u003c/p\u003e\r\n\r\n## Installation\r\n\r\n### System Requirements\r\n\r\n**Linux (including Arch):**\r\n```bash\r\n# For audio support, install ALSA libraries\r\nsudo pacman -S alsa-lib\r\n\r\n# Or if using PulseAudio/PipeWire\r\nsudo pacman -S libpulse pipewire-pulse pipewire-alsa\r\n```\r\n\r\n**Ubuntu/Debian:**\r\n```bash\r\nsudo apt-get install libasound2-dev\r\n```\r\n\r\n### Pre-built Binaries (Recommended)\r\n\r\nDownload the latest release for your platform:\r\n\r\n- **Windows AMD64**: [tuitar-windows-amd64.exe](https://github.com/Cod-e-Codes/tuitar/releases/latest/download/tuitar-windows-amd64.exe)\r\n- **Linux AMD64**: [tuitar-linux-amd64](https://github.com/Cod-e-Codes/tuitar/releases/latest/download/tuitar-linux-amd64)\r\n\r\n### From Source\r\n\r\n```bash\r\n# Install from source\r\ngit clone https://github.com/Cod-e-Codes/tuitar\r\ncd tuitar\r\ngo build -o tuitar\r\n```\r\n```bash\r\n# Or install directly\r\ngo install github.com/Cod-e-Codes/tuitar@latest\r\n```\r\n\r\n## Usage\r\n\r\n```bash\r\n# Start the application\r\n./tuitar\r\n\r\n# The application will create a tabs.db SQLite database in the current directory\r\n```\r\n\r\n## Key Bindings\r\n\r\n### Global\r\n- `q` / `Ctrl+C` - Quit application\r\n- `?` - Toggle help\r\n- `Ctrl+N` - Create new tab\r\n- `Ctrl+S` - Save current tab\r\n\r\n### Browser Mode\r\n- `j` / `↓` - Move down\r\n- `k` / `↑` - Move up\r\n- `Enter` - Edit selected tab\r\n- `d` - Delete selected tab\r\n\r\n### Editor Mode (Normal)\r\n- `h` / `←` - Move cursor left\r\n- `j` / `↓` - Move cursor down (to next string)\r\n- `k` / `↑` - Move cursor up (to previous string)\r\n- `l` / `→` - Move cursor right\r\n- `w` - Move to next measure boundary\r\n- `b` - Move to previous measure boundary\r\n- `g` - Move to beginning of current measure\r\n- `$` - Move to end of current measure\r\n- `Home` - Move to beginning of string\r\n- `End` - Move to end of string\r\n- `PgUp` / `PgDn` - Page up/down scrolling\r\n- `x` - Delete fret (replace with dash)\r\n- `Space` - Play/pause tab (with real audio output)\r\n- `m` - Add new measure\r\n- `M` - Remove last measure\r\n- `i` - Switch to insert mode\r\n- `Tab` - Return to browser\r\n- `Esc` - Stay in normal mode\r\n\r\n### Editor Mode (Insert)\r\n- `0-9` - Insert fret number (auto-advances cursor)\r\n- `-` - Insert rest/dash (auto-advances cursor)\r\n- `Backspace` - Delete previous character and move back\r\n- `Arrow keys` / `hjkl` - Navigate while in insert mode\r\n- `Esc` - Return to normal mode\r\n\r\n## Editing Workflow\r\n\r\nTuitar uses a modal editing system inspired by Vim:\r\n\r\n1. **Normal Mode** (default): Navigate and perform editing commands\r\n   - Use arrow keys or `hjkl` to move the cursor\r\n   - Press `i` to enter Insert mode at the current position\r\n   - Press `x` to delete the fret number at cursor (replaces with `-`)\r\n   - Press `Space` to play/pause the tab with audio output\r\n\r\n2. **Insert Mode**: Type fret numbers and navigate\r\n   - Type `0-9` to insert fret numbers\r\n   - Type `-` to insert rests\r\n   - The cursor automatically advances after inserting\r\n   - Use `Backspace` to delete and move backward\r\n   - Press `Esc` to return to Normal mode\r\n\r\n3. **Visual Feedback**: \r\n   - Current cursor position is highlighted\r\n   - Insert mode shows with yellow highlighting\r\n   - Normal mode shows with blue highlighting\r\n   - Playback positions are highlighted in cyan\r\n   - Mode indicator shows current editing mode\r\n\r\n## Audio Playback\r\n\r\nTuitar features real-time audio playback using the Karplus-Strong string synthesis algorithm:\r\n\r\n- **Realistic Guitar Sound**: Uses Karplus-Strong algorithm for authentic plucked string timbre\r\n- **Accurate Frequencies**: Standard guitar tuning with proper fret calculations\r\n- **Real-time Highlighting**: Visual feedback shows currently playing notes\r\n- **Tempo Control**: Respects tab tempo settings (default 120 BPM)\r\n- **Multiple Strings**: Plays chords and multi-string passages correctly\r\n- **Natural Decay**: String-specific damping for realistic sound decay\r\n- **High Quality**: 44.1kHz sample rate with volume control\r\n\r\n## Project Structure\r\n\r\nThe application follows a clean architecture pattern:\r\n\r\n- `internal/models/` - Core data structures and business logic\r\n- `internal/storage/` - Data persistence layer (SQLite with modernc.org/sqlite)\r\n- `internal/ui/` - Bubble Tea UI components and views  \r\n- `internal/audio/` - Real-time audio playback using gopxl/beep library\r\n- `internal/midi/` - MIDI playback functionality (basic implementation)\r\n\r\n## Building from Source\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/Cod-e-Codes/tuitar\r\ncd tuitar\r\n```\r\n\r\n```bash\r\n# Install dependencies (ensure audio libraries are installed first)\r\ngo mod tidy\r\n```\r\n\r\n```bash\r\n# Build\r\ngo build -o tuitar\r\n```\r\n\r\n```bash\r\n# Run\r\n./tuitar\r\n```\r\n\r\n## Dependencies\r\n\r\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework\r\n- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components\r\n- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling\r\n- [modernc.org/sqlite](https://modernc.org/sqlite) - Pure Go SQLite driver (CGO-free)\r\n- [gopxl/beep](https://github.com/gopxl/beep) - Audio playback library (updated fork)\r\n\r\n## Tips \u0026 Tricks\r\n\r\n- **Quick Start**: Press `Ctrl+N` to create a new tab and start editing immediately\r\n- **Save Often**: Use `Ctrl+S` to save your work - changes are highlighted when unsaved\r\n- **Navigation**: Use `hjkl` keys for faster navigation without leaving home row\r\n- **Measure Navigation**: Use `w`/`b` to jump between measures, `g`/`$` for measure boundaries\r\n- **Page Scrolling**: Use `PgUp`/`PgDn` for fast scrolling through long tabs\r\n- **Measure Management**: Use `m` to add measures, `M` to remove them - they display side by side\r\n- **Insert Flow**: In Insert mode, type fret numbers quickly - the cursor advances automatically\r\n- **Error Correction**: Use `x` in Normal mode for quick deletions, or `Backspace` in Insert mode\r\n- **Mode Awareness**: Watch the mode indicator to know which editing mode you're in\r\n- **Tab Management**: Use `d` in browser mode to delete unwanted tabs\r\n- **Audio Playback**: Press `Space` to hear your tabs played back with Karplus-Strong string synthesis\r\n- **Volume Control**: Audio is automatically balanced to prevent distortion\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests if applicable\r\n5. Submit a pull request\r\n\r\n### Development Setup\r\n\r\nThe project uses GitHub Actions for CI/CD:\r\n\r\n- **Automated Testing**: Runs tests and linting on every push and PR\r\n- **Multi-platform Builds**: Automatically builds for Windows, Linux, and macOS\r\n- **Automated Releases**: Creates releases with proper versioning and changelogs\r\n- **Manual Releases**: Use the \"Manual Release\" workflow for semantic versioning\r\n\r\n### Building for Development\r\n\r\n```bash\r\n# Run tests\r\ngo test ./...\r\n\r\n# Run linter\r\ngolangci-lint run\r\n\r\n# Build for your platform\r\ngo build -o tuitar\r\n\r\n# Build for specific platform\r\nGOOS=windows GOARCH=amd64 go build -o tuitar.exe\r\n```\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details\r\n\r\n## Releases\r\n\r\nCheck out the [Releases page](https://github.com/Cod-e-Codes/tuitar/releases) for the latest version and changelog.\r\n\r\n## Roadmap\r\n\r\n- [x] Audio playback (fully implemented with Karplus-Strong string synthesis)\r\n- [x] Visual playback highlighting\r\n- [x] Measure management (add/remove measures dynamically)\r\n- [x] Advanced navigation (page scrolling, measure jumping)\r\n- [x] Tab deletion functionality\r\n- [ ] Advanced tab notation (bends, slides, hammer-ons, pull-offs)\r\n- [ ] Multi-instrument support (bass, drums, etc.)\r\n- [ ] Tab sharing\r\n- [ ] MIDI export functionality\r\n- [ ] Custom tuning support\r\n- [ ] Metronome functionality\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcod-e-codes%2Ftuitar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcod-e-codes%2Ftuitar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcod-e-codes%2Ftuitar/lists"}