find-sources

What this skill does

# find-sources

Discover and rank media sources across YouTube, Internet Archive, Bandcamp, SoundCloud, and other platforms. Intelligently prioritizes official releases, lossless formats, and verified channels while filtering out low-quality duplicates.

## Purpose

Automate the tedious process of hunting down the best available version of media content across fragmented platforms. Instead of manually checking Bandcamp, YouTube, archive.org, and streaming services, this command orchestrates a comprehensive search and returns a ranked, deduplicated list of sources with quality scoring.

**Key Benefits**:
- **Time Savings**: Search 5+ platforms in one command instead of manual browser searches
- **Quality Assurance**: Automatically prioritizes lossless > high-bitrate > standard quality
- **Official First**: Verified channels and artist-uploaded content ranked highest
- **Deduplication**: Filters redundant sources, keeps only the best version
- **Comprehensive Coverage**: Catches rare/archival content missed by streaming services

## Parameters

### Required

**`<artist>`** - Artist or creator name to search for

Examples:
- `"Tool"`
- `"Pink Floyd"`
- `"Grateful Dead"`
- `"Tame Impala"`

### Optional Flags

**`--scope <scope>`** - Limit search scope (default: `complete`)

- `complete` - Full artist catalog (all albums, singles, live recordings)
- `album:NAME` - Specific album only (e.g., `album:"Dark Side of the Moon"`)
- `era:NAME` - Time period or tour (e.g., `era:"1990-1995"`, `era:"Lateralus Tour"`)
- `track:NAME` - Single song across all versions (e.g., `track:"Stairway to Heaven"`)

**`--tier <1-4>`** - Minimum acceptable quality tier (default: `3`)

- `1` - Official/Lossless only (FLAC, verified channels, Qobuz Hi-Res)
- `2` - High Quality+ (256kbps AAC, 1080p video, official sources)
- `3` - Standard+ (128kbps+, 720p+, most YouTube content)
- `4` - Accept all (includes phone recordings, low-quality rips)

**`--output <file>`** - Save results to YAML file (default: print to stdout)

- Absolute or relative path
- Creates parent directories if needed
- Overwrites existing file

**`--platforms <list>`** - Comma-separated platform filter (default: all)

- `youtube` - YouTube and YouTube Music
- `bandcamp` - Bandcamp artist pages
- `archive` - Internet Archive (all collections)
- `soundcloud` - SoundCloud
- `qobuz` - Qobuz Hi-Res
- `vimeo` - Vimeo

Example: `--platforms youtube,bandcamp,archive`

**`--sort <field>`** - Sort results by field (default: `quality_score`)

- `quality_score` - Tier + format + verification score (0-100)
- `tier` - Tier 1 first, then tier 2, etc.
- `upload_date` - Newest first
- `platform` - Alphabetical by platform name

**`--limit <n>`** - Maximum results to return (default: unlimited)

**`--verified-only`** - Only include verified/official sources (boolean flag)

**`--include-unavailable`** - Include geo-blocked or restricted content (default: exclude)

## Usage Examples

### Example 1: Complete Artist Catalog (High Quality+)

```bash
aiwg find-sources "Tool" --tier 2 --output tool-sources.yaml
```

**What it does**:
1. Searches Bandcamp for official Tool releases (FLAC preferred)
2. Checks YouTube for verified Tool channels and Topic channels
3. Searches Internet Archive for live recordings and official uploads
4. Filters results to Tier 2+ only (256kbps+ audio, 1080p+ video)
5. Scores and ranks all sources
6. Saves to `tool-sources.yaml`

**Expected output**: 30-50 sources including studio albums (FLAC from Bandcamp), official music videos (1080p YouTube), live concerts (archive.org soundboard recordings).

### Example 2: Specific Album (Lossless Only)

```bash
aiwg find-sources "Pink Floyd" --scope 'album:"The Dark Side of the Moon"' --tier 1 --verified-only
```

**What it does**:
1. Searches only for "The Dark Side of the Moon" album
2. Prioritizes lossless sources (FLAC, WAV, Qobuz Hi-Res)
3. Only includes verified/official channels
4. Filters out audience recordings, re-uploads, unofficial versions

**Expected output**: 3-8 sources including Qobuz 24/96 FLAC, Bandcamp official FLAC (if available), YouTube Topic channel official audio.

### Example 3: Live Era Search

```bash
aiwg find-sources "Grateful Dead" --scope 'era:"1977"' --platforms archive --output gd1977.yaml
```

**What it does**:
1. Searches only Internet Archive
2. Filters to 1977 concerts
3. Includes soundboard recordings (Tier 2) and audience recordings (Tier 3)
4. Saves comprehensive list to `gd1977.yaml`

**Expected output**: 50-100 sources (Grateful Dead has extensive archive.org presence with official taper policy).

### Example 4: Single Track Across All Versions

```bash
aiwg find-sources "Led Zeppelin" --scope 'track:"Stairway to Heaven"' --tier 2
```

**What it does**:
1. Finds all high-quality versions of "Stairway to Heaven"
2. Includes studio version, live recordings, remastered editions
3. Ranks by quality score
4. Prints to stdout (no --output specified)

**Expected output**: 10-20 sources including studio album version, live at Madison Square Garden, BBC Sessions version, 2014 remaster, etc.

### Example 5: Platform-Specific Search

```bash
aiwg find-sources "Tame Impala" --platforms youtube,bandcamp --sort upload_date --limit 10
```

**What it does**:
1. Searches only YouTube and Bandcamp
2. Sorts by upload date (newest first)
3. Limits to 10 most recent results

**Expected output**: Recent releases, new music videos, latest Bandcamp uploads.

## Workflow

### Phase 1: Parse Request

1. **Extract Artist Name** - Clean and normalize input
2. **Parse Scope** - Determine search boundaries (complete/album/era/track)
3. **Set Quality Threshold** - Minimum acceptable tier
4. **Platform Selection** - Which platforms to query (default: all)

### Phase 2: Official Channels First

**Priority Search** - Highest quality, verified sources

1. **Bandcamp**
   ```bash
   # Search Bandcamp for artist
   curl -s "https://bandcamp.com/search?q=$(echo "$ARTIST" | sed 's/ /+/g')&item_type=b"
   ```
   - Extract artist page URL
   - Check for FLAC/WAV availability
   - Record album list with formats

2. **Qobuz (if available)**
   ```bash
   # Check Qobuz for Hi-Res releases
   # Requires API key or web scraping
   ```
   - Look for 24-bit/96kHz+ releases
   - Note sample rates and bit depths

3. **YouTube Verified Channels**
   ```bash
   yt-dlp --dump-json "https://www.youtube.com/@${ARTIST_HANDLE}/videos"
   ```
   - Find verified channel (✓ badge)
   - Get video list with quality metadata
   - Filter to HD (1080p+)

4. **YouTube Topic Channels**
   ```bash
   yt-dlp "ytsearch:${ARTIST} - Topic"
   ```
   - Auto-generated official audio channels
   - Usually AAC 256kbps
   - Reliable metadata

### Phase 3: Archive Search

**Historical and Live Content**

1. **Internet Archive API**
   ```bash
   curl "https://archive.org/advancedsearch.php?q=creator:(${ARTIST})&fl[]=identifier,title,date,format,avg_rating&rows=100&output=json"
   ```
   - Filter by scope (year range for era, album title, etc.)
   - Parse formats (FLAC, MP3, Ogg)
   - Note taper/source info

2. **Etree Collection** (for jam bands)
   ```bash
   curl "https://archive.org/advancedsearch.php?q=collection:etree+AND+creator:(${ARTIST})&output=json"
   ```
   - Soundboard recordings
   - Audience recordings with quality ratings

3. **Live Music Archive**
   ```bash
   curl "https://archive.org/advancedsearch.php?q=collection:etree+AND+subject:(${ARTIST})&output=json"
   ```

### Phase 4: YouTube Comprehensive

**Broad Search with Quality Filtering**

1. **Search Query Construction**
   ```bash
   # For complete catalog
   QUERY="${ARTIST} official HD"

   # For album
   QUERY="${ARTIST} ${ALBUM_NAME} full album"

   # For track
   QUERY="${ARTIST} ${TRACK_NAME} official"
   ```

2. **Execute Search**
   ```bash
   yt-dlp --dump-json "ytsearch50:${QUERY}" | jq -r '.[]'
   ```

3. **Quality Filter**
   - Extract resolution (height >= 720 for Tier 3, >= 1080 for Tier 2)
   - Extract audio bitra