From e309c1d53c9cf91a35f66eeaa11bf3f0f4329668 Mon Sep 17 00:00:00 2001 From: wompmacho Date: Sun, 24 May 2026 14:12:20 +0000 Subject: [PATCH] update reame for readability --- README.md | 243 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 135 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index b0aea03..aa1596a 100644 --- a/README.md +++ b/README.md @@ -21,116 +21,9 @@ A simple, fast, and powerful CLI tool to search, view, and download guitar tabs --- -## 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 +### Flags The complete list of supported command-line flags: @@ -145,3 +38,137 @@ The complete list of supported command-line flags: | `-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 + ``` + +--- \ No newline at end of file