tracker: searching, comparing and downloading releases

One engine for every kind of material: common mechanics (search → breakdown → comparison → download), while the quality rules plug in via a profile per material type.

S=scripts/tracker_hunt.py                    # from the repository root

python3 $S search "Jelusick"                 # list of releases
python3 $S search "Blade Runner 2049" --facts  # + breakdown of each version
python3 $S info 6415449                      # facts on a single topic
python3 $S compare 6499624 6517503 6795598   # comparison with a recommendation
python3 $S fetch 6415449 --dir "Jelusick/Album [TR24]" --priority high

Requirements

• A rutracker account — registration is invite-only. The client authenticates with session cookies; the password itself is never stored anywhere.
• Cookies live in ~/.config/music-restoration/secrets/ (directory 700, files 600; ./install.sh bootstraps both). rutracker_cookies.txt holds one name=value per line — empty lines and # comments are ignored. Minimum set: bb_session, bb_ssl, bb_t, cf_clearance. Next to it, rutracker_ua.txt — the exact User-Agent of the browser those cookies came from (cf_clearance is bound to one IP + UA pair).
• No cookies → do not start a search. The client fails with NotLoggedError ("no cookies…") before any request goes out. Instead, tell the user how to set it up: run ./install.sh to bootstrap the secrets directory, then python3 scripts/rt_browser_refresh.py to copy the cookies from a Firefox profile — details in docs/setup.md (secrets and cf_clearance sections). scripts/doctor.py reports the missing file as WARN.

Quality profiles

The profile is picked automatically from the forum section and the topic body (for movies the rutracker title is often truncated, so the markers are also searched in the body: the Russian section labels for translation, subtitles and runtime).

Comparison is Pareto, not "one best"

compare prints a table with a score and an explanation, then the best overall pick and an alternative. Versions almost always involve a trade-off: TR24 24/44.1 vs CD 16/44.1, BDRemux 42 GB vs BDRip 1.4 GB. The skill's job is to show the difference; the decision stays with the user.

Workflow

1. Search (search), with --facts if needed.
2. Comparison (compare) — pick a version with an explanation.
3. Download (fetch) — priority high, a separate directory.
4. Check after download — scripts/audio_measure.py <dir>: from the release page you cannot tell whether this is real lossless (fake hi-res, lossy transcode). This step is mandatory when quality matters.
5. For music, next come split-flac-album (if image+cue) and release-restore.

Pitfalls (each cost time — do not relearn)

• The tracker goes down for maintenance: the page answers 200, but it is a stub saying the forum is temporarily disabled for maintenance until HH:MM MSK. Telltale sign: the page is ~1.5 KB instead of tens of KB. Work from a local .torrent in ~/Downloads, and do not treat this as an authorization failure.
• dl.php comes as a relative link (dl.php?t=…): without the base prefix https://rutracker.org/forum/ requests fails with MissingSchema.
• A private tracker does not report seeder counts in announce (seederCount = -1): do not rely on trackerStats, take seeders from the search results.
• Never take the size from the topic text — small numbers sneak in there (cover size, pieces of the tracklist). Searching by id gives the exact size.
• "TR24" means 24 bits at 44.1 kHz, not a high sample rate. True hi-res is verified after download.
• Vinyl/DSD (LP, SACD) is a different mastering, not "higher quality": noise, rumble, different dynamics. For restoration a digital master is preferable.
• Do not confuse "the alternative only exists as MP3" with "this release is MP3" — phrase it explicitly, otherwise you get a false conclusion about quality (a real mistake from a past session).
• Keep test downloads out of the dataset raw material: the enrichment loop only cleans dataset/raw/, but everything put there it will wipe.
• Never touch the user's own torrents: filter any bulk operations (pause, priority change, removal) by downloadDir.
• Stalled torrents: 0 peers → remove the torrent and clear the wanted set, otherwise the torrent keeps downloading into a deleted directory and disk space leaks.
• image+cue downloads: the track directory and the image must not be kept together if --src <dir> will later run on it (the image ends up processed as a track).