flacfetch 0.15.3__tar.gz

flacfetch-0.15.3/ARCHITECTURE.md

@@ -0,0 +1,97 @@
+# 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
+        RED[REDProvider]
+        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**: `REDProvider` 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.
+*   **RED**: "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**: (RED) Album > Single > EP.
+4.  **Health**: Seeders (RED) / Views (YouTube - implicitly handled via display).
+5.  **Quality**: Lossless > High Bitrate.
+6.  **Year (Contextual)**:
+    *   *RED*: **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".
+
+### 2.4. Security: No Hardcoded URLs
+**Design Decision**: Tracker API base URLs are **never** stored in the source code. Both `REDProvider` and `OPSProvider` require a `base_url` parameter that must be provided at runtime (typically via environment variables).
+
+**Rationale**:
+1. **Privacy**: Private trackers prefer their URLs not be publicly indexed.
+2. **Safety**: Ensures test suites cannot accidentally hit real tracker APIs without proper mocking.
+3. **Flexibility**: Allows easy switching between different tracker instances if needed.
+
+## 3. Implementation Details
+
+### RED 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.
+*   **Base URL Required**: The `base_url` constructor parameter is mandatory; if not provided, an error is raised.
+
+### 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.15.3/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.15.3/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.15.3/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: flacfetch
+Version: 0.15.3
+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,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: remote
+Requires-Dist: httpx>=0.28.0; extra == "remote"
+Requires-Dist: playwright>=1.40.0; extra == "remote"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
+Requires-Dist: pydantic>=2.0.0; extra == "api"
+Requires-Dist: httpx>=0.28.0; extra == "api"
+Requires-Dist: google-cloud-storage>=2.13.0; extra == "api"
+Requires-Dist: google-cloud-secret-manager>=2.16.0; extra == "api"
+Provides-Extra: spotify
+Requires-Dist: spotipy>=2.25.1; extra == "spotify"
+Provides-Extra: ejs
+Requires-Dist: yt-dlp-ejs>=0.3.0; extra == "ejs"
+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: pytest-asyncio>=0.23.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"
+Provides-Extra: all
+Requires-Dist: httpx>=0.28.0; extra == "all"
+Requires-Dist: playwright>=1.40.0; extra == "all"
+Requires-Dist: fastapi>=0.115.0; extra == "all"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "all"
+Requires-Dist: pydantic>=2.0.0; extra == "all"
+Requires-Dist: google-cloud-storage>=2.13.0; extra == "all"
+Requires-Dist: google-cloud-secret-manager>=2.16.0; extra == "all"
+Requires-Dist: spotipy>=2.25.1; extra == "all"
+Requires-Dist: yt-dlp-ejs>=0.3.0; extra == "all"
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-mock>=3.10.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "all"
+Requires-Dist: ruff>=0.1.0; extra == "all"
+Requires-Dist: mypy>=1.0.0; extra == "all"
+Requires-Dist: types-requests>=2.28.0; extra == "all"
+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**: RED and OPS (API integration). Uses advanced file list filtering to find specific songs within album torrents, downloading only the required track.
+    -   **Streaming Services**: Spotify (via `librespot`, requires Premium account) - CD Quality FLAC (44.1kHz/16-bit).
+    -   **Public Sources**: YouTube (via `yt-dlp`).
+-   **Smart Prioritization**:
+    -   **Official Sources**: Automatically prioritizes "Topic" channels and "Official Audio" on YouTube. Spotify results are always from official sources.
+    -   **Quality Heuristics**: 
+        -   **Trackers (RED/OPS)**: Prioritizes Lossless (FLAC) and healthy torrents (Seeders). Matches filename exactly to your query.
+        -   **Spotify**: CD-quality FLAC (44.1kHz/16-bit) via librespot capture. Prioritizes by popularity.
+        -   **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 both an API Key and API URL:
+```bash
+# RED
+export RED_API_KEY="your_api_key_here"
+export RED_API_URL="your_tracker_url_here"
+# OR
+flacfetch "..." --red-key "your_key" --red-url "your_url"
+
+# OPS
+export OPS_API_KEY="your_api_key_here"
+export OPS_API_URL="your_tracker_url_here"
+# OR
+flacfetch "..." --ops-key "your_key" --ops-url "your_url"
+```
+
+**Spotify Configuration** (Optional - requires Premium account)
+
+Spotify provides CD-quality audio (44.1kHz/16-bit) captured via librespot and converted to FLAC. This uses the official Spotify Web API for authentication (OAuth) and librespot for audio capture.
+
+**Prerequisites:**
+- Spotify Premium account
+- `librespot` binary: `brew install librespot` or `cargo install librespot`
+- `ffmpeg` for audio conversion
+
+**Setup:**
+```bash
+# 1. Install Spotify extra dependencies
+pip install flacfetch[spotify]
+
+# 2. Create a Spotify Developer App
+# Go to: https://developer.spotify.com/dashboard
+# Click "Create App"
+# Set redirect URI to: http://127.0.0.1:8888/callback
+# Note your Client ID and Client Secret
+
+# 3. Set environment variables
+export SPOTIPY_CLIENT_ID='your-client-id'
+export SPOTIPY_CLIENT_SECRET='your-client-secret'
+export SPOTIPY_REDIRECT_URI='http://127.0.0.1:8888/callback'
+
+# 4. First run will open browser for OAuth login (token cached automatically)
+flacfetch "Artist" "Title"
+
+# Disable Spotify if needed
+flacfetch "Artist" "Title" --no-spotify
+```
+
+**How it works:**
+1. Uses Spotify Web API (via spotipy) for search and playback control
+2. Starts librespot as a Spotify Connect device with OAuth token
+3. Triggers playback via Web API, captures raw PCM via pipe backend
+4. Converts PCM to FLAC using ffmpeg
+
+**Note:** The redirect URI must use `127.0.0.1` (not `localhost`) as per Spotify's updated security requirements.
+
+**Provider Priority**
+
+When multiple providers are configured, flacfetch searches them in priority order. By default: **RED > OPS > Spotify > YouTube**
+
+This means RED is searched first, and only if it returns no results will OPS be searched, then Spotify, then YouTube. This prioritizes lossless sources first, then high-quality streaming.
+
+```bash
+# Use default priority (RED > OPS > Spotify > YouTube)
+export RED_API_KEY="..."
+export RED_API_URL="..."
+export OPS_API_KEY="..."
+export OPS_API_URL="..."
+flacfetch "Artist" "Title" --auto
+
+# Custom priority (e.g., prefer Spotify over trackers)
+flacfetch "Artist" "Title" --provider-priority "Spotify,RED,OPS,YouTube"
+
+# Or via environment variable
+export FLACFETCH_PROVIDER_PRIORITY="OPS,RED,Spotify,YouTube"
+flacfetch "Artist" "Title" --auto
+
+# Disable fallback (only search highest priority provider)
+flacfetch "Artist" "Title" --auto --no-fallback
+```
+
+### Library Usage
+
+**Quick Example:**
+
+```python
+from flacfetch.core.manager import FetchManager
+from flacfetch.core.models import TrackQuery
+from flacfetch.providers.red import REDProvider
+from flacfetch.providers.ops import OPSProvider
+from flacfetch.providers.spotify import SpotifyProvider  # Optional
+from flacfetch.downloaders.spotify import SpotifyDownloader  # Optional
+
+manager = FetchManager()
+manager.add_provider(REDProvider(api_key="...", base_url="..."))
+manager.add_provider(OPSProvider(api_key="...", base_url="..."))
+
+# Spotify (requires SPOTIPY_CLIENT_ID, SPOTIPY_CLIENT_SECRET, SPOTIPY_REDIRECT_URI env vars)
+spotify_provider = SpotifyProvider()
+manager.add_provider(spotify_provider)
+manager.register_downloader("Spotify", SpotifyDownloader(provider=spotify_provider))
+
+# 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}")
+```
+
+**For comprehensive library documentation**, including:
+- Complete API reference for all classes and methods
+- Data models and type hints
+- Provider configuration options
+- Advanced usage patterns (filtering, custom sorting, batch processing)
+- Error handling best practices
+- 5+ detailed examples
+
+See **[LIBRARY.md](LIBRARY.md)** for full library API documentation.
+
+## 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.15.3/PLAN.md

@@ -0,0 +1,118 @@
+# 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., `REDProvider`, `OPSProvider`, `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
+        RED
+        OPS
+        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.
+-   **REDProvider / OPSProvider**: 
+    -   Uses `ajax.php?action=browse` with `artistname` and `filelist` parameters to find torrents containing the specific track.
+    -   Requires `base_url` parameter (set via environment variable) in addition to API key.
+    -   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 YouTube.
+
+### 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: Private Tracker Provider Integration
+-   Implement authentication (API Key + Base URL support via environment variables).
+-   Implement `REDProvider.search` and `OPSProvider.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`.