Guitar Tab Downloader

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.

Usage

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.

Interactive 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):

Search

Search using Songsterr (default)

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

Search on GProTab.net

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

Search for Songs

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

Download

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

Example:

wompmacho@docker:/srv/dev/tab-downloader$ ./tab-downloader -download-artist "Sky Eats Airplane"
[*] Trying Songsterr first for artist: Sky Eats Airplane
[*] Searching Songsterr for artist: Sky Eats Airplane
[+] Found 5 tabs for this artist on Songsterr.
┌─────┬──────────────────────┬───────────────────┬───────────────────────────────────────────────────────────────────────────────────┐
│ Idx │ Song Title           │ Artist            │ URL                                                                               │
├─────┼──────────────────────┼───────────────────┼───────────────────────────────────────────────────────────────────────────────────┤
│ 1   │ Giants In The Ocean  │ Sky Eats Airplane │ https://www.songsterr.com/a/wsa/sky-eats-airplane-giants-in-the-ocean-tab-s386244 │
│ 2   │ She Is Just A Glitch │ Sky Eats Airplane │ https://www.songsterr.com/a/wsa/sky-eats-airplane-she-is-just-a-glitch-tab-s53681 │
│ 3   │ Photographic Memory  │ Sky Eats Airplane │ https://www.songsterr.com/a/wsa/sky-eats-airplane-photographic-memory-tab-s79812  │
│ 4   │ Sound Of Symmetry    │ Sky Eats Airplane │ https://www.songsterr.com/a/wsa/sky-eats-airplane-sound-of-symmetry-tab-s3385754  │
│ 5   │ Numbers              │ Sky Eats Airplane │ https://www.songsterr.com/a/wsa/sky-eats-airplane-numbers-tab-s3799256            │
└─────┴──────────────────────┴───────────────────┴───────────────────────────────────────────────────────────────────────────────────┘

Enter selection (e.g., 1-5,7,10-12) or press Enter to download all [Default: all]: 
[*] Downloading all songs.
[*] Downloading tabs to: downloads/Sky Eats Airplane
[1/5] Downloading: Giants In The Ocean
[+] Saved to: downloads/Sky Eats Airplane/Sky Eats Airplane - Giants In The Ocean.gp
[2/5] Downloading: She Is Just A Glitch
[+] Saved to: downloads/Sky Eats Airplane/Sky Eats Airplane - She Is Just A Glitch.gp
[3/5] Downloading: Photographic Memory
[+] Saved to: downloads/Sky Eats Airplane/Sky Eats Airplane - Photographic Memory.gp
[4/5] Downloading: Sound Of Symmetry
[+] Saved to: downloads/Sky Eats Airplane/Sky Eats Airplane - Sound Of Symmetry.gp
[5/5] Downloading: Numbers
[+] Saved to: downloads/Sky Eats Airplane/Sky Eats Airplane - Numbers.gp
[+] Finished downloading artist tabs from Songsterr!

Development

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

Build

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

Test

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

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
```
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
```

8.6 KiB Raw Permalink Blame History