add initial version of tab-downloader

2026-05-24 04:47:53 +00:00
commit d56d4714db
13 changed files with 3628 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,147 @@
+# 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.
+
+---
+
+## Installation & Compilation
+
+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).
+
+1. Navigate to the project directory:
+   ```bash
+   cd /srv/dev/tab-downloader
+   ```
+
+2. Build the binary:
+   ```bash
+   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:
+
+```bash
+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:
+
+```bash
+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:
+
+```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):
+```
+
+---
+
+### 2. Automated CLI Mode (Flags)
+
+For automated pipelines or direct searches, run the command with flags.
+
+#### Search for Artists
+
+# Search using Songsterr (default)
+```bash
+./tab-downloader -search-artist "The Eagles"
+```
+
+# Search on GProTab.net specifically
+```bash
+./tab-downloader -search-artist "The Eagles" -site gprotab
+```
+
+#### Search for Songs
+
+```bash
+./tab-downloader -search-song "Hotel California"
+```
+
+#### Download a Specific Song
+
+# 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
+```
+
+Terminal Prompt Example:
+
+```text
+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.                                                   |
+
+---