A simple, fast, and powerful CLI tool to search, view, and download guitar tabs (Guitar Pro formats like .gp, .gp3, .gp4, .gp5, .gpx, etc.) from both Songsterr.com and GProTab.net.

Features

Dual-Source Support: Integrates with both Songsterr.com (default) and GProTab.net.
Songsterr Pagination & Unlimited Downloads: The 50-tab limit on Songsterr is fully lifted! The tool implements automated offset-pagination loops to retrieve and download all available tabs for any artist.
Interactive Multi-Tab Selection: When batch-downloading an artist's tabs, a powerful index range selection engine prompts you (e.g. 1,3,5-10,12), allowing you to download only specific tabs. Pressing Enter downloads all tabs as the default behavior.
Automated Fallbacks: When using Songsterr, if a search or download fails, the tool automatically falls back to GProTab.net to find your tabs.
Pretty Table Formatting: Displays search results in gorgeous, modern Unicode box-drawing tables with ANSI colors:
- Header row styled in Bold Cyan.
- Row indexes highlighted in Bright Green for quick interactive choices.
- Song/Artist titles in Bright White and URLs in muted Gray.
Interactive TUI Mode: Launch the tool without flags for an interactive, colorized menu to search, browse, and download tabs on-the-fly.
Automated CLI Mode: Run headlessly with full command-line arguments and flags to automate downloads and search.
Polite Batch Downloading: Includes a configurable delay (default 1 second) between requests to respect rate limits.
Smart Filename Extraction: Saves files using authentic filenames pulled directly from download headers.

Installation & Compilation

Ensure you have Go (version 1.20 or higher) and Node.js installed (Node.js is used by the Songsterr download helper script).

Navigate to the project directory:
```
cd /srv/dev/tab-downloader
```
Build the binary:
```
go build -o tab-downloader main.go
```

Running Tests

The project includes lightweight, zero-dependency unit tests for both the Go orchestrator and the TypeScript converter utilities.

1. Go Unit Tests

Run the Go test suite to verify GProTab path normalization, Songsterr name slugifying, and our multi-index selection range parser:

go test -v

2. TypeScript Unit Tests

Run the Node.js native test suite to verify Songsterr musical duration matching and General MIDI program mappings:

node --experimental-strip-types songsterr/duration-mapper.test.ts

Usage

1. Interactive TUI Mode

Run the compiled binary with no arguments to launch the colorized interactive menu:

./tab-downloader

Example prompt:

=== Guitar Tab Downloader Menu (Site: Songsterr) ===
1. Search for Artists
2. Search for Songs
3. Download Tabs for an Artist (allows selection/all)
4. Download a Specific Song Tab
5. Switch Site Source (Current: Songsterr)
6. Exit
==================================================
Enter choice (1-6):

2. Automated CLI Mode (Flags)

For automated pipelines or direct searches, run the command with flags.

Search for Artists

Search using Songsterr (default)

./tab-downloader -search-artist "The Eagles"

Search on GProTab.net specifically

./tab-downloader -search-artist "The Eagles" -site gprotab

Search for Songs

./tab-downloader -search-song "Hotel California"

Download a Specific Song

Downloads the song (automatically falling back to GProTab.net if Songsterr fails)

./tab-downloader -download-song "Hotel California" -output ./my_tabs

Download All Tabs for an Artist

Downloads tabs for an artist into a subdirectory named after the artist, with an interactive prompt allowing you to filter specific selections or download all by default:

./tab-downloader -download-artist "The Eagles" -output ./my_tabs

Terminal Prompt Example:

Enter selection (e.g., 1-5,7,10-12) or press Enter to download all [Default: all]: 1,3,5-7,10

Technical Details & CLI Flags

The complete list of supported command-line flags:

Flag	Type	Default	Description
`-site`	`string`	`songsterr`	Select source website: `'songsterr'` or `'gprotab'`.
`-search-artist`	`string`	`""`	Search for artists matching the query and print a beautiful Unicode table.
`-search-song`	`string`	`""`	Search for songs matching the query and print a beautiful Unicode table.
`-download-artist`	`string`	`""`	Download tabs for an artist (prompts with interactive selection). Accepts artist name query, slug, or full URL.
`-download-song`	`string`	`""`	Download a single song tab. Accepts song name query, slug, or full URL.
`-output`	`string`	`downloads`	Destination directory for downloaded files.
`-delay`	`int`	`1000`	Delay in milliseconds between downloads in batch/artist mode.