CHANGELOG.md

Changelog

All notable changes to this project will be documented here.

v0.9.20 — Community Cache Publish Reset Endpoint Fix

High-Level

This release is a focused community-cache publish stability patch. It fixes the GitHub branch-reset path used during manual and automated publish runs so Retreivr can recover cleanly after branch cleanup, rejected PRs, and stale publish-branch reuse without tripping over the wrong GitHub refs endpoint.

Added

• Regression coverage for resetting an existing publish branch through GitHub’s git/refs update endpoint.

Changed

• Release-facing docs, highlights, Docker examples, and starter defaults now point to v0.9.20.

Fixed

• Community-cache publish branch resets now call the correct GitHub API path when force-updating an existing publish branch.
• Manual publish runs no longer fail with a 404 during the branch-reset step after the remote publish branch has been recreated or needs to be repointed at main.

v0.9.19 — Search UX Hardening + Plugin Setup Fixes

High-Level

This release is a bug-fix and usability pass focused on the day-to-day operator surface. Video search results now use the same modern grid treatment as the newer music views, hover previews feel more alive, Music Mode respects its configured default audio format again, and the Jellyfin plugin setup flow is hardened so real external testing can continue.

Added

• Responsive grid layout for standard video search result cards.
• Muted hover-preview playback for supported video result cards after a short delay.
• Source-aware external action labels such as Open in YouTube and Open in SoundCloud.

Changed

• Video result cards now share the newer grid-first presentation language already used for music artist and album search results.
• Grid-card hover/focus states and narrow-viewport spacing were tightened so search results feel more intentional on both desktop and mobile.
• Release-facing docs, highlights, Docker examples, and starter defaults now point to v0.9.19.

Fixed

• Home Music Mode now reapplies its configured default format correctly instead of falling back to mp3 after config reloads.
• Video result card actions are aligned more consistently, including centered external-link buttons and clearer action ordering.
• Jellyfin plugin configuration now uses plugin-owned config endpoints and explicit save handling instead of depending on Jellyfin’s generic plugin-config round-trip behavior.

v0.9.18 — Community Cache Publish Branch Reset + Sync Docs

High-Level

This release closes the last major community-cache publish loop around stale rejected PR branches. Retreivr now resets orphaned publish branches back to clean main before republishing, keeps the public dataset contract strict around canonical youtube source naming, and improves operator-facing documentation for local cache sync behavior.

Added

• Regression coverage for resetting stale publish branches when no open PR exists for the active publish branch.
• Operator-facing documentation for resolution_api local cache sync fields, intended usage, and UI actions.

Changed

• Community-cache publishing now treats a closed or rejected publish PR as a clean-reset boundary instead of continuing to reuse the stale branch contents indefinitely.
• Release-facing docs, highlights, Docker examples, and starter defaults now point to v0.9.18.

Fixed

• Rejected or closed publish branches no longer keep replaying old invalid dataset files into later publish attempts.
• Local cache sync settings are now documented clearly enough to distinguish single-node installs from upstream-mirror sync setups.

v0.9.17 — Community Cache Contract Hardening + Export Tag Ordering

High-Level

This release is a hardening pass on the new resolution-network and library-integration foundations from v0.9.16. It tightens community-cache publishing against the public dataset contract, makes export copies inherit finalized music tags deterministically, and prepares the runtime/docs/examples for a cleaner release and deployment cycle.

Added

• Regression coverage for community-cache publish source normalization so youtube_music inputs are emitted as cache-safe youtube transport records.
• Regression coverage for synchronous final music metadata application before post-finalization export copies are written.

Changed

• Community-cache publish merge logic now normalizes legacy queued proposals and existing branch records so stale youtube_music source values are rewritten into the canonical dataset contract during publish.
• Community-cache backfill now treats unresolved release-enrichment edge cases as structured skips instead of noisy hard failures.
• Release-facing docs, highlights, Docker examples, and starter defaults now point to v0.9.17.

Fixed

• Post-finalization copy exports no longer race ahead of music metadata tagging; export targets now inherit the finalized tagged canonical file state.
• Live publish proposals and merged cache records now conform to the cache repo’s youtube-only source policy even when the originating runtime source was youtube_music.
• Community-cache default repo/docs wiring remains aligned to the canonical retreivr-community-cache repository naming.

v0.9.16 — Resolution Network Foundations + Jellyfin Plugin Bootstrap

High-Level

This release expands Retreivr from a deterministic acquisition engine into the early foundation of a shared resolution network. It adds a first-class Resolution API, local-first community cache workflows, publish/backfill controls, and the initial Jellyfin plugin integration path built around the new API and community dataset model.

Added

• Versioned Resolution API with public-facing infrastructure endpoints for single resolve, bulk resolve, submit, verify, stats, health, snapshot, and diff sync.
• Local-first community cache lookup flow backed by a persistent on-node dataset mirror with remote fallback and deterministic best-source selection.
• Manual Community Cache controls in Settings for Run Publish Now, Backfill Library, publish/sync status, and richer runtime visibility.
• Historical community-cache backfill workflow and CLI for scanning the canonical music library, repairing missing MusicBrainz tagging when possible, and emitting publish proposals for previously acquired files.
• Normalized resolution availability model across the new API and runtime flows: verified, pending, not_found, and local_only.
• Auto-verify and unresolved-MBID queue plumbing so successful acquisitions strengthen local resolution state and unresolved lookups are captured for later network fill.
• Local cache sync API/operator workflow for pulling remote resolution data into the local node as a first-class operational action.
• Section 3 architecture baseline checklist in project management docs to keep future work aligned with the long-term network vision.
• Separate Jellyfin plugin repository bootstrap aligned to the Resolution API contract, including release automation, manifest-based installation, backend status, and a first minimal in-plugin music search/acquisition UI.

Changed

• Community cache publishing now prefers stable publisher identity for branch naming and tighter trusted-branch policy alignment.
• Cache lookup and resolution flows were reworked around the shared dataset contract instead of treating the community cache as a thin optional side path.
• Retreivr documentation and runtime guidance now frame the project more clearly as acquisition infrastructure plus an emerging shared resolution layer.
• Plugin-side docs now direct operators to the Retreivr Docker starter bundle as the primary fast-start backend path.

Fixed

• Music library export targets now integrate cleanly with post-finalization library workflows without mutating canonical files.
• Music Mode full-album queueing was hardened for duplicate reporting, empty-release variants, and truthful queue visibility.
• Jellyfin plugin release packaging/manifest flow now produces installable release assets with valid checksums, icon metadata, and stable repository-manifest behavior.
• Jellyfin plugin settings persistence was hardened so saved backend URLs and toggles survive round-trips correctly.

v0.9.15 — Library Import Overhaul + Queue Recovery + Live Status

High-Level

This release turns library import into a first-class operational workflow. Retreivr now resolves fuzzy Apple Music XML imports with a dedicated import-aware profile, exposes truthful batch and queue status in the UI/API, and adds recovery controls for stale or blocked jobs so large imports are easier to trust and operate.

Added

• Import-aware MusicBrainz resolution profile for library imports, including album_artist support, batch-context scoring, softer duration handling, and controlled fallback behavior for non-ideal release candidates.
• Persisted import-batch and import-item records with per-track outcomes, rejection reasons, scoring details, duplicate linkage, and selected release bucket metadata.
• New queue recovery actions in the Status page: Cancel Active, Recover Stale Jobs, Clear Failed, and Clear Queue.
• Expanded live status payload and UI sections for active jobs, queue health, stale-job counts, import progress, and recent import-batch summaries.
• Music library integration settings and post-finalization export targets for canonical music files, including flat-folder copy targets and optional AAC transcode targets for watched-library workflows such as Apple Music auto-import or portable-device sync.

Changed

• Library import processing now records batch-level progress and compact completion summaries instead of relying on noisy per-track logs.
• Duplicate handling for import-resolved canonical jobs now classifies active, completed, failed, and stale rows instead of silently skipping everything as a generic duplicate.
• Operations Status layout in the web UI was reorganized into clearer responsive sections that better use available width and hide disabled operator subsections.
• Watcher status logging now emits on meaningful state transitions instead of repeating redundant idle/downtime chatter.

Fixed

• Watcher downtime no longer appears to pause import execution or queue processing in logs; watcher pause semantics are now clearer and status-driven.
• Stale claimed or otherwise blocked queue rows can now be recovered so they stop wedging large import runs indefinitely.
• Status page counters and labels now better distinguish queue activity, active work, import progress, and subsystem state.
• Music Mode full-album download buttons now report truthful queue results instead of marking albums as queued when every expanded track was skipped as a duplicate or when queue persistence was unavailable.

v0.9.14 — Community Cache Publisher Automation

High-Level

This release turns community-cache contribution into a built-in workflow. Retreivr can now take verified local resolution matches, stage them through the existing outbox, and automatically publish PR-ready dataset updates to the community cache repository on a schedule.

Added

• Internal community-cache publisher worker that ingests verified outbox proposals, batches them by recording MBID, updates community dataset files, and opens or updates a GitHub pull request automatically.
• Community Cache settings section in the web UI for lookup, proposal emission, repo/branch targeting, PR behavior, polling interval, batch size, and token env-var configuration.
• New config defaults for automated community-cache publishing, including repo, branch, polling, token env, and batch-size controls.

Changed

• Community-cache contribution is now a complete in-app flow: successful verified matches can emit to the outbox and be picked up by the internal publisher worker without a manual export step.
• Runtime config updates now refresh community-cache publisher scheduling without requiring a restart.

v0.9.13 — Review Queue + Recoverability Hardening

High-Level

This release replaces the old filesystem-only music review hold area with a proper internal review queue and operator workflow. It also hardens recoverable runtime failure handling so transient watcher/metadata conditions are less noisy and less likely to look catastrophic in logs.

Added

• Dedicated Review page in the web UI for low-confidence music matches.
• Internal review queue storage under Retreivr-managed app data instead of the public /downloads tree.
• Inline review preview, detailed quarantine reasons, and batch accept/reject controls.
• Home-page pending-review alert and Review-nav badge count.

Changed

• Accepted review items now move from internal quarantine storage into the canonical music library only after explicit operator approval.
• Accepted review items now promote the original failed music job into a completed acquired file so future dedupe behaves correctly.

Fixed

• Music review/quarantine jobs now execute correctly against the internal review storage root instead of failing path validation against /downloads.
• AcoustID empty-result cases no longer crash the metadata worker.
• Recoverable watcher supervisor network/DNS failures now log as warnings instead of full crash-style tracebacks.
• Recoverable metadata-worker conditions now log more quietly instead of producing unnecessary stack traces.

v0.9.12 — Music Finalization Hardening

High-Level

This release tightens the finalization path for music downloads so partially processed files are less likely to appear in the final library. It also hardens final file moves for cross-filesystem setups, where temp and destination paths may live on different mounts.

Changed

• Music downloads now complete metadata tagging while still in the temp location before the final library move.
• Music, video, and music-video finalization paths now use a safer destination-directory temp file strategy when a direct atomic rename is not possible across filesystems.
• Music review/quarantine items now route into __NEEDS_REVIEW__ so the folder stays pinned near the top when sorted alphabetically.

Fixed

• Reduced the chance of exposing an untagged or partially processed music file at the final destination when tagging or post-processing fails.
• Cross-filesystem finalization no longer falls back to a visible copy directly into the final destination path before completion.
• Home playlist file imports in Music and Music Video modes now honor the active destination and mode-specific format defaults instead of falling back to generic download locations.
• Music Mode full-album downloads now preserve the selected audio format (for example m4a) across per-track enqueue expansion.
• Music Mode direct-URL downloads now read the correct mode-specific format selector instead of the generic video format control.

v0.9.11 — Provenance + Reconcile + Defaults Hardening

High-Level

This release is a practical hardening step toward v1.0.0. It strengthens file traceability, expands library reconciliation beyond music-only workflows, and tightens destination/default behavior so operators can move existing libraries into Retreivr with less duplicate risk and less ambiguity.

Added

• Retreivr provenance tags embedded into music downloads and video/music-video downloads.
• Library reconcile workflow in Settings for backfilling known media on disk into Retreivr database state.
• Operator guide for v1.0 expectations and download-default behavior.
• Mode-specific Home default format controls for Video, Music Video, and Music workflows.

Changed

• Library reconcile now scans audio and video files, not only music files.
• Home destination and format defaults were tightened so Video, Music Video, and Music modes resolve more predictably.
• Dedicated music-search defaults now align better with the newer Home music destination model.
• Version resolution for provenance/runtime metadata now prefers explicit runtime version, then installed package metadata, then project version from source checkout.

Fixed

• Full-album music downloads now honor the selected Music destination instead of falling back to the single-download folder.
• Reconciled music can now participate in stronger duplicate prevention through global ISRC awareness and canonical-ID fallback matching.
• Settings download-default layout was cleaned up so destinations and format selectors are clearer and mode-specific.

v0.9.10 — Watcher/Telegram Hardening + Config Upgrade Safety

High-Level

This release is a focused hardening pass after v0.9.9: watcher reliability was tightened, watcher Telegram batching was made less noisy and more accurate, and config upgrade/default behavior was made safer for existing user installations.

Changed

• Music download flow now de-emphasizes/skips pre-download metadata probe in music paths to reduce avoidable retries and improve determinism.
• Added music candidate cooldown controls to avoid repeatedly selecting recently failing candidates.
• Config loading now backfills missing keys recursively from defaults and persists them on load without overwriting existing user-provided values.
• Default-template backfill no longer injects sample/demo entities (for example example_account, sample playlists) into real user configs.

Fixed

• Watcher startup now resets persisted poll state for configured playlists, forcing immediate polling after container/app restart before adaptive backoff resumes.
• Watcher polling no longer hard-skips when OAuth client is unavailable; it now attempts yt-dlp fallback for playlist fetch.
• Subscribe-mode watcher detection no longer misses new videos when seen entries appear first; newly detected subscribe IDs are marked seen at detection time.
• Watcher batch orchestration now prefers full poll coverage across watched playlists (with bounded max wait), reducing one-item/one-message spam behavior.
• Watcher Telegram dispatch now includes cooldown-aware batching and improved attempted-count accounting.
• Watcher summary dispatch now waits for terminal job states (bounded) before send, improving post-download summary timing and attempted-item resolution.
• Watcher skew/startup idle behavior hardened to prevent long “stuck waiting” windows from stale persisted next_poll_at values.
• OAuth refresh logging wording clarified (Refreshing credentials - Attempt X/Y and explicit success line).
• OAuth helper modal sizing in the web UI now respects viewport height and keeps controls reachable on smaller browser windows.

v0.9.9 — Settings IA Overhaul + UX Consistency + Runtime Notification Fixes

High-Level

This release focuses on configuration clarity, safer control flow, and runtime reliability. The former long Config page was redesigned into a structured Settings experience, Home mode controls were unified, and key operational regressions in scheduler persistence and Telegram reporting were fixed.

Added

• Redesigned Settings information architecture (sectioned navigation, focused section view, advanced-mode gating, and mobile selector fallback).
• Mode-specific Home destination defaults for Video/Music/Music Video were formalized in settings.

Changed

• Home control behavior was unified across Video/MV/Music flows (shared delivery semantics, consistent destination handling, and expanded format surfacing including m4a where applicable).
• YouTube playlist/account configuration flow was streamlined (normalized playlist ID handling, constrained account selection, and clearer add/delete actions).
• Settings layout responsiveness was hardened across desktop/tablet/mobile to reduce section-switch and resize inconsistencies.

Fixed

• Scheduler enabled-state save/apply flow now respects user toggles after Save Schedule / Save Config.
• Telegram scheduler/watcher summaries now resolve and display human-readable video titles (instead of only YouTube IDs) in attempted-item lists.
• Settings section navigation/selection no longer triggers unintended scroll/hash jumps during category changes.

v0.9.8 — Fast Discovery + Video Preview + Adapter Extensibility

High-Level

This release focuses on homepage discovery responsiveness and operator usability. Search now renders incrementally as sources resolve, lightweight video discovery is prioritized, and supported sources can be previewed inline before enqueue. Deterministic acquisition and download behavior remain unchanged.

Added

• Homepage video preview flow with Preview action on result cards for supported adapters.
• Preview trigger parity on title/thumbnail clicks (same behavior as the Preview button).
• Structured custom adapter framework with user-facing config/custom_search_adapters.example.yaml template.
• New video discovery adapters integrated for rumble and archive_org.
• Discovery timing instrumentation and source-level adapter progress logging.
• New API endpoint GET /api/version/latest to resolve latest version from GHCR tags (with release fallback).

Changed

• Search discovery pipeline refactored for lightweight-first behavior:
  • canonical metadata resolution removed from initial generic/video discovery path
  • strict per-source timeout budget for discovery
  • bounded discovery result set per source
  • fallback/retry behavior for timed-out sources without blocking first visible results
• YouTube lightweight discovery migrated to Innertube search (youtubei/v1/search) for fast candidate return.
• Homepage results rendering now updates progressively as adapters resolve (no all-at-once batch wait).
• Candidate row rendering is now non-blocking: rows render first, job-state enrichment follows asynchronously.
• Home polling loop hardened to prevent overlapping async polls and reduce UI update latency.
• Search DB connections tuned for concurrent read/write responsiveness (WAL, busy_timeout) during progressive candidate writes.
• Source selection UX refined:
  • dynamic source list from backend
  • video-mode source filtering to remove non-video adapters from the selection list
• Info page version check now tracks GHCR-published versions (container-first) instead of browser-side GitHub release lookup.

Removed

• Legacy local YouTube search cache pipeline and schema artifacts (search_query_cache and related indexes).
• x and bitchute default source adapter exposure from active source selection paths.

Fixed

• Multi-source visibility issue where one adapter’s results could hide or starve others in combined searches.
• Homepage candidate refresh race conditions that caused delayed or dropped incremental rows.
• Rumble/archive preview wiring and embed behavior reliability on homepage preview modal.
• Search-card metadata regressions (including posted-date rendering on result cards).

Upgrade Notes

• No required config migration for existing installs.
• To add site-search adapters, copy config/custom_search_adapters.example.yaml to config/custom_search_adapters.yaml and ensure custom_search_adapters_file is set in config/config.json.

v0.9.7 — Community Cache + Local Search Cache + Watcher/Telegram Hardening

High-Level

This release improves cache-first search/resolution performance, stabilizes watcher/Telegram reporting, and refines music/music-video UX without changing deterministic scoring thresholds. Added Music Video Mode with similar UX as Music Mode, but attempts to download official music videos from official channels as priority while still embedding musicbrainz metadata.

Added

• Community transport cache lookup + publish outbox (local JSONL proposals, opt-in).
• Local SQLite search cache for homepage search with cache-first replay + background refresh.
• Deterministic community reverse-index rebuild from local dataset snapshots.
• Music/MV metadata-first UX upgrades: MB IDs on cards, artwork, album/track navigation improvements.

Changed

• Homepage search now surfaces cached candidates immediately and continues normal adapter resolution in parallel.
• Candidate dedupe now merges provenance/metadata deterministically and removes cache/adapter duplicate rows.
• Community lookup remains hint-only and is injected before normal ladder execution; fallback behavior is unchanged if cache is missing/unavailable.
• Config defaults/schema expanded for community lookup/publish and local search-cache controls with backward-compatible defaulting.
• Generic/video scoring now includes a small logarithmic view_count tie-break bonus when metadata already contains view counts (no extra fetch calls).
• Navigation cleanup: page naming/hash alias behavior aligned around Advanced.

Fixed

• Search/control-flow safety fixes so cache failures/timeouts do not block request resolution.
• Restricted-content filtering improved for adapter normalization and cache replay.
• Telegram scheduler/watcher summaries hardened: cleaner headers, title-first item labels, duplicate dispatch reduction.
• Watcher stability improvements: batch-level messaging behavior, restart resilience, and non-blocking polling paths.
• Music UI regressions fixed across View Tracks, card actions, artwork loading/layout, and mode-specific interaction behavior.

v0.9.6 — Runtime Distribution + Music Match Robustness

High-Level

This release focuses on three themes: faster music retrieval/download throughput, safer/more deterministic matching, and better runtime visibility. It also adds Docker-first runtime packaging and tightens import/job execution behavior for large queues.

Added

• Runtime distribution: GHCR versioned images, release bundle zip assets, and README-runtime.md.
• Deterministic music benchmark gate with CI artifacts (results plus markdown delta report).
• Runtime album run_summary.json diagnostics (completion, unresolved classes, rejection mix, per-track detail).
• Import-only low-confidence quarantine flow to Music/Needs Review via music_track_review.

Changed

• Music matching/retrieval pipeline hardened and made faster without lowering gates:
  • deterministic multi-rung fallback and bounded duration expansion
  • per-rung source retrieval parallelized across youtube_music, youtube, soundcloud, bandcamp with deterministic merge
  • candidate pre-resolution overlaps with active downloads, with bounded lookahead (music_preresolve_lookahead, default 3, cap 4)
  • stronger in-process MB resolution cache reuse for repeated (recording_mbid, release_mbid) pairs
  • conservative default fragment concurrency for music downloads (yt_dlp_opts.concurrent_fragment_downloads=2, overrideable)
• Import/runtime throughput improvements:
  • bounded parallel MB binding (import_mb_binding_workers, default 4, cap 5)
  • import row dedupe before MB lookup for exact (artist/title/album) repeats, while preserving per-track enqueue/progress fan-out
  • worker poll interval reduced from 5s to 1s
  • bounded same-source job concurrency via per-source semaphores (default 2, cap 4; configurable with max_concurrent_jobs_per_source or source_concurrency)
• EP-aware handling expanded:
  • EP retrieval refinement rung for album runs
  • EP release groups included in album metadata search (primarytype:album OR ep)
  • EP releases accepted in album-run pair resolution and enrichment fallback
• Scoring/gating robustness improved:
  • featured-artist normalization (feat/ft/featuring) and album_artist aware artist/channel scoring
  • source-aware album gating for weak-metadata adapters (youtube_music, youtube, soundcloud)
  • clearer retrieval-vs-ranking separation with recall@k benchmark metrics (k={1,3,5,10})
• Runtime observability expanded:
  • decision-edge diagnostics, richer rejected-candidate metadata, injected-candidate rejection mix, EP refinement telemetry, variant tagging, benchmark motif rollups
  • lightweight runtime metrics for per-source active slots, queue age, resolve latency, and resolution-cache hit rate
• UI/status usability refresh:
  • full-width Operations Status and Download Queue
  • wider/scrollable queue table using user-facing title column
  • Clear Failed queue action
  • Metrics panel moved to Info
  • Home search now routes YouTube playlist URLs through playlist enqueue on Search & Download (instead of direct-URL mode), while Search shows a clear prompt to use download mode for playlist URLs

Fixed

• Reduced false-negative music rejects tied to featured-credit tokenization and missing album metadata.
• Corrected playlist/library import progress reporting (completed-work snapshots, no pre-item drift, finalization shown as active).
• Fixed MusicBrainz include-contract error in album metadata fetch (genres include misuse).
• Fixed MP4 post-processing regression where incompatible audio could persist.
• Fixed Home/header UI consistency regressions after layout/navigation changes.
• Fixed worker retry-loop regression causing duplicate downloads after successful writes (adapter store wiring and post-download crash path).

v0.9.5 — Music Mode Hardening + Playlist File Import

Added

• MusicBrainz-first Music Mode API surface:
  • GET /api/music/search (metadata-only discovery)
  • POST /api/music/enqueue (track enqueue from canonical MB payload)
  • POST /api/music/album/download (album enqueue by release group)
• Playlist file import flow with batch finalize support for M3U/M3U8, CSV, Apple Music XML/plist, and Soundiiz JSON.
• Music failure diagnostics persistence (music_failures) with status visibility.
• Regression test coverage expanded across MB binding/scoring, yt-dlp option contracts, import behavior, and Music Mode UI flow.

Changed

• Enforced strict MB-bound canonical metadata for music_track before enqueue/execution, with fail-fast behavior instead of degraded naming fallbacks.
• Hardened deterministic MB pair selection and bucket handling (album > compilation > single fallback), including stronger duration/variant rejection and stable tie-breaks.
• Consolidated download payload/option authority: unified enqueue payload building, explicit final_format (video) vs music_final_format (audio), and consistent audio_mode handling for music.
• Aligned direct URL and worker paths on canonical yt-dlp option/CLI building with controlled retry escalation and safer non-fatal metadata probing.
• Stabilized Music Mode UX into a metadata-first Home flow with toggle gating, stale-response protection, and a single authoritative track enqueue path.
• UI/UX fixes and updates across Home search, advanced options layout, status indicators, and delivery controls.
• Unified visual theme across Home/Info/Status/Config and renamed the Advanced Search nav label to Info for clearer navigation semantics.
• Client delivery was brought back on Home flows and now obeys the delivery toggle for both candidate and direct URL downloads.
• Playlist file import now runs as a background job (POST /api/import/playlist returns 202 + job_id) with progress polling via GET /api/import/playlist/jobs/{job_id} to avoid blocking the request path.
• Scheduler, watcher, and scheduled Spotify sync ticks now pause while playlist imports are active to reduce runtime contention and UX conflicts.
• Home import UX now enforces explicit confirmation, disables import controls while running, and displays a live progress modal with status counters and errors.
• Album-run canonicalization now enforces one release context across all queued tracks:
  • consistent album, album_artist, release_date, mb_release_id, mb_release_group_id, and artwork_url
  • consistent album-wide genre best-effort (MusicBrainz release/release-group first, resolved fallback only when available)
• Music library pathing now always keys artist folders from canonical album_artist (not per-track featured artist credits).
• Music path builder now creates Disc N folders only when disc_total > 1 (single-disc albums no longer force Disc 1).
• Album-run queue payloads now propagate track_total and disc_total for downstream tag correctness.
• Metadata worker now prefers album-run artwork_url for all tracks in an album run, with release-art fallback only when needed.
• Consolidated music path contract authority across both runtime workers:
  • shared relative music layout builder now drives both engine.job_queue and download.worker
  • single source of truth for Disc-folder inclusion rules
• Consolidated shared music contract helpers for integer parsing/track formatting and canonical metadata coercion to reduce drift between worker stacks.
• Consolidated music root resolution logic into shared path utilities used by metadata download worker flows.

Fixed

• MusicBrainz recording include contract errors (InvalidIncludeError) in binding fetch paths.
• Search destination regression caused by missing build_output_template import.
• Direct URL preview blank-card fallback by returning safe title/uploader/thumbnail values on extraction failure.
• Album enqueue hard-failure behavior: partial track failures now return a success summary instead of a full 500 response.
• Fixed Home UI state drift and delivery-mode edge cases for clearer, consistent behavior.
• Fixed album-mode metadata drift where featured-artist tracks could branch into separate artist folders.
• Fixed inconsistent album artwork across tracks in the same album run by enforcing run-level cover art preference.
• Fixed missing/partial track/disc total tag writes so players can reliably show Track X of Y and Disc A of B.
• Fixed lingering single-disc Disc 1 folder creation in the secondary download worker path by migrating it to the shared layout authority.

v0.9.4 — Filesystem Layout Stabilization

Changed

• Docker runtime now defaults to canonical root-level directories: /downloads, /data, /config, /logs, /tokens
• No RETREIVR_*_DIR overrides required in container deployments
• Unified database path resolution (removed legacy RETREIVR_DB_PATH fallbacks)

Migration Notes

• Legacy /app/data deployments must remap volumes
• Optional SQL path rewrite may be required if absolute paths were stored

[v0.9.3] – Canonical Authority & Scheduler Hardening

This release establishes Retreivr’s canonical authority model and locks in deterministic orchestration behavior. v0.9.3 is a stability milestone focused on correctness, idempotency, and clean archival output.

Highlights

• MusicBrainz is now the canonical metadata authority.
• Spotify downgraded to optional intent ingestion (OAuth + Premium required).
• Spotify API usage (playlists, saved tracks, metadata hints) now strictly requires OAuth configuration and an active Premium subscription.
• Deterministic playlist snapshot hashing and diffing.
• Idempotent scheduler ticks (no duplicate enqueues).
• MKV set as the default video container.
• Integration tests added for full pipeline and snapshot behavior.

---

Added

• Structured PlaylistRunSummary with:
  • added
  • skipped
  • completed
  • failed
• Stable playlist snapshot hashing using normalized item sets.
• Crash-safe restart behavior for scheduler runs.
• Active-job duplicate detection (queued / claimed / downloading / postprocessing states).
• Integration tests covering:
  • Full music flow (search → resolve → download → embed → persist)
  • Spotify intent conversion (MB-first enforcement)
  • Playlist reorder behavior (no re-enqueue)
  • Crash/restart idempotency
• MKV default container policy for video downloads.

---

Changed

• Canonical metadata resolution is now MusicBrainz-first in all ingestion paths.
• Spotify metadata is treated as hints only and never overrides MusicBrainz canonical results.
• Legacy resolver paths removed.
• Duplicate MusicBrainz client stacks consolidated into a single service layer.
• Canonical naming enforced:
  • No video IDs in filenames
  • No upload dates in filenames
  • Zero-padded music track numbers
• Video metadata embedding now occurs after final container merge, ensuring metadata survives remux.
• Scheduler diff logic hardened to ignore reorder-only changes.
• Snapshot persistence made deterministic to prevent unnecessary DB churn.

---

Fixed

• Prevented duplicate active-job enqueue on scheduler restart.
• Eliminated reorder-triggered playlist re-downloads.
• Fixed snapshot instability caused by unordered playlist items.
• Prevented metadata failures from corrupting or blocking completed downloads.

---

Notes

• This release prioritizes stability over new feature expansion.
• v0.9.3 marks the transition to a canonical, deterministic ingestion engine.
• MKV is now the default video container to preserve codec fidelity and improve metadata support.
• Spotify integration depends on the official Spotify Web API and requires valid OAuth credentials plus Premium account validation; without these, Spotify playlist sync and metadata ingestion remain disabled.

[v0.9.2] – Search Engine Dialed In // Home Page UI Update

Highlights

This release hardens the download pipeline (especially audio-only MP3), improves observability, and simplifies the Home UI ahead of broader feature work. Video downloads remain stable and unchanged.

⸻

🚀 Improvements • Reliable MP3 audio-only downloads • Audio mode now uses a robust bestaudio[acodec!=none]/bestaudio/best selector. • Prevents unnecessary video downloads when targeting MP3. • Matches known-working yt-dlp CLI behavior. • Works consistently for direct URLs and queued jobs. • Safer yt-dlp option handling • Avoids forced merge/remux unless explicitly required. • Reduces ffmpeg post-processing failures. • Audio and video paths are now clearly separated and predictable. • yt-dlp CLI observability • Job workers now log the exact yt-dlp CLI command executed (with secrets redacted). • Makes debugging format, cookie, and extractor issues significantly easier.

⸻

🧠 Behavior Fixes • Post-processing failures are now terminal • ffmpeg / post-processing errors correctly mark jobs as FAILED. • Prevents silent re-queue loops and misleading “Queued” states in the UI. • Video pipeline preserved • Default video behavior (bestvideo+bestaudio/best) remains unchanged. • MP4 / MKV / WebM downloads continue to work as before.

⸻

🎧 Music & Metadata • Music metadata enrichment remains optional • Failed or low-confidence enrichment no longer blocks successful downloads. • Clear logging when metadata is skipped due to confidence thresholds.

⸻

🖥 UI / UX • Home page cleanup • Reorganized source filters and advanced options into a single compact row. • Reduced visual noise without removing functionality. • Improved spacing and alignment for music mode, format, and destination controls. • Advanced Search remains available • Advanced functionality is still accessible via the dedicated Advanced Search page.

⸻

🧹 Internal / Maintenance • Improved internal option auditing logs. • Better separation between search, enqueue, and execution logic. • No schema or config migrations required.

⸻

⚠️ Known Notes • Client-side (“download to this device”) delivery is still being refined and may be disabled or hidden in some UI paths.

[v0.9.1] – Runtime Stability & Direct URL Fixes

This release focuses on restoring and hardening runtime stability after refactors since yt-archiver v1.2.0. Primary goals were correctness, predictability, and eliminating regressions in downloads, scheduling, and search flows.

Fixed:

Restored reliable Direct URL downloads for video and audio (mp3/m4a/etc). Corrected yt-dlp invocation for audio formats (uses extract-audio instead of merge-output-format). Fixed Direct URL runs appearing permanently queued in the Home UI. Prevented empty or zero-byte output files from being recorded as completed. Fixed scheduler playlist downloads producing incorrect formats or audio-only output. Ensured scheduler and direct downloads can run concurrently without interference. Fixed missing database schema initialization for search-related tables. Normalized all filesystem paths via paths.py and environment variables (Docker-safe). Fixed Advanced Search “Failed to load requests” error caused by search DB store calling service-only logic. Fixed Home screen results remaining stuck in “Queued” by restoring reliable search request status hydration. Unified search job database usage to a single canonical path to prevent schema and state mismatches. Changed:

Direct URL playlist links are now explicitly rejected with a clear user-facing error message. Direct URL runs bypass the job queue but still report progress and completion via run status. Search-only results can now be downloaded individually via the Home results UI. Default video downloads respect configured format preferences (e.g., webm/mp4). Metadata enrichment failures no longer block or corrupt completed downloads. Notes:

Playlist URLs must be added via Scheduler / Playlist configuration, not Direct URL mode. Kill-download button is not guaranteed during active runs and remains experimental. Watcher functionality is present but considered beta and may change in later releases.

[v0.9.0] – Retreivr Rebrand Release // Music Mode and Metadata

• Project renamed to Retreivr
• Repository migrated to new namespace
• Branding updated across documentation, UI, and Docker artifacts

Added:

• Music mode (opt-in per playlist and per single-URL run) with audio-focused metadata and music-safe naming.
• Smart Search feature - aggregating results from multiple top-tier sources and scoring quality and metadata acquisition, ranking results, and simplifying the entire media-searching process for users.
• yt-dlp cookies support (Netscape cookies.txt) for improved YouTube Music metadata.
• Music filename template support (artist/album/track hierarchy).
• Music metadata enrichment pipeline (MusicBrainz + optional AcoustID + artwork) with background tagging.
• UI controls for music mode, cookies, music template, and metadata enrichment options.
• Config UI controls for watcher enable, backoff timing, and downtime window.
• Per-playlist subscribe mode (only download new videos after first run).
• Single-playlist run controls in the Web UI.
• Single-URL delivery modes (server library or one-time client download via HTTP).
• Button to Kill downloads in progress (cancel active run from Status Section).
• Adaptive watcher with per-playlist state persisted in SQLite.
• Watch policy config with downtime windows and backoff timing.

Changed:

• Metadata flow now prefers yt-dlp music fields when music mode is enabled.
• Music metadata tagging can overwrite existing yt-dlp tags by default (configurable).
• Music URLs (music.youtube.com) auto-enable music mode for single URL runs.
• Music mode download URLs use music.youtube.com when enabled.
• Music mode respects video formats (does not force audio when final_format is a video).
• Download execution uses a native single-call path with explicit JS runtime/solver and a muxed-video requirement, with hardened fallback on failure.
• Watcher uses a single supervisor loop and deterministic scheduling.
• Downloads respect downtime windows and defer until downtime ends.
• Watcher batches detections with a quiet-window strategy and sends one Telegram summary per batch.
• Status now reports current phase and last error for active runs.

Summary

This v0.9.0 release marks the official rebrand of the project from YouTube-Archiver to Retreivr. The version number has been reset to reflect a new product identity and roadmap.

Important Notes

• v1.2.0 was the final release under the YouTube-Archiver name.
• Versioning resumes at v0.9.0 under the Retreivr name.
• Functionality is unchanged in this release.
• Future releases may introduce breaking changes as APIs, environment variables, and UI contracts are stabilized.

|vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv| |##################################| |//////////////////////////////////| |\\\\\\\\\\\\\\\\\| |##################################| |^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|

[v1.2.0] – Final YouTube-Archiver Release

Summary

Final release published under the YouTube-Archiver name before rebranding.

Changes

1.2.0 - OAuth Web UI Helper Added:

• Web UI OAuth helper per account (launches Google auth URL + paste code to save token).
• API endpoints to support OAuth in the Web UI flow.

Notes:

• Docker pulls remain available via GHCR:
• docker pull ghcr.io/sudoStacks/retreivr:latest
• image: ghcr.io/sudoStacks/retreivr:latest

1.1.2 - Publish Docker to GHCR Latest No changes from v1.1.1 - just creating new tag to automatically publish to GHCR repo to make docker pulls directly from there.

Docker Pull Command: docker pull ghcr.io/sudoStacks/retreivr:latest

Docker Compose Line: image: ghcr.io/sudoStacks/retreivr:latest

1.1.1 - Minor Patch Added:

• prompts to verify you wish to remove items on 'Remove' button press

Changed:

• hardened version control by clearing caches.
• better date/time format in Status block.
• clearer log entries when Google Oauth runs to verify playlists.

1.1.0 - Version Control and YT-DLP Update Maintenance Added:

• App version display and GitHub release check in Status.
• Manual yt-dlp update button (requires restart).

Changed:

• Dockerfile build arg for YT_ARCHIVER_VERSION.

1.0.1 - Frontend UI Updates Added:

• Multi-page Web UI (Home, Config, Downloads, History, Logs) with top navigation.
• Separate playlist progress vs per-video download progress indicators.
• Downloads + History filters with limits, and internal scrolling tables.
• Mobile navigation menu + collapsible filters for small screens.
• Telegram summary truncation to avoid oversized messages.
• Playlist name field in config editor (non-functional label).

Changed:

• Default Downloads/History limit to 50.
• Light-mode header styling and mobile spacing tweaks.

Fixed:

• History “Copy URL” now copies the YouTube URL, not API download URL.
• Config/playlist download paths normalized to remain relative to /downloads.

1.0.0 - First public release Added:

• Docker-first deployment with explicit volume paths.
• FastAPI backend serving API + static Web UI.
• Web UI for config, runs, status, logs, history, downloads, and cleanup.
• Built-in scheduler (no cron, no systemd).
• SQLite-backed history and state.
• Optional Telegram summaries and optional Basic auth.
• Home Assistant-friendly status and metrics endpoints via API.
• desktop GUI deprecated

Prior to 1.0.0

• no official release
• only python scripts released, no official package
• archiver.py ran independently
• a desktop GUI was created, paving way for the eventual webUI