Repository navigation
YTMDL v0.28.1
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_PROXYrouting 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/cookiesacross container recreations. - Reliable track timeouts: A track reaching
YTDM_TRACK_TIMEOUTis retried withinMUSICDL_MAX_ATTEMPTSasTRACK_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 updaterefusing 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_FORMATandTRANSFER_BUDGET_EXCEEDEDin 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.
-
Download
ytmdlctl-<os>-<arch>andSHA256SUMSfrom the
v0.28.1 release. -
Verify the downloaded binary's checksum with
sha256sum --ignore-missing -c SHA256SUMS
(on macOS,shasum -a 256 --ignore-missing -c SHA256SUMS). -
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 indocs/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