flacfetch 0.3.0__tar.gz

flacfetch-0.3.0/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# Architecture & Design
+
+This document details the architectural decisions, component design, and key learnings from the development of **flacfetch**.
+
+## 1. High-Level Architecture
+
+The system follows **Clean Architecture** principles to decouple core logic from external providers and interfaces.
+
+```mermaid
+graph TD
+    CLI[CLI Adapter] --> Core
+    Lib[Library User] --> Core
+    
+    subgraph Core
+        FM[FetchManager]
+        Models[Release, TrackQuery, Quality]
+        Interfaces[Provider, Downloader]
+    end
+    
+    FM --> Providers
+    FM --> Downloaders
+    
+    subgraph Providers
+        Redacted[RedactedProvider]
+        YouTube[YoutubeProvider]
+    end
+    
+    subgraph Downloaders
+        LibTorrent[TorrentDownloader]
+        YtDlp[YoutubeDownloader]
+    end
+```
+
+### Core Components
+
+*   **FetchManager**: The central orchestrator. It aggregates results from registered providers, applies sorting/prioritization logic, and delegates downloading.
+*   **Models**:
+    *   `Release`: Unified representation of a search result. Abstracts away differences between a Torrent and a YouTube video. Contains metadata (Year, Label, Views) and download info.
+    *   `Quality`: Value object representing format (FLAC/Opus/AAC), bitrate, and source media. Implements comparison logic (`__lt__`) for sorting.
+*   **Interfaces**:
+    *   `Provider`: Abstract base class for search sources.
+    *   `Downloader`: Abstract base class for download mechanisms.
+
+## 2. Key Design Choices
+
+### 2.1. Selective BitTorrent Downloading
+**Challenge**: Private trackers usually organize content by **Album**, but users often want a single **Track**. Downloading a 500MB FLAC album for one 30MB song is inefficient.
+**Solution**:
+*   **Search**: `RedactedProvider` uses the `filelist` API parameter to find torrents containing the specific track title.
+*   **Matching**: It parses the file list string (`filename{{{size}}}|||...`) to identify the exact target file index.
+*   **Download**: `TorrentDownloader` uses `libtorrent`'s `prioritize_files` API. It sets the target file priority to `7` (High) and all others to `0` (Skip), downloading only the necessary chunks.
+
+### 2.2. Hybrid Prioritization Logic
+**Challenge**: "Best" means different things for different sources.
+*   **Redacted**: "Best" = Original Release (Oldest), Lossless, Healthy (Seeders).
+*   **YouTube**: "Best" = Modern Codec (Newest), Official Source (Topic Channel), High Bitrate.
+**Solution**:
+The `FetchManager` implements a weighted sort key:
+1.  **Match Score**: Does the filename exactly match the query? (Crucial for filtering junk).
+2.  **Official Score**: (YouTube only) Is it a "Topic" channel or "Official Audio"? (Heavily boosted).
+3.  **Release Type**: (Redacted) Album > Single > EP.
+4.  **Health**: Seeders (Redacted) / Views (YouTube - implicitly handled via display).
+5.  **Quality**: Lossless > High Bitrate.
+6.  **Year (Contextual)**:
+    *   *Redacted*: **Oldest First** (Prefer original pressings).
+    *   *YouTube*: **Newest First** (Prefer modern Opus uploads over legacy 2011 AAC uploads).
+
+### 2.3. YouTube Quality & Reliability
+**Learnings**:
+*   **Metadata vs Reality**: YouTube metadata (via `yt-dlp`) can be misleading. Older videos might list "AAC" but provide very low bitrate (48kbps) streams even if `itag` suggests higher potential.
+*   **Bitrate Guessing**: Estimating bitrate from file size is dangerous for video containers. We switched to relying strictly on `abr` (Audio Bitrate) or known `itag` mapping (e.g., 251 -> Opus 130k).
+*   **Proxy for Quality**: Since accurate bitrate is hard to guarantee without downloading, we use **Upload Year** as a strong proxy. Videos uploaded post-2015 (and especially post-2020) almost always offer high-quality Opus streams. Pre-2015 uploads are often legacy AAC with lower fidelity.
+*   **Visuals**: The CLI color-codes the Year (Green > 2020, Red < 2015) instead of showing potentially inaccurate bitrate numbers, empowering the user to choose based on "Freshness".
+
+## 3. Implementation Details
+
+### Redacted Provider
+*   **Lazy Loading**: Fetching file lists for *every* search result is slow. We implemented a default search limit (20 groups) to prevent rate-limiting while still finding the best match.
+*   **Lossless Filter**: Hard-coded to only return `FLAC` results to ensure archival quality from trackers.
+
+### YouTube Provider
+*   **Topic Search**: Appends "topic" to search queries to surface auto-generated "Art Tracks" (high quality, static image) which are preferred over user uploads.
+*   **URL Handling**: Constructs `youtu.be` short links for easy sharing/checking.
+
+## 4. Future Improvements
+*   **Metadata Tagging**: Auto-tag downloaded files using MusicBrainz/Discogs.
+*   **Spectral Analysis**: Integrate `ffmpeg` or `sox` to verify frequency cutoffs post-download automatically.
+

flacfetch-0.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 FlacFetch Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

flacfetch-0.3.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include ARCHITECTURE.md
+include PLAN.md
+include pyproject.toml
+include requirements.txt
+recursive-include flacfetch *.py
+recursive-include tests *.py
+prune venv
+prune .github
+prune api_docs

flacfetch-0.3.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: flacfetch
+Version: 0.3.0
+Summary: Search and download high-quality audio from multiple sources
+Home-page: https://github.com/yourusername/flacfetch
+Author: Your Name
+Author-email: Andrew Beveridge <andrew@beveridge.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nomadkaraoke/flacfetch
+Project-URL: Repository, https://github.com/nomadkaraoke/flacfetch
+Project-URL: Issues, https://github.com/nomadkaraoke/flacfetch/issues
+Keywords: audio,music,flac,download,youtube,redacted,torrent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: yt-dlp>=2023.0.0
+Requires-Dist: transmission-rpc>=7.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# flacfetch
+
+[![PyPI version](https://badge.fury.io/py/flacfetch.svg)](https://pypi.org/project/flacfetch/)
+[![Python Version](https://img.shields.io/pypi/pyversions/flacfetch.svg)](https://pypi.org/project/flacfetch/)
+[![Tests](https://github.com/nomadkaraoke/flacfetch/workflows/Tests/badge.svg)](https://github.com/nomadkaraoke/flacfetch/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/nomadkaraoke/flacfetch/branch/main/graph/badge.svg)](https://codecov.io/gh/nomadkaraoke/flacfetch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**flacfetch** is a Python tool designed to search for and download high-quality audio files from various sources. It is optimized for finding specific tracks (songs) across both private music trackers and public sources, with intelligent prioritization of "Official" and "Original" releases.
+
+## Features
+
+-   **Precise Track Search**:
+    -   **Private Music Trackers**: Redacted and OPS (API integration). Uses advanced file list filtering to find specific songs within album torrents, downloading only the required track.
+    -   **Public Sources**: YouTube (via `yt-dlp`).
+-   **Smart Prioritization**:
+    -   **Official Sources**: Automatically prioritizes "Topic" channels and "Official Audio" on YouTube.
+    -   **Quality Heuristics**: 
+        -   **Trackers (Redacted/OPS)**: Prioritizes Lossless (FLAC) and healthy torrents (Seeders). Matches filename exactly to your query.
+        -   **YouTube**: Prioritizes newer uploads (Opus codec) over legacy uploads (AAC). Color-codes upload years to help you spot modern, high-quality streams (Green: 2020+, Yellow: 2015-2019, Red: <2015).
+-   **Flexible Interaction**:
+    -   **Interactive Mode**: Present search results to the user for manual selection with rich, color-coded metadata (Seeders, Views, Duration).
+    -   **Automatic Mode**: Automatically select the highest ranked release.
+-   **Smart Downloading**:
+    -   **Selective BitTorrent**: Uses Transmission daemon to download *only* the specific file matching your search query from larger album torrents (saving bandwidth).
+    -   **Direct Downloads**: Handles HTTP/Stream downloads for public sources.
+
+## Requirements
+
+-   Python 3.10+
+-   `requests`
+-   `yt-dlp`
+-   `transmission-rpc`
+-   **Transmission** (daemon) - *Required for BitTorrent downloads* (Optional if only using YouTube)
+
+### Installing Transmission
+
+Transmission is a lightweight, cross-platform BitTorrent client with RPC support.
+
+-   **Ubuntu/Debian**: `sudo apt install transmission-daemon`
+-   **macOS**: `brew install transmission-cli`
+-   **Windows**: Download from [transmissionbt.com](https://transmissionbt.com)
+
+flacfetch will automatically start the transmission daemon if it's not running.
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install flacfetch
+```
+
+### From Source
+
+```bash
+git clone https://github.com/nomadkaraoke/flacfetch.git
+cd flacfetch
+pip install .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/nomadkaraoke/flacfetch.git
+cd flacfetch
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### CLI Usage
+
+**Standard Search (Artist - Title)**
+```bash
+flacfetch "Seether - Tonight"
+```
+
+**Explicit Arguments (Recommended for precision)**
+```bash
+flacfetch --artist "Seether" --title "Tonight"
+```
+
+**Auto-download Highest Quality**
+```bash
+flacfetch --auto --artist "Seether" --title "Tonight"
+```
+
+**Output Options**
+```bash
+# Specify output directory
+flacfetch --artist "Seether" --title "Tonight" -o ~/Music
+
+# Auto-rename to "ARTIST - TITLE.ext"
+flacfetch --artist "Seether" --title "Tonight" --rename
+
+# Specify exact filename
+flacfetch --artist "Seether" --title "Tonight" --filename "my_song"
+
+# Combine options
+flacfetch --artist "Seether" --title "Tonight" -o ~/Music --rename
+```
+
+**Verbose Logging**
+```bash
+flacfetch -v "Seether - Tonight"
+```
+
+**Configuration**
+
+To use private music trackers, you must provide an API Key:
+```bash
+# Redacted
+export REDACTED_API_KEY="your_api_key_here"
+# OR
+flacfetch "..." --redacted-key "your_key"
+
+# OPS
+export OPS_API_KEY="your_api_key_here"
+# OR
+flacfetch "..." --ops-key "your_key"
+```
+
+**Provider Priority**
+
+When multiple providers are configured, flacfetch searches them in priority order. By default: **Redacted > OPS > YouTube**
+
+This means Redacted is searched first, and only if it returns no results will OPS be searched, then YouTube. This is useful for conserving buffer on trackers with stricter limits.
+
+```bash
+# Use default priority (Redacted > OPS > YouTube)
+export REDACTED_API_KEY="..."
+export OPS_API_KEY="..."
+flacfetch "Artist" "Title" --auto
+
+# Custom priority
+flacfetch "Artist" "Title" --provider-priority "OPS,Redacted,YouTube"
+
+# Or via environment variable
+export FLACFETCH_PROVIDER_PRIORITY="OPS,Redacted,YouTube"
+flacfetch "Artist" "Title" --auto
+
+# Disable fallback (only search highest priority provider)
+flacfetch "Artist" "Title" --auto --no-fallback
+```
+
+### Library Usage
+
+```python
+from flacfetch.core.manager import FetchManager
+from flacfetch.core.models import TrackQuery
+from flacfetch.providers.redacted import RedactedProvider
+from flacfetch.providers.ops import OPSProvider
+
+manager = FetchManager()
+manager.add_provider(RedactedProvider(api_key="..."))
+manager.add_provider(OPSProvider(api_key="..."))
+
+# Search for a specific track
+results = manager.search(TrackQuery(artist="Seether", title="Tonight"))
+best = manager.select_best(results)
+
+if best:
+    # Download returns the path to the downloaded file
+    file_path = manager.download(
+        best, 
+        output_path="./downloads",
+        output_filename="Seether - Tonight"  # Optional: custom filename
+    )
+    print(f"Downloaded to: {file_path}")
+```
+
+## Architecture & Design
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture, design choices, and implementation learnings.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Legal Disclaimer
+
+This tool is intended for use with content to which you have legal access. Users are responsible for complying with all applicable laws and terms of service for the supported providers.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

flacfetch-0.3.0/PLAN.md

@@ -0,0 +1,117 @@
+# Architecture & Implementation Plan
+
+## 1. High-Level Architecture
+
+The system will be designed using **Clean Architecture** principles to separate concerns between the core logic, external interfaces (CLI/Library), and infrastructure (APIs/Downloaders).
+
+### Core Components
+
+1.  **Orchestrator (`FetchManager`)**: The main entry point that coordinates searching, selection, and downloading.
+2.  **Domain Models**:
+    -   `TrackQuery`: Input data (Artist, Title).
+    -   `Release`: Represents a finding (Source, Quality, Metadata, Download Link/Magnet, **Target File**).
+    -   `Quality`: Value object for audio quality (Format, Bitrate, Source Media) with comparison logic.
+3.  **Interfaces (Abstract Base Classes)**:
+    -   `Provider`: Interface for searching (e.g., `RedactedProvider`, `YoutubeProvider`).
+    -   `Downloader`: Interface for retrieving content (e.g., `TorrentDownloader`, `HttpDownloader`).
+    -   `UserInterface`: Interface for interaction (handling selection prompts).
+
+### Component Diagram
+
+```mermaid
+graph TD
+    CLI[CLI Adapter] --> Core
+    Lib[Library User] --> Core
+    
+    subgraph Core
+        FM[FetchManager]
+        QS[QualitySorter]
+        Handler[InteractionHandler]
+    end
+    
+    FM --> Providers
+    FM --> Downloaders
+    
+    subgraph Providers
+        Redacted
+        Bandcamp
+        YouTube
+    end
+    
+    subgraph Downloaders
+        LibTorrent
+        YtDlp
+        DirectHttp
+    end
+```
+
+## 2. Detailed Design
+
+### 2.1 Provider System
+Each provider implements a `search(query: TrackQuery) -> List[Release]` method.
+-   **RedactedProvider**: 
+    -   Uses `ajax.php?action=browse` with `artistname` and `filelist` parameters to find torrents containing the specific track.
+    -   Parses the `fileList` field in the response to identify the specific file within the torrent that matches the requested song.
+    -   Prioritizes "Album" releases (Type 1) and original release years when presenting options.
+-   **PublicProviders**: Wrappers around `yt-dlp` or scraping logic for Bandcamp/Soundcloud.
+
+### 2.2 Quality & Selection Logic
+-   **Quality Class**: Implements `__lt__`, `__eq__` to allow sorting.
+    -   Hierarchy: `FLAC 24bit` > `FLAC 16bit` > `MP3 320` > `AAC` > `Other`.
+-   **Auto-Selection**: `FetchManager` sorts results by `Quality` and picks the top.
+-   **Interactive Selection**: `FetchManager` delegates to `InteractionHandler`.
+    -   **CLI Implementation**: Prints list to stdout, reads index from stdin.
+    -   **Library Implementation**: Accepts a callable/hook passed during initialization or method call.
+
+### 2.3 Downloader System
+-   **TorrentDownloader**: Uses `libtorrent`.
+    -   **Selective Downloading**: Uses the `target_file` information from the `Release` to set file priorities. All files are set to priority 0 (skip) except the target song file, which is set to priority 7 (high).
+    -   Manages session, adds magnet/torrent file, monitors progress, alerts on completion.
+-   **HttpDownloader**: Standard HTTP GET or `yt-dlp` process.
+
+## 3. Implementation Plan
+
+### Phase 1: Core & Interfaces
+-   Define `TrackQuery`, `Release`, `Quality` data classes.
+-   Define `Provider` and `Downloader` abstract base classes (ABCs).
+-   Implement `Quality` comparison logic.
+
+### Phase 2: Redacted Provider Integration
+-   Implement authentication (API Key support).
+-   Implement `RedactedProvider.search` using specific `artistname` and `filelist` filtering.
+-   Parse `fileList` string (format: `filename{{{size}}}|||...`) to find target track.
+-   Parse results into `Release` objects, including `target_file` metadata.
+
+### Phase 3: BitTorrent Integration
+-   Set up `libtorrent` session management.
+-   Implement `TorrentDownloader` with selective file downloading support.
+-   Ensure protocol compatibility.
+
+### Phase 4: Public Providers
+-   Implement `YoutubeProvider` using `yt-dlp`.
+-   Implement `HttpDownloader`.
+
+### Phase 5: CLI & Library API
+-   Build `FetchManager` to tie it all together.
+-   Implement CLI with separated `--artist` and `--title` arguments for precision.
+-   Implement `ConsoleInteractionHandler` (CLI) and `CallbackInteractionHandler` (Library).
+
+## 4. Testing Strategy
+
+### 4.1 Unit Testing (`pytest`)
+-   **Domain Logic**: Test `Quality` sorting and `FetchManager` flow (mocking providers).
+-   **Providers**: Test API response parsing using mocked JSON responses (recorded from actual API calls or synthesized based on docs).
+-   **Downloaders**: Mock `libtorrent` session and file system operations.
+
+### 4.2 Integration Testing
+-   Test the "Search -> Select -> Download" pipeline with a "MockProvider" and "MockDownloader" to ensure the architecture holds together without hitting real external services.
+
+### 4.3 End-to-End Testing (Manual/Staging)
+-   Run against real APIs (limited) to verify contract assumptions.
+
+## 5. Technology Stack
+-   **Language**: Python 3.10+
+-   **HTTP Client**: `httpx` (async support) or `requests`.
+-   **Torrent**: `python-libtorrent` (via system package or pip).
+-   **CLI**: `argparse` (stdlib).
+-   **Testing**: `pytest`, `pytest-mock`.

flacfetch-0.3.0/README.md

@@ -0,0 +1,187 @@
+# flacfetch
+
+[![PyPI version](https://badge.fury.io/py/flacfetch.svg)](https://pypi.org/project/flacfetch/)
+[![Python Version](https://img.shields.io/pypi/pyversions/flacfetch.svg)](https://pypi.org/project/flacfetch/)
+[![Tests](https://github.com/nomadkaraoke/flacfetch/workflows/Tests/badge.svg)](https://github.com/nomadkaraoke/flacfetch/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/nomadkaraoke/flacfetch/branch/main/graph/badge.svg)](https://codecov.io/gh/nomadkaraoke/flacfetch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**flacfetch** is a Python tool designed to search for and download high-quality audio files from various sources. It is optimized for finding specific tracks (songs) across both private music trackers and public sources, with intelligent prioritization of "Official" and "Original" releases.
+
+## Features
+
+-   **Precise Track Search**:
+    -   **Private Music Trackers**: Redacted and OPS (API integration). Uses advanced file list filtering to find specific songs within album torrents, downloading only the required track.
+    -   **Public Sources**: YouTube (via `yt-dlp`).
+-   **Smart Prioritization**:
+    -   **Official Sources**: Automatically prioritizes "Topic" channels and "Official Audio" on YouTube.
+    -   **Quality Heuristics**: 
+        -   **Trackers (Redacted/OPS)**: Prioritizes Lossless (FLAC) and healthy torrents (Seeders). Matches filename exactly to your query.
+        -   **YouTube**: Prioritizes newer uploads (Opus codec) over legacy uploads (AAC). Color-codes upload years to help you spot modern, high-quality streams (Green: 2020+, Yellow: 2015-2019, Red: <2015).
+-   **Flexible Interaction**:
+    -   **Interactive Mode**: Present search results to the user for manual selection with rich, color-coded metadata (Seeders, Views, Duration).
+    -   **Automatic Mode**: Automatically select the highest ranked release.
+-   **Smart Downloading**:
+    -   **Selective BitTorrent**: Uses Transmission daemon to download *only* the specific file matching your search query from larger album torrents (saving bandwidth).
+    -   **Direct Downloads**: Handles HTTP/Stream downloads for public sources.
+
+## Requirements
+
+-   Python 3.10+
+-   `requests`
+-   `yt-dlp`
+-   `transmission-rpc`
+-   **Transmission** (daemon) - *Required for BitTorrent downloads* (Optional if only using YouTube)
+
+### Installing Transmission
+
+Transmission is a lightweight, cross-platform BitTorrent client with RPC support.
+
+-   **Ubuntu/Debian**: `sudo apt install transmission-daemon`
+-   **macOS**: `brew install transmission-cli`
+-   **Windows**: Download from [transmissionbt.com](https://transmissionbt.com)
+
+flacfetch will automatically start the transmission daemon if it's not running.
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install flacfetch
+```
+
+### From Source
+
+```bash
+git clone https://github.com/nomadkaraoke/flacfetch.git
+cd flacfetch
+pip install .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/nomadkaraoke/flacfetch.git
+cd flacfetch
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### CLI Usage
+
+**Standard Search (Artist - Title)**
+```bash
+flacfetch "Seether - Tonight"
+```
+
+**Explicit Arguments (Recommended for precision)**
+```bash
+flacfetch --artist "Seether" --title "Tonight"
+```
+
+**Auto-download Highest Quality**
+```bash
+flacfetch --auto --artist "Seether" --title "Tonight"
+```
+
+**Output Options**
+```bash
+# Specify output directory
+flacfetch --artist "Seether" --title "Tonight" -o ~/Music
+
+# Auto-rename to "ARTIST - TITLE.ext"
+flacfetch --artist "Seether" --title "Tonight" --rename
+
+# Specify exact filename
+flacfetch --artist "Seether" --title "Tonight" --filename "my_song"
+
+# Combine options
+flacfetch --artist "Seether" --title "Tonight" -o ~/Music --rename
+```
+
+**Verbose Logging**
+```bash
+flacfetch -v "Seether - Tonight"
+```
+
+**Configuration**
+
+To use private music trackers, you must provide an API Key:
+```bash
+# Redacted
+export REDACTED_API_KEY="your_api_key_here"
+# OR
+flacfetch "..." --redacted-key "your_key"
+
+# OPS
+export OPS_API_KEY="your_api_key_here"
+# OR
+flacfetch "..." --ops-key "your_key"
+```
+
+**Provider Priority**
+
+When multiple providers are configured, flacfetch searches them in priority order. By default: **Redacted > OPS > YouTube**
+
+This means Redacted is searched first, and only if it returns no results will OPS be searched, then YouTube. This is useful for conserving buffer on trackers with stricter limits.
+
+```bash
+# Use default priority (Redacted > OPS > YouTube)
+export REDACTED_API_KEY="..."
+export OPS_API_KEY="..."
+flacfetch "Artist" "Title" --auto
+
+# Custom priority
+flacfetch "Artist" "Title" --provider-priority "OPS,Redacted,YouTube"
+
+# Or via environment variable
+export FLACFETCH_PROVIDER_PRIORITY="OPS,Redacted,YouTube"
+flacfetch "Artist" "Title" --auto
+
+# Disable fallback (only search highest priority provider)
+flacfetch "Artist" "Title" --auto --no-fallback
+```
+
+### Library Usage
+
+```python
+from flacfetch.core.manager import FetchManager
+from flacfetch.core.models import TrackQuery
+from flacfetch.providers.redacted import RedactedProvider
+from flacfetch.providers.ops import OPSProvider
+
+manager = FetchManager()
+manager.add_provider(RedactedProvider(api_key="..."))
+manager.add_provider(OPSProvider(api_key="..."))
+
+# Search for a specific track
+results = manager.search(TrackQuery(artist="Seether", title="Tonight"))
+best = manager.select_best(results)
+
+if best:
+    # Download returns the path to the downloaded file
+    file_path = manager.download(
+        best, 
+        output_path="./downloads",
+        output_filename="Seether - Tonight"  # Optional: custom filename
+    )
+    print(f"Downloaded to: {file_path}")
+```
+
+## Architecture & Design
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture, design choices, and implementation learnings.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Legal Disclaimer
+
+This tool is intended for use with content to which you have legal access. Users are responsible for complying with all applicable laws and terms of service for the supported providers.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

flacfetch-0.3.0/flacfetch/__init__.py

@@ -0,0 +1,6 @@
+"""flacfetch - Search and download high-quality audio from multiple sources."""
+
+__version__ = "0.3.0"
+__author__ = "Andrew Beveridge"
+__email__ = "andrew@beveridge.uk"
+