Skip to content

Download Automation & Queue ​

YTMDL Downloads und Warteschlange — v0.27-Entwicklungssnapshot

The YTMDL download engine coordinates background worker pools to process individual tracks, complete albums, and full discographies without starving shorter jobs.

Fair Queue Scheduling ​

  • Fair Division: Jobs with hundreds of tracks are processed in balanced round-robin chunks, ensuring a single massive discography cannot monopolize the queue.
  • Opus Stream Extraction: yt-dlp extracts native Opus streams (audio/opus inside WebM containers) and remuxes them stream-copy into .opus (Ogg) containers without generational audio transcoding.
  • Verification: Every downloaded file is probed via ffprobe to verify audio stream validity, channels, and sample rates before promotion to the library.
  • Retry & Circuit Breaker: Transient network or rate-limiting errors trigger exponential backoff.

Job Priorities ​

Every job carries a priority that decides its order relative to other jobs. Manual requests are placed ahead of background automation by default.

PriorityLabel (UI)Assigned to
lowNiedrigArtist subscription synchronization and background discovery jobs
normalNormalGeneral default
highHochManually requested downloads (artist, release, or track)
very_highSehr hochReserved for expedited items
  • Change a priority: open a job on the Downloads page and pick a new value from the Priorität selector, or PATCH /api/v1/jobs/{id} with {"priority": "..."}.
  • Raising a subscription job to high lets it compete with manual downloads; lowering a manual job to low parks it behind everything else.

Pausing the Queue ​

Global pause (storage maintenance) ​

Administrators can stop all queue processing from Settings → Storage (Warteschlange anhalten / fortsetzen), or via POST /api/v1/storage/queue/pause and .../resume. While paused the panel shows Download-Warteschlange: Pausiert. In-flight items finish their current step and no new work starts. YTMDL also pauses the queue on its own when the Storage Identity Guard fails or the library runs low on space.

Per-job pause ​

Individual jobs can be paused and resumed without affecting the rest of the queue (POST /api/v1/jobs/{id}/pause and .../resume). Paused jobs are listed under the Pausiert tab on the Downloads page. A paused job keeps its place and priority; deduplication still treats its items as pending so a subscription run will not create a duplicate job for the same release.

Understanding Status Labels ​

Job and item badges use plain-language German labels. The most common ones:

Internal statusJob labelMeaning
queuedIn WarteschlangeAccepted, waiting for a worker
resolving_artist / resolving_releases / resolving_tracksKünstler/Releases/Tracks werden aufgelöstBuilding the track list from metadata providers
matchingQuellen werden gesuchtSelecting an audio candidate for each track
downloadingWird heruntergeladenyt-dlp is fetching audio
taggingTags werden geschriebenWriting Vorbis comments and cover art
finalizingWird finalisiertAtomic promote from staging into /music
retry_waitWartet auf WiederholungTransient error; will retry after backoff
retry_wait + SESSION_UNAVAILABLEWartet auf ProviderDeferred by a temporary provider or session cooldown — not a failure and no retry budget is spent
waiting_for_storageWartet auf SpeicherLibrary mount is offline; staged audio is safe
waiting_for_spaceWartet auf SpeicherplatzFree space below the configured reserve
completedAbgeschlossenFinished — individual track failures do not fail the whole job
failedFehlgeschlagenThe job itself could not proceed
cancelledAbgebrochenCancelled by a user — never retried

A track that does not finish within YTDM_TRACK_TIMEOUT goes to Wartet auf Wiederholung with the error code TRACK_TIMEOUT and is retried like any other transient error, within the item's attempt limit (MUSICDL_MAX_ATTEMPTS); on its last attempt it fails. The time limit is local: it never pauses a provider or marks a media session. Only an explicit cancellation ends a track as Abgebrochen. Stopping or restarting the service is neither: interrupted tracks are picked up again after the restart.

NOTE

A job that finishes with some failed tracks remains completed, and appears in Fertig, with the badge Abgeschlossen mit Problemen. Click the amber track count to inspect only its failed tracks. Opening these details never starts a retry. Use Fehlgeschlagene wiederholen or a single item's retry action to explicitly re-attempt those tracks.

The Downloads page tab badges (Aktiv, In Warteschlange, Pausiert, Abgeschlossen, Fehlgeschlagen) reflect global database totals, not just the jobs visible on the current page.

The selected status group and priority are applied on the server before pagination, so older failures remain discoverable. Paused is an overlay on non-terminal jobs; it overlaps the active and queued groups. Direct links to a job load that job independently of its position in the list.

Understanding Errors ​

Search errors and download problems explain the known cause and a next step in German. Unknown causes remain unknown: a provider connectivity failure does not imply expired cookies. Raw provider output is not shown in these notices. Technische Details reveals the error code and, for API failures when available, the request ID for support.

Automatic continuation is shown for a download scheduled for retry, with its continuation time when available. Failed search requests do not promise an automatic repeat. Provider/session cooldown notices offer no immediate retry button; new cookies do not lift an active protective pause.

Ursachen bei nicht verfügbaren Aufnahmen ​

Die Downloadansicht unterscheidet MEDIA_AGE_RESTRICTED (fehlende Altersfreigabe), MEDIA_PREMIUM_REQUIRED (Premium-Anforderung) und MEDIA_UNAVAILABLE (Aufnahme zum Prüfzeitpunkt nicht verfügbar). Diese Fehler betreffen einzelne Quellen. Sie lösen keine Provider-Pause aus und werden nicht unverändert automatisch wiederholt. Ein manueller Versuch bleibt möglich, wenn sich der Zugang oder die Verfügbarkeit geändert hat.

Nur wenn die fehlgeschlagenen Kandidaten dieselbe Ursache melden, übernimmt der Auftrag diesen spezifischen Fehlercode. Gemischte oder unbekannte Ursachen bleiben TRACK_NOT_FOUND; Format- und Schutzfehler behalten ihre bisherige Priorität. Die Oberfläche interpretiert keine rohen Provider-Meldungen.

Optional kann eine geprüfte Veröffentlichung als options.release_announcement mit date (YYYY-MM-DD), source und checked_at (ISO-Zeitstempel) hinterlegt werden. Der Hinweis erscheint bei noch vorhandenen Fehlern mit Quelle und Prüfdatum. Ein angekündigter Termin beweist nicht, dass alle Aufnahmen erst dann verfügbar werden. Nach dem Termin fordert die Ansicht eine erneute Prüfung an; allein der Hinweis plant keinen Neustart. Es ist keine Datenbankmigration nötig.

Released under the Apache 2.0 License.