Skip to content

Releases

YTMDL v1.6.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 21:18
3570443

YTMDL v1.6.0

A download that finished while the library was unreachable is no longer downloaded again, stored track identities can be carried over to a new form, and the remaining views of the web interface follow the theme.

Highlights

  • A staged download is only moved when the library returns. A track that was downloaded while the library storage was unreachable (an offline network share, for example) used to be downloaded, tagged and verified once more when the library came back. The backend now keeps the finished file in staging with a record of what it learned (checksum, source, cover, lyrics lookup) and, once the library is writable again, verifies the file against its checksum and moves it: no provider request, no yt-dlp run, no retry attempt spent. This survives a restart. A staged file that is missing or changed is discarded with a warning in the log and downloaded the normal way.
  • Stored track identities can be migrated. Every track now records the scheme its identity key was built under. About 15 seconds after start, the backend carries keys written by 1.3.0 and earlier (the older reading of an unbracketed remix title) over to the current form, in the background, one track per transaction. A track whose new key another track already carries, or whose stored key no longer follows from its stored title and artists, is never merged or deleted: it keeps its old key, is still found as before, and is listed at GET /api/v1/library/identity-migration. To keep the stored keys, set MUSICDL_LIBRARY_IDENTITY_MIGRATION=false in .env.
  • The mobile navigation behaves like a dialog. Focus moves into the drawer when it opens and stays there, Escape closes it and returns focus to the button that opened it, and the page behind it is inert for assistive technology.

Changes

  • Downloads:
    • An item that waited for free space in the library was downloaded again on every dispatch tick until space was available; it now only re-checks the library.
    • Cancelling or failing a job removes the staging files of its waiting items at once instead of at the next start.
    • Items staged by an earlier version carry no record and are downloaded once more after the update, as before.
  • Matching: the older remix-title reading is only applied to tracks that have not been migrated. A title such as "Blinding Lights Major Lazer Remix" no longer matches a stored "Blinding (Remix)".
  • Web interface:
    • Downloads, Subscriptions, Settings and Playlists use the same loading placeholders, empty states and error states as the other views; an empty filtered list offers to reset its filters.
    • Settings: the "Beim Start festgelegt" block shows a loading state and an error with a retry instead of staying absent when the settings cannot be loaded.
    • Subscriptions: the search field, filters and row controls have accessible names; the table hides the provider, next-check and filter columns on narrow widths.
    • Playlists: the loading placeholder has the shape of the grid, dialog fields are labelled, and the space reserved for the player is no longer doubled.
    • Fixed colour values in the download cards, the update panel and the subscription import dialog are replaced by the theme's status colours.
    • The mobile drawer has its own close button and closes when the window grows past the mobile width.
  • Qualify v1.5.0 upgrades as well as v0.28.1, v1.0.0, v1.1.1, v1.2.0, v1.3.0, v1.4.0 and v1.4.1.

Upgrade from v1.5.0

Use the checksum-verified v1.6.0 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.6.0 --dry-run before
ytmdlctl update --channel stable --target 1.6.0. The update migrates the
database to schema 19; verify a database backup first. Protect the media
separately; the database dump does not contain music files.

Upgrade Notes

Existing installations can update using:

ytmdlctl update

Stored track identities can be migrated. Every track now records the scheme its identity key was built under.

About 15 seconds after start, the backend carries keys written by 1.3.0 and earlier (the older reading of an unbracketed remix title) over to the current form, in the background, one track per transaction.

A track whose new key another track already carries, or whose stored key no longer follows from its stored title and artists, is never merged or deleted: it keeps its old key, is still found as before, and is listed at GET /api/v1/library/identity-migration.

To keep the stored keys, set MUSICDL_LIBRARY_IDENTITY_MIGRATION=false in .env.

Full Changelog: v1.5.0...v1.6.0

YTMDL v1.5.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 09:55
a768f52

YTMDL v1.5.0

A new file naming scheme, with an automatic move of existing libraries to it, and a web interface with toasts, a command menu and a queue that can be dragged on touch screens.

Highlights

  • New file names. Characters a filesystem refuses no longer become - and _; they become their fullwidth look-alikes (/ \ : * ? " < > | become / \ : * ? " < > |). AC/DC is now the folder AC/DC and Who? is Who?. A multi-disc track is 2-02 - Title instead of 202 - Title (track 105 on disc 2 is 2-105 - Title); it is still one folder per release, and a single-disc release keeps 02 - Title. Edition notes stay in the name as before.
  • Existing libraries are moved automatically. About 15 seconds after the new backend starts, it moves an existing library to the new names in the background, once: tracks with their lyrics files, covers and anything else in the release folder. It never overwrites a file, resumes after a restart, and waits while the library storage is unreachable. Its state is at GET /api/v1/library/naming-migration and in the library's maintenance tab. To choose the moment yourself, set MUSICDL_LIBRARY_AUTO_RENAME=false in .env before updating.
  • What media servers will see. Plex, Jellyfin and Emby find files by path, so their next scan sees the old paths disappear and new ones appear: renamed files show up as new items and the old ones are removed. Albums and artists stay as they were, but depending on the server and its settings, play counts, ratings, playlists and "recently added" dates tied to the old paths may be lost or reset, and Navidrome, which also keys tracks by path, is affected too. On a mount without hard links (some SMB shares) each file is copied and verified against the original's SHA-256 instead, which takes long for a large library.
  • A web interface that answers back. Results and errors appear as toasts, a command menu opens with Ctrl+K or Cmd+K, and the queue can be reordered by dragging on touch screens as well as with the keyboard.

Changes

  • File names: a song in the trash keeps the path it had when it was deleted and is restored under its current name when the library has moved. Two tracks that share a name only under the new rules are told apart with the [source-…] suffix a download would use; tracks that carried it only because of the old substitution get their plain name back.
  • Library repair: the manual "move to canonical path" repair now carries the cover files along and keeps the loudness and fingerprint data of the track, which it used to drop.
  • Web interface:
    • Toasts report results that had no feedback (added to the queue, play next, added to a playlist), errors that were silent or far from the action, and playback errors with a retry action. Form validation stays at its field.
    • The command menu (Ctrl+K or Cmd+K, or the search button in the sidebar and the mobile header) offers the views, library and catalogue search, player actions, profile and sign-out. Typing "bib" and pressing Enter opens the library view before it runs a search.
    • The queue can be reordered by dragging from the grip with touch, mouse or pen, and with the keyboard (Space, arrow keys, Space or Escape); the up and down buttons stay.
    • Durations, times, counters and badges use a monospaced face with even digit widths.
    • The mini player, the queue and the player page are no longer redrawn on every progress tick while a track plays.
    • Every control that can be focused, not only buttons, shows a visible focus ring.
    • The library's maintenance tab has a card for the naming migration: its state, the counts, and every file left in place with the reason.
    • Small fixes: "1 Künstler" and "12 Künstler" instead of "Künstlers", "EP" instead of "Ep" in the release-type filter, and a console error on the dashboard and the "page not found" view is gone.
  • Qualify v1.4.1 upgrades as well as v0.28.1, v1.0.0, v1.1.1, v1.2.0, v1.3.0 and v1.4.0.

Upgrade from v1.4.1

Use the checksum-verified v1.5.0 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.5.0 --dry-run before
ytmdlctl update --channel stable --target 1.5.0. Protect the media separately;
the database dump does not contain music files, and the file renaming described
above changes the paths of the music files themselves.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v1.4.1...v1.5.0

YTMDL v1.4.1

Choose a tag to compare

@github-actions github-actions released this 17 Nov 08:22
d62dced

YTMDL v1.4.1

Signing in no longer fails right after the page opens, and live albums that the provider does not label as live are recognised.

Highlights

  • Signing in no longer fails with an error right after opening the page. A client that opened with several requests at once received a different security (CSRF) token in each response, and the last one to arrive replaced the others, so the sign-in request could be refused with HTTP 403 CSRF_INVALID. The web client now retries once with the current token, and the server no longer issues a new token for every request without a cookie: a signed-in session always receives the same token, and a signed-out client receives its token only from GET /api/v1/auth/status. Sessions that are already signed in stay signed in; a CSRF cookie issued before the update keeps working.
  • Live albums without "live" in the title are recognised. An album named after a venue or a tour used to share its tracks' identity with the studio recordings. An album whose own track titles carry a live marker for at least three tracks and three quarters of the list now counts as a live release, so its plainly titled tracks ("Intro", a medley, an unmarked song) are live recordings. Compilations, singles and EPs keep their type, and a deluxe edition with a live bonus disc stays an album. An album recognised this way is filtered like any other live release: the default release filter leaves it out.
  • The audio match takes the release into account. A plainly titled track of a live album now looks for a live source and no longer downloads the studio recording; a studio track no longer accepts a plainly titled upload of a live album. A live track without a live source fails to match.

Changes

  • For API clients and scripts: a signed-out client now receives its CSRF cookie only from GET /api/v1/auth/status; other endpoints no longer set one for a request without a cookie. Call the status endpoint first, as the web client and the Apple app already do. Signing in, setting up the server and approving a device sign-in rotate the cookie to the new session's token.
  • Release tooling: the Ubuntu runner image is pinned instead of following ubuntu-latest. Release images are pushed under a candidate tag and qualified, upgrades included, before they receive the version tag, so a failed qualification no longer uses up a version. A run that fails or is rehearsed deletes its own candidate images.
  • Qualify v1.4.0 upgrades as well as v0.28.1, v1.0.0, v1.1.1, v1.2.0 and v1.3.0.

Upgrade from v1.4.0

Use the checksum-verified v1.4.1 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.4.1 --dry-run before
ytmdlctl update --channel stable --target 1.4.1. Protect the media separately;
the database dump does not contain music files.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v1.4.0...v1.4.1

YTMDL v1.4.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 22:01
1c89b4e

YTMDL v1.4.0

A new look for the web interface, the fixes from a full code review, and a
correction to how live recordings are told apart from studio recordings.

Versions 1.3.1 and 1.3.2 were tagged but never released: both release runs
stopped in the upgrade qualification after the container images had been pushed,
and published image tags are never replaced. The 1.3.1 and 1.3.2 images on
GHCR belong to no release; use 1.4.0.

Highlights

  • A new theme for the web interface. The glass look with background glows, blur and heavy shadows is replaced by a flat one: surfaces tinted in the violet of the logo step up in lightness, fine borders separate them, and a wash of the two brand colours sits behind the top of the page. Corners are tighter, colours and motion come from one set of theme tokens, and text contrast was recalculated for every surface. With "reduce motion" enabled, movement is removed while fades and colour changes stay.
  • Studio recordings are no longer skipped because of a live album. A track that a live album lists under the plain song title used to share its identity with the studio recording, so whichever of the two reached the library second counted as already owned. Tracks of a live release are now live recordings. A studio recording that was skipped for this reason counts as missing again and is picked up by the next subscription sync or download.
  • Library repair cannot quarantine catalogued audio. A finding without a repair of its own (missing lyrics, a cover problem, an audio file that could not be probed) used to default to quarantine, which moved the registered file away and left its track unplayable. A registered file is now never quarantined, whatever the finding or the requested action.
  • Downloads no longer loop while the library is away. With offline staging enabled and the library unreachable, a finished track was downloaded again and again. It now waits until the library is back.

Changes

  • Reorganize requires an administrator. POST /library/reorganize moves files of the shared library and joins the other administrator-only library tools.
  • The bundled frontend sends X-Frame-Options: SAMEORIGIN, Content-Security-Policy: frame-ancestors 'self' and X-Content-Type-Options: nosniff. Embedding the web interface in a page of another origin stops working.
  • Sign-in attempts are counted before the password is checked, so parallel attempts cannot exceed the limit, and a successful sign-in no longer clears the failures counted for the whole address.
  • Deleting a track or release keeps its catalogue entry when the audio cannot be removed from disk and reports the failure. Lyrics sidecars and cover.png are removed with it, and releases of more than 500 tracks are deleted completely.
  • Retagging keeps embedded PNG covers: it looks for cover.png as well as cover.jpg and takes the image type from the file.
  • Restoring a track from the trash brings back its play counts and playback history. The restore check also covers a reused ISRC and a deleted release or artist.
  • "Retry failed" on a cancelled job puts the job back in the queue. A job paused before its tracks were resolved is resolved when it is resumed, also after a restart.
  • A media session is released when a download attempt ends between resolving and downloading, replacing a cookie file re-checks that the session is idle, and a cancelled wait gives its rate-limit token back.
  • A library file whose catalogue entry could not be written is removed again, so the next attempt does not store a second copy.
  • Discography deduplication keeps recordings with different ISRCs apart. An unbracketed remix title ("Song Tiesto Remix") only loses the word before "remix".
  • Path components are limited to 240 bytes, which keeps long titles in scripts with multi-byte characters within the filesystem limit. Moves fall back to an exclusive copy on mounts without hard links.
  • Artwork uploads of up to 8 MiB are accepted; the general request limit used to refuse them above 1 MiB. Loudness analysis is no longer cut off by the general request timeout. Internal errors are logged with their cause.
  • The Deezer client bounds response sizes, rejects unexpected statuses and does not follow pagination outside the API or in a loop.
  • ytmdlctl update enforces the release's minimum upgrade version like the dry run does, and stops the target backend before it decides whether an automatic rollback is safe. The artist merge of ytmdlctl no longer builds its SQL with a fixed quote delimiter.
  • Web player: playback stops and the queue is cleared when the signed-in user changes; job progress reconnects after the server closed the stream; signing in keeps the requested page, such as a device pairing link; starting a new queue under shuffle no longer brings the previous queue back.
  • Apple app: an unreadable stored session leads to a new sign-in instead of a failed connection; the Keychain entry is keyed by the normalized server address; device sign-in reports a failed session restore and slows down on a rate limit; a resume position survives an unknown track duration.
  • The sign-in and first-run forms use the accent button for their action. Errors are shown in orange-red, so they no longer look like the accent.
  • Release tooling: the upgrade qualification verifies that a test stack is really gone before the next one starts and can run without a release tag; both qualification scripts print why they stopped. Continuous integration runs only the jobs a change affects and checks the real browser flow on pull requests into main.
  • Qualify v1.3.0 upgrades as well as v0.28.1, v1.0.0, v1.1.1 and v1.2.0.

Upgrade from v1.3.0

Use the checksum-verified v1.4.0 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.4.0 --dry-run before
ytmdlctl update --channel stable --target 1.4.0. Protect the media separately;
the database dump does not contain music files.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v1.3.0...v1.4.0

YTMDL v1.3.0

Choose a tag to compare

@github-actions github-actions released this 08 Oct 20:23
71f2cab

YTMDL v1.3.0

Highlights

  • Device-code sign-in: A TV client such as the native Apple TV app requests a short code and receives its own account session after you approve it on a signed-in browser, iPhone, iPad or Mac (Profile & Security → Apple TV & Devices). Codes expire after five minutes, work once and are bounded in memory; no password is typed on the remote.
  • Usable web playlists: Playlists show cover collages and track artwork, with filtering, sorting, pagination and labeled track actions. Removing a playlist track asks for confirmation; the offline-copy controls stay available in a collapsed section.
  • Clearer download failures: Age gates, subscription requirements and unavailable recordings are no longer shown as the same generic "no audio source" error. Jobs that still contain failures can carry an optional checked release announcement with source and date.

Changes

  • Downloads recover when an already configured session can access a restricted recording: at most five eligible sessions are asked, once each. Bot, authentication and throttling responses stop immediately as before.
  • A verified recording that collides with a different file at the conventional library name gets a deterministic source suffix; both files are preserved.
  • Matching no longer credits a text hit with direct-source confidence. Known runtime differences above the 15-second verification allowance are rejected, downloaded audio is verified against the requested recording, and a requested performer is checked for fallback performances. Incompatible originals are preserved when a verified correction is published.
  • When corrected audio is kept beside an original, library and search rows, track details and playback use one compatible primary file. Playlists and favorites show one row per recording and artist counts no longer count physical copies. Nothing is deleted; originals stay reachable by file ID.
  • Cancelling an offline playlist copy stays effective until the new copy is published atomically; the previous complete copy is kept.
  • The bundled frontend now overwrites X-Forwarded-For with the connecting address instead of appending to it, so a client can no longer forge its address to avoid the login and device-sign-in limits.
  • Device sign-in admission is bounded: a refused start keeps the caller's quota, a full address table drops one entry instead of refusing new callers, and a poll no longer holds its lock during database calls.
  • Qualify v1.2.0 upgrades as well as v0.28.1, v1.0.0 and v1.1.1.

Upgrade from v1.2.0

Use the checksum-verified v1.3.0 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.3.0 --dry-run before
ytmdlctl update --channel stable --target 1.3.0. Protect the media separately;
the database dump does not contain music files.

If you run your own reverse proxy in front of the bundled frontend, the backend
now sees the proxy's address for every client, so per-address limits share one
key. See Tips.

Known Limits

  • Pending device codes live in the memory of one backend process. A restart invalidates them; several replicas would need shared storage or sticky routing. An older backend cannot complete device sign-in, so update the server before offering it to a TV client.
  • A device approved by an administrator receives administrator permissions too. Revoke it under Profile → Sessions.
  • A release announcement is an annotation with a source and a check date. It never schedules a retry and does not guarantee that the source becomes available.
  • The native Apple apps are not part of this release. They are a separate preview with their own apple-v… downloads and version numbers.
  • All limits of v1.2.0 still apply.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v1.2.0...v1.3.0

YTMDL v1.2.0

Choose a tag to compare

@github-actions github-actions released this 03 Oct 13:54
703ab07

YTMDL v1.2.0

Highlights

  • Seven-day duplicate trash: Removed alternative recordings retain audio, lyrics, metadata, favorites and playlist membership for restoration. Default confirmation and the explicit direct-removal setting remain available; permanent purge always requires a separate confirmation.
  • Local audio duplicate detection: Explicitly run bounded Chromaprint analysis to find similar recordings with different names. Compare and listen before choosing; no automatic deletion or provider requests.
  • Personal song radio: Preview a varied mix of up to 50 available local songs using your favorites, listening history, current song and optional artist genre. Play it or append without interrupting the current track.
  • Explicit device handoff: Save up to 500 queued tracks, the current position and repeat mode for 15 minutes. Take over with the same account on another device; local volume and sound settings stay local.
  • Browser-local offline playlists: Explicitly save a complete playlist copy with local covers, then play, seek and advance without server connectivity. Failed, oversized or canceled refreshes preserve the previous complete copy. Removing a copy affects only this browser.

Changes

  • Protect trash operations with a persistent journal, confined paths, non-overwriting same-filesystem moves and recoverable interruptions. Restore original identities and ordering around surviving neighbors without overwriting newer files or resurrecting deleted accounts/playlists.
  • Ship Chromaprint in both backend image architectures. Audio matching is generation-bound, duration-aware and conservative; ambiguous recordings remain eligible for ordinary playback/downloads and never affect provider health.
  • Prevent stale device handoffs and asynchronous offline sources from overriding newer queue selections. Pausing while a local source is loading remains paused.
  • Cache only the public application shell in the offline service worker; authenticated API replies and credentials are never cached. New application versions do not force a reload during playback.
  • Qualify current v1.1.1 upgrades as well as v0.28.1 and v1.0.0 with Docker, rootless Podman and both storage guard modes. Exercise offline copies, cancellation, atomic refresh, real audio and offline restart in Chromium and Firefox.

Upgrade from v1.1.1

Use the checksum-verified v1.2.0 CLI and Compose files from this release. Preserve
private configuration, proxy settings, mounts, cookies and the database volume.
Run ytmdlctl update --channel stable --target 1.2.0 --dry-run before
ytmdlctl update --channel stable --target 1.2.0. The fresh installer is only for
new installations. Protect the media separately; the database dump does not
contain music files. Full schema rollback requires restoring the verified backup.

Known Limits

  • The seven-day trash applies to alternative versions removed by the duplicate review. Other existing delete actions remain permanent. Previously deleted media cannot be recovered. Trash needs hardlink support on the same filesystem and must be excluded from external media-server scans. It is not a media backup.
  • Fingerprints inspect at most the first 90 seconds. Short or uniform audio can be inconclusive; versions sharing the same opening can differ later. Audio similarity is a listening aid and never proves an entire recording is identical. Analysis starts only on request; no background library-wide scan is scheduled.
  • Radio uses available local music and existing artist genre assignments. Handoff requires both devices to reach the server; it is explicit, expires after 15 minutes and does not monitor or remotely control devices.
  • Offline copies are limited to 200 songs, 64 MiB per audio file and 512 MiB per copy. They belong to this browser profile and server address, remain accessible after logout, and can be evicted by the browser. Server favorites, lyrics, radio, listening history and new loudness measurements are unavailable in the offline view.
  • A new offline start requires HTTPS (or localhost) and a prepared public shell. HTTP IP installations support offline playback only in an already opened app. Independent Safari/iOS qualification, multiday soak and a security audit are not claimed. Provider dependencies and opt-in combined-stream fallback remain as before.

Upgrade Notes

Existing installations can update using:

ytmdlctl update

Additive migrations 0016–0018 reach schema 18.

Upgrades from older supported schemas require a verified database backup; full schema rollback requires restoring that backup.

Media, configuration and cookies require separate protection.

Upgrade itself never removes songs.

Full Changelog: v1.1.1...v1.2.0

YTMDL v1.1.1

Choose a tag to compare

@github-actions github-actions released this 02 Oct 19:53
5b2ee53

YTMDL v1.1.1

Highlights

  • Complete player and library update: Responsive player layout, Escape, reliable crossfade, clearer errors, consistent button feedback, genres, local/custom artwork, smart playlists, listening history and optional loudness adjustment.
  • Swipe duplicate review: Cover-card comparisons with samples, keyboard controls, undo and a default confirmation dialog. Administrators can explicitly disable repeated confirmation per account/browser; direct mode removes losing versions only after the final choice.

Fixed

  • Lock confirmation, keep-all, skip, reload and view controls throughout the card transition as well as saving/deletion. A second action cannot race a pending choice or change its deletion mode. Preserve keyboard focus and ignore repeated choices until the next card is ready.
  • Replace the unpublished v1.1.0 stable candidate and withdrawn v1.1.0-rc.1; the source version, CLI, installation archive, frontend and documentation now consistently use v1.1.1.
  • Qualify upgrades from v0.28.1 and v1.0.0 with both container engines and guard modes, validating the schema against the release manifest. Stable notes compare the preceding published stable release.

Upgrade

Use the checksum-verified v1.1.1 CLI and Compose files. Preserve private
configuration, mounts, database volume, cookies and proxy settings. Run
ytmdlctl update --channel stable --target 1.1.1 --dry-run before
ytmdlctl update --channel stable --target 1.1.1. The fresh installer is only for
new installations. Replace local test-image pins with the official target first.

Known Limits

  • Duplicate matching uses normalized title and artist credit, not audio fingerprints. Intentional album/live/remix versions can be kept; groups over 100 versions cannot be bulk removed.
  • Deletion is permanent and affects every user's favorites and playlist references. Undo covers unfinished comparisons only. Filesystem/database changes cannot be atomic together; partial removals are reported accurately, and restoring deleted audio requires a separate media backup.
  • Loudness analysis and combined-stream fallback remain opt-in. Provider/network dependencies and the v1 platform boundary still apply; multiday soak and full Safari/iOS support are not claimed.

Upgrade Notes

Existing installations can update using:

ytmdlctl update

Migration from schema 12–14 to 15 is additive.

Verify a database backup and protect configuration, cookies and media separately.

Full schema rollback requires backup restoration; upgrading never automatically removes duplicate candidates.

Full Changelog: v1.0.0...v1.1.1

YTMDL v1.0.0

Choose a tag to compare

@github-actions github-actions released this 01 Oct 17:20
8145f19

YTMDL v1.0.0

Highlights

  • Official deployment package: Docker Compose and rootless Podman share a release-pinned installation bundle. Fresh installation creates private database credentials, writable service directories and a storage identity marker without changing existing data.
  • Container release contract: Backend and frontend images target Linux amd64 and arm64, with pinned base-image digests, OCI source/version labels and published software inventories. Qualification gates run before stable publication.
  • Consistent v1 version: CLI, backend, frontend package metadata, documentation and deployment defaults use 1.0.0. Database schema stays at 12.

Fixed

  • The update panel now shows the conditional v0.28.0 CLI bootstrap notice before host update commands.

  • Numbered release-note instructions render as separate steps, preserving wrapped text and code blocks.

  • Managed-update dry runs check target image resolution with host overrides, rejecting pinned hotfix or stale images before reporting readiness. The real update uses the same read-only check; private configuration and subprocess output are omitted from its diagnostics.

  • Verify release indexes, platform manifests and actual image identities across Docker classic, Docker containerd and Podman stores. A single retained local RepoDigest no longer incorrectly rejects a valid release.

  • Use the same storage guard environment aliases in status, dry runs and real updates. Conflicting identities are blocked without exposing their values.

  • Replace an unguarded live lyrics test with a local HTTP fixture so ordinary test runs do not depend on provider availability.

Upgrade from v0.28.1

Preserve .env, music/data mounts, cookies, database volumes and local overrides.
Use the checksum-verified v1 host CLI and the two v1 Compose files. First run
ytmdlctl update --target 1.0.0 --dry-run, then perform the update. The dry run
rejects image overrides pinned to an older release or private hotfix. Do not
remove storage checks to work around a bad mount. The fresh installer is only
for new installations; see INSTALL.md for exact commands.

For v0.28.0 with disabled Storage Identity Guard, use the v1 CLI directly:
the old CLI blocks before downloading its own fix. No database migration is
required.

Known Limits

  • Provider availability, credentials and network proxy requirements remain external dependencies. Restrictions and provider protection are not bypassed.
  • Combined-stream audio fallback is disabled by default; no multiday production soak or throughput comparison is claimed for this release.
  • NFS and full Safari/iOS playback are outside the qualified v1 support boundary.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v0.28.1...v1.0.0

YTMDL v0.28.1

Choose a tag to compare

@github-actions github-actions released this 01 Oct 00:34
72345cf

YTMDL v0.28.1

Highlights

  • Provider proxy access: HTTP clients now accept an explicitly configured private-network proxy. Origin-address validation, redirect protection and NO_PROXY routing remain enforced.
  • 25 MiB cookie uploads: Both media-session upload routes and the bundled Nginx proxy accept cookie files up to 25 MiB, with 26 MiB for multipart framing. Managed cookies persist under /data/cookies across container recreations.
  • Reliable track timeouts: A track reaching YTDM_TRACK_TIMEOUT is retried within MUSICDL_MAX_ATTEMPTS as TRACK_TIMEOUT. Explicit cancellation remains cancellation; shutdown leaves interrupted work for recovery. Cancelling a query no longer pauses the YouTube family.
  • Staging cleanup: Staging is removed after an item's final state is stored, including permanent failures. Startup pruning runs after recovery and preserves active, retryable, unknown and symlinked entries.

Changes

  • Fixed ytmdlctl update refusing updates when Storage Identity Guard is intentionally disabled. Missing, mismatched, unavailable or unverifiable storage still blocks updates.
  • Treat Music Premium and YouTube Premium item restrictions as candidate failures, preserving session health and allowing resolution to continue with another candidate.
  • Added an optional combined-stream audio fallback, disabled by default. It is considered only when no audio-only stream exists; preview markers, DRM, protected transports and unsupported codecs are rejected. Audio packets are copied without re-encoding and video never reaches the library.
  • Bound combined transfers by size (default 128 MiB) and process time (default 10 minutes, starting after the session slot is granted). Budget and format failures remain candidate scoped and never pause providers or media sessions.
  • Isolate each download attempt in its own staging directory. Only verified audio is published; stale files are never adopted as a successful result. Partial transfers are not resumed after an interrupted attempt or restart.
  • Report TRACK_TIMEOUT, UNSUPPORTED_MEDIA_FORMAT and TRANSFER_BUDGET_EXCEEDED in the frontend error-code types.
  • Correct deployment links and repository workflow documentation; exclude local environment overrides, dependencies and build outputs from container build contexts.
  • Preserve explicitly configured custom cookie directories. Database schema remains 12; no database migration is required.

Upgrade from v0.28.0

If Storage Identity Guard is disabled, use the v0.28.1 CLI for this update.
The old v0.28.0 ytmdlctl stops during preflight before it can download the fix.

  1. Download ytmdlctl-<os>-<arch> and SHA256SUMS from the
    v0.28.1 release.

  2. Verify the downloaded binary's checksum with sha256sum --ignore-missing -c SHA256SUMS
    (on macOS, shasum -a 256 --ignore-missing -c SHA256SUMS).

  3. Make it executable and use that binary directly, substituting your platform
    and installation directory:

    chmod +x ./ytmdlctl-<os>-<arch>
    ./ytmdlctl-<os>-<arch> --project-dir /path/to/ytmdl update --target 0.28.1 --dry-run
    ./ytmdlctl-<os>-<arch> --project-dir /path/to/ytmdl update --target 0.28.1

Installations with a configured and verified Storage Identity Guard can update
normally. Backup, manifest and image-digest checks still apply.

Known Limits

  • The combined-stream fallback remains disabled until an operator explicitly enables YTDM_COMBINED_AUDIO_FALLBACK. Its effect on real bandwidth, verified downloads and provider throttling has not been measured. The controlled comparison plan is documented in docs/diagnostics/combined-fallback-comparison.md.
  • Combined transfers occupy a session slot for their duration. Waiting for a slot still counts against the track's time limit.
  • Historical failed items are not automatically retried. Interrupted partial transfers start again.

Updates

For v0.28.0 installations with Storage Identity Guard disabled, first download the v0.28.1 ytmdlctl binary for your platform and verify it against SHA256SUMS. The old v0.28.0 CLI refuses this update during preflight. Follow Upgrade from v0.28.0 above, then use the verified v0.28.1 binary for update --target 0.28.1 --dry-run and update --target 0.28.1.

No database migration is required.

Full Changelog: v0.28.0...v0.28.1

YTMDL v0.28.0

Choose a tag to compare

@github-actions github-actions released this 20 Sep 18:08

YTMDL v0.28.0

Highlights

  • Update Channels: Administrators can choose between Stable (regular releases only, default for existing and new installations) and Development (explicitly published prereleases) in the update settings and web interface. ytmdlctl supports channel selection and SemVer 2.0.0 comparison with prerelease precedence.
  • Provider & Download Reliability: Reduced provider request volume through bounded metadata caching, candidate resolution deduplication, escalated YouTube rate-limit backoffs, and non-blocking DRM handling for SoundCloud items.
  • Audio Stream Classification: HLS audio renditions whose codec is reported as unknown are accepted and probed; combined audio/video streams are never filed as audio, while embedded cover art remains supported.
  • Age-Gate & Session Protection: YouTube age restrictions ("Sign in to confirm your age", "Verify your age") and unavailable videos are treated as candidate failures rather than session authorization failures. Healthy media sessions remain active without transitioning to AUTH_FAILED, while genuine auth failures and bot challenges preserve systemic protections.
  • Failed Job Error Visibility: Failure reasons from failed download items are propagated directly to parent jobs in the API and displayed in the Downloads UI (JobCard), replacing generic failure labels with actionable error details.
  • Discovered Release Deduplication: Equivalent provider catalog entries for the same release are deduplicated during artist scanning and discovery, preventing redundant download jobs that collide on canonical library storage paths.

Changes

  • Update System: PUT /api/v1/system/update/channel stores the preferred channel; update status reports channel, prerelease badges, and recommended ytmdlctl commands. An installed version newer than the channel offers is never downgraded.
  • ytmdlctl: check and update accept --channel stable|development and --target <version>. Manifest v3 is maintained for stable releases to preserve backward compatibility with installed CLI tooling.
  • Downloads & Diagnostics: The hourly throughput summary log line reports acquisitions, provider requests, reuse, rate limits, cooldown time, and failure reasons.
  • Web UI: Downloads view displays root item error messages on failed job cards with graceful fallback for historical jobs without parent error metadata.

Updates

Existing installations can update using:

ytmdlctl update

No database migration is required.

Full Changelog: v0.27.2-rc.2...v0.28.0