v0.4.2

v0.4.2 is the current version covered by this documentation. Changes since v0.4.1 are summarized below. For a development or PR build, use the documentation at that build's commit.

CLI and terminal workflow

• Named queues persist membership, per-item progress, workflow IDs and confirmed uploads across runs. Limits advance through remaining work; explicit retry and refresh keep prior progress. Independent items can continue past an uncertain submission when its durable protection remains available. See saved queues for locking, durability limits and recovery.
• Metadata title selection is available in the plain CLI and TUI. Ambiguous retained matches need an explicit choice; strict unattended mode never selects the top ambiguous match. Use exact provider IDs or permit prompts with --uac. Provider selection documents search, back, cancel and clear behavior.
• Local Input readiness explains missing or advisory facts before later tracker work. Missing media stops before unrelated tracker questions; invalid programme-language answers can be corrected at the same prompt. Plain output and the TUI show the inspected track, language and soundtrack-origin consequences.
• Clear completed duplicate checks default to Yes at tracker approval; duplicates and incomplete checks retain their separate review. An explicit remote-search waiver replaces stored remote results and survives later stages, while authoritative in-client blocks remain enforced. See tracker overrides.
• Retained results distinguish tracker submission, client delivery, preparation failure, and partial debug/site-check outcomes. Image-host progress separates uploaded, reused and failed images and explains fallback; retained HDR reports list per-format outcomes and successful artifact IDs.
• Ctrl+C coordinates worker cancellation and bounded input cleanup. Hashing can stop during processing; an OS read already in progress can delay shutdown. Auto presentation falls back to plain output only for a dashboard failure before work starts, never after cancellation. See interaction and safety.
• The obsolete --not-anime, --torrenthash, and -th options are removed. Use --anime=false and --infohash respectively. The CLI reference accounts for current commands, aliases, constrained values, defaults, and reset/clear behavior.

Metadata, media and naming

• TMDB, IMDb and TVDB candidate cards add available posters, credits, runtime, overviews and provider links. Explicit title searches leave prepared facts and draft IDs unchanged until applied. TVDB series links can fill missing sibling IDs without replacing manual selections or clears. See Input corrections.
• Multiple manual provider IDs remain independently authoritative despite conflicting cross-links. Successful data survives refresh and restart. A missing final category defaults to Movie only after provider fallback; it does not supply missing IDs or waive requirements.
• Plain season and episode numbers are accepted for manual corrections. TVDB naming-year evidence retains explicit disambiguation even without a collision result. Measured video dimensions and scan type improve automatic resolution, including portrait, anamorphic and cropped sources. See naming values and resolution detection.
• Partial-season sources retain explicit part labels and episode membership through preparation, names and duplicate checks. Unknown or contradictory ranges remain unverified; identifying all included episodes does not establish a complete season. Package checks use the torrent's intended file inventory. See media analysis.
• Decrypted 3D Blu-ray ISO input supports playlist selection, BDInfo and single-view screenshots without mounting or extraction. The torrent retains the original ISO. DVD, 2D and encrypted ISOs remain unsupported. The ISO guide lists FFmpeg/libbluray and MVC-evidence requirements.
• Blu-ray.com matching reads listings before fetching edition pages, supports one-edition or explicit all-edition inspection, retains country filtering and manual selections, and reports per-edition scores and dates. Compatible evidence survives refresh. Preparation reports current substeps, retained evidence and partial provider outcomes without treating unknown totals as measured progress. See Blu-ray edition matching.
• Non-disc TV packs use the selected first episode for HDR eligibility and offer only that episode as the HDR target; later episodes do not substitute for an ineligible primary episode. See supported HDR sources.
• Language identities preserve regional/script variants and distinguish unknown, collective and non-linguistic values. TMDB spoken-language evidence refines original-language comparison. Verified multilingual original soundtracks do not become dubs solely because they contain another language; original-language and track-origin corrections remain independent. See canonical metadata.
• Tracker preparation improves inspected audio-feature handling, compatibility-track association, subtitle-review controls, provider IDs, naming, description markup and screenshot spacing, and protocol outcome handling. Destination-specific requirements remain visible in review; consult each tracker's current rules. The tracker guide explains findings and questionnaires without publishing destination rules. Where supported, an intended-replacement setting exposes an explicit questionnaire choice; the setting alone does not authorize replacement.

Web UI, images and analysis

• Settings and release tools gain contextual help without changing saved values. Language selectors use compact summaries and multi-select dropdowns. Input warnings open and focus the relevant correction controls; saved required facts still gate duplicate navigation. See Web UI.
• Test connection checks supported integrations against current draft values without saving or uploading. Unsupported safe probes report their limits instead of claiming credential validity. Tracker authentication remains a separate action.
• Cancel active work coordinates cancellation across workflow pages and reloads. Starting a new attempt clears old cancellation feedback. Failed and partial dry runs require explicit retry; prerequisite answers continue the same pending dry run. See source lifecycle and safe first use.
• Collected tracker images load on Screenshots with normal selection, deletion and ordering. Current selections control hosted links and descriptions. Compatible navigation recovers after duplicate review while preserving edited times; imported comparison blocks remain separate.
• Preferred image-host overrides now guide automatic screenshots and DVD menus as well as analysis. Compatible saved links can be reused; destination host restrictions and fallback still apply. Multipart batches respect encoded-size and file-count limits. See Image Hosting.
• Dolby Vision screenshot previews, captures and overlays share one renderer policy. Profile 5 skips incompatible software tone mapping; supported fallback preserves actual per-image processing and reports degraded colour. Saved renderer outcomes follow the image content and hosted link. See Screenshot capture.
• Standalone HDR failures distinguish output setup/publication from source errors and report retained output paths, including partial artifacts. Audio-analysis logs explain partial outcomes and decode retries without treating decoding progress as final completion. See HDR analysis and Audio analysis.

Torrent reuse, configuration and upload safety

• --infohash selects an exact existing client torrent before ordinary discovery, with source/layout validation and fallback after a miss. It overrides ordinary skip/none search selectors; a named client still restricts lookup. It does not change client injection. See client and torrent options and the API contract.
• Torrent-client discovery checks matching top-level subfolders. --keep-folder retains a supplied folder around one selected movie/episode video while excluding sidecars. Reuse checks the requested layout and can convert an eligible one-file wrapper without new pieces.
• Each tracker retains its best compatible torrent base, preferring reuse without partial-tail hashing and applying piece-count, piece-size and file-size limits. Optional variants are no longer generated. --nohash skips trackers needing unavailable pieces. V2 and hybrid torrents still require regeneration. See Torrent preparation.
• prefer_max_16_torrent and UA_DEFAULT_PREFER_MAX_16_TORRENT are removed; imports ignore the preference and exports omit it. --max-piece-size remains supported.
• Stored-settings YAML exports publish complete snapshots with platform-specific replacement guarantees. Compatibility-only settings still save/export but no longer invalidate active workflow stages. See configuration and Settings activation.
• Per-upload anonymous choices, including false, survive reviewed projections; group visibility applies where supported. Upgrades rebuild incompatible unfinished tracker reviews while preserving compatible source facts, confirmed uploads and uncertain outcomes. See anonymous uploads.
• Debug runs normal auth, banned-group, claim, rule and duplicate checks while retaining real blocked/failed outcomes. Available inputs can still produce a redacted diagnostic payload after an approval is declined. Debug-prepared operations cannot submit through continuation or retry. Image uploads and client injection remain possible unless explicitly skipped. See debug behavior.
• Source-modification review asks once across the selected trackers and checks the selected files (plus the folder when retained). Continuations keep the approved tracker scope. See names and eligibility.
• Account maintenance guidance can report credential-expiry advice from upload responses or a recognized indefinite connection-IP restriction during authentication. Neither an imported cookie nor a read-only connection check proves upload readiness. Follow authentication recovery and the displayed guidance.
• Accepted tracker uploads remain accepted when torrent retrieval, local retention or client delivery fails. Registered torrents retain available destination detail links in reconstructed comments; downloaded metainfo remains unchanged. Captured torrent identity binds submission hashes to the reviewed artifact. See submission and retention.

Build and dependency maintenance advances the Go toolchain to 1.27.4 and updates media libraries and Web UI/site tooling. Automated checks cover sharded Linux, Windows and macOS Go suites and include the documentation lockfile in dependency scans. These changes do not imply live verification of a particular media source or integration.

Upgrade and compatibility

Stop every process and back up the complete active state directory before upgrading. Database migrations are forward-only; restore the matching backup before returning to v0.4.1. Never run old and new binaries against the same database. See Upgrading.

In addition to the storage migration below, additive migrations retain ambiguous provider candidates and per-image renderer outcomes. Existing screenshots keep known tone-mapping evidence without invented renderer history. Preparation, identity, capture, torrent-artifact and tracker-review compatibility changes can require fresh preparation and review; older automatic matches or artifacts are not silently treated as compatible. Manual corrections, confirmed submissions and uncertain outcomes retain their respective authority. An incompatible continuation must prepare again rather than repeating continuation.

Release artifacts and workflow storage

Automatically managed release files are kept together under tmp/<release>/ in the active state directory. The primary mediainfo.txt and MediaInfo.json are stored at that release folder's root; secondary inspections, analysis outputs and temporary work stay beneath the same owner. Source validation still controls reuse. Deleting a release from History removes its owned generated files, including nested outputs, while preserving active or shared artifacts and source media.

Older prepared releases require preparation again. There is no automatic migration or discovery and cleanup of the previous report-cache layout.

Workflow ownership and command receipts migrate automatically into structured SQLite rows, retaining exact immutable JSON snapshot references and historical results. The first startup may take longer while existing data is backfilled. Interrupted migration rolls back and retries on restart; uncertain ownership preserves recoverable records and defers cleanup. Follow the stopped-service backup and rollback guidance in Upgrading before opening an existing database with this version.

Remove the legacy report cache

1. Stop every upbrr binary, service and container using the state directory, including scheduled restarts.
2. Locate the active state directory using Configuration: State location. Check any configured state-path override or container volume; do not assume the current working directory is the state directory.
3. With every process still stopped, back up the complete active state directory, including its database and authentication/configuration files. Complete this state backup before deleting any cache, installing the new version or starting it against the database.
4. If that state directory contains tmp/hdr-mediainfo, verify that it is the old upbrr report cache before manually removing only that directory. If it is absent, skip this step. Do not remove all of tmp, the state directory, its database, authentication/configuration files, or source media.
5. After the backup and any applicable cleanup are complete, install the new version, start upbrr and prepare releases again to recreate validated reports in their release folders.

Follow the full upgrade procedure for installation, startup checks and rollback.