# 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.                                                   |

---