# 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: ```bash ./tab-downloader ``` Example prompt: ```text === 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) ```bash ./tab-downloader -search-artist "The Eagles" ``` - **Search on GProTab.net** ```bash ./tab-downloader -search-artist "The Eagles" -site gprotab ``` - **Search for Songs** ```bash ./tab-downloader -search-song "Hotel California" ``` ### Download - **Downloads the song** (automatically falling back to GProTab.net if Songsterr fails) ```bash ./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: ```bash ./tab-downloader -download-artist "The Eagles" -output ./my_tabs ``` Example: ```bash 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](https://go.dev/) (version 1.20 or higher) and [Node.js](https://nodejs.org/) installed (Node.js is used by the Songsterr download helper script). ### Build - **Navigate to the project directory** ```bash cd /srv/dev/tab-downloader ``` - **Build the binary** ```bash 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: ```bash go test -v ``` - **TypeScript Unit Tests** Run the Node.js native test suite to verify Songsterr musical duration matching and General MIDI program mappings: ```bash node --experimental-strip-types songsterr/duration-mapper.test.ts ``` ---