Skip to content

Features

Jump to bottom
Salem874 edited this page Mar 30, 2026 · 5 revisions

Features Guide

Comprehensive guide to MeedyaDL's features. For troubleshooting, see Troubleshooting.

Companion Downloads

MeedyaDL can automatically download additional format versions alongside your primary audio download. This is configured in Settings > Quality > Companion Downloads.

Audio Codec Companions

Six companion modes are available:

Mode Behaviour
Disabled No companions. Only the primary format is downloaded.
Atmos → Lossless (default) When downloading Dolby Atmos, also downloads ALAC (lossless).
Atmos → Lossless + Lossy Atmos → ALAC + AAC; ALAC → AAC. Maximum compatibility.
Specialist → Lossy Atmos or ALAC → AAC companion for universal playback.
Atmos → All Formats Atmos → AC3 (Dolby Digital) + ALAC + AAC. 4 files per track.
Custom Pick exactly which codecs to download via multi-select checkboxes.

File naming: Specialist formats get a suffix (e.g., [Dolby Atmos], [Lossless], [Dolby Digital]). The most universally compatible companion uses a clean filename.

Progress tracking: Companion downloads stream their output in real time to the Activity Log and progress bar. The queue-level bar advances after the primary download completes (partial credit), while the per-item bar shows companion speed/ETA. Processing labels show the current activity (e.g., "Companion: ALAC 14/28").

Music Video Companions

When enabled, MeedyaDL automatically downloads the music video for each track (if one exists on Apple Music) alongside the audio files.

Requirements:

  • MusicKit credentials must be configured in Settings > Cover Art > Animated Artwork (Team ID, Key ID, private key)
  • Enable the toggle in Settings > Quality > Video Quality > Music Video Companions

How it works:

  1. After audio download completes, the app queries the Apple Music API for each track's music video relationship
  2. Tracks with music videos get a companion GAMDL download using your video quality settings
  3. Duplicate music videos (same video linked from multiple tracks) are automatically deduplicated
  4. Results are logged in the Activity Log

Progress visibility: Companion downloads stream their progress in real time — the global progress bar shows speed, ETA, and percentage during companion downloads. The queue item stays in "Processing" state until all companions and enrichment finish. Desktop notifications are deferred until all background work is complete.

Quality & Fallback Chain

Audio Fallback

When the preferred audio codec is unavailable, MeedyaDL automatically tries the next codec in the fallback chain:

ALAC → Atmos → AC3 → AAC Binaural → AAC → AAC Legacy

For GAMDL >= 2.9.1, the native --song-codec-priority flag passes the entire chain in one process. If that fails, MeedyaDL retries each codec individually as a safety net.

Video Quality

Configure in Settings > Quality > Video Quality:

  • Resolution: 2160p (4K) → 240p, with automatic fallback to the next lower resolution
  • Codec Priority: H.265 (HEVC) and H.264 (AVC), reorderable
  • Remux Format: M4V, MP4, or MKV container

Artist Auto-Select

When downloading from an artist URL, select which content types to include via multi-select checkboxes in Settings > Quality:

  • Main Albums, Compilation Albums, Live Albums, Singles & EPs, All Albums, Top Songs, Music Videos

MeedyaDL creates a separate queue item for each selected content type.

Template Builder

The Settings > Templates tab uses a visual chip/pill builder for creating file and folder naming templates. Instead of typing GAMDL format strings manually, you can:

  • Click + to add variables (Artist, Album, Track #, etc.) or separators (/, -, space)
  • Click × on any chip to remove it
  • Toggle "Edit Raw" for direct text editing (power users)
  • See a live preview with sample metadata below the template

Available template variables: {artist}, {album_artist}, {album}, {title}, {track:02d}, {disc}, {year}, {genre}, {playlist_artist}, {playlist_title}.

Enhanced Lyrics (Word-by-Word Sync)

When Enhanced LRC is enabled (default: on), MeedyaDL converts Apple Music's TTML lyrics to Enhanced LRC format with word-level synchronized timestamps.

How it works:

  1. GAMDL downloads TTML lyrics (forced as primary format when enhanced LRC is enabled)
  2. MeedyaDL parses the TTML XML, extracting <span> word timestamps
  3. Generates Enhanced LRC with inline <mm:ss.xx> word timing
  4. Saves as .lrc sidecar file AND embeds in the M4A/M4V metadata

Songs without word-level timing gracefully fall back to standard line-level LRC.

Companion formats: When Enhanced LRC is enabled, you can still select LRC and SRT as companion formats. TTML is locked as primary, but companions download alongside for maximum compatibility.

Lyrics Format Fallback

When the Lyrics Format Fallback toggle is enabled (default: on), MeedyaDL automatically retries with alternative formats if the primary lyrics format doesn't produce sidecar files for all tracks:

  • Audio (.m4a): TTML → LRC → SRT
  • Video (.m4v/.mp4): TTML → SRT → LRC

Each fallback uses --synced-lyrics-only to avoid re-downloading media.

Subtitle Formats

MeedyaDL can generate multiple subtitle/caption formats from the TTML source downloaded from Apple Music. Configure in Settings > Lyrics.

Format Source Styling Setting Default
Enhanced LRC TTML Word-by-word sync timestamps enhanced_lrc On
WebVTT (.vtt) TTML/SRT/LRC Plain text generate_webvtt Off
Rich SRT (.srt) TTML/WebVTT Bold, italic, underline, colours generate_rich_srt On
ASS (.ass) TTML/WebVTT Full styling + positioning + colours (BGR) generate_ass Off
Subtitle embedding SRT/WebVTT Freeform atoms in MP4 container embed_subtitles Off

Rich SRT and ASS both support dual-source priority: TTML first (richest), then WebVTT. This enables future services (YouTube, BBC iPlayer) that provide WebVTT to produce styled output.

MusicBrainz Video Discovery

When enabled (Settings > Quality), MeedyaDL uses the MusicBrainz database to discover music videos as a fallback when the Apple Music API returns no results. No credentials required.

3-tier priority chain:

  1. Apple Music URL search in MusicBrainz external links (highest fidelity)
  2. ISRC code search (standard recording identifier)
  3. AcoustID recording ID direct lookup (from fingerprinting)

Also discovers cross-platform URLs (YouTube, Spotify, Deezer, Tidal, SoundCloud, Bandcamp) for future multi-service support.

Metadata Enrichment

After each download, a 12-stage enrichment pipeline runs automatically:

  1. Codec & source tags + Apple Music API metadata (always-on) — 30+ freeform atoms per file including ISRC, UPC, genre, advisory, artist IDs, record label, copyright, release dates, Apple Digital Master, composer, editorial notes, duration, and more. Written in dual namespaces (com.apple.iTunes + MeedyaMeta) with industry-standard names (LABEL, COPYRIGHT, COMPILATION, TOTALTRACKS). Tag definitions driven by tags.toml — adding new tags requires only editing the TOML file.
  2. Enhanced LRC — TTML to word-by-word LRC conversion (opt-in, default on) 2b. Lyrics format fallback — retries with LRC/SRT if TTML didn't cover all tracks (opt-in, default on) 2c. WebVTT generation — converts TTML/SRT/LRC to .vtt (opt-in) 2d. Rich SRT generation — TTML/WebVTT to styled SRT (opt-in, default on) 2e. Subtitle embedding — embeds SRT/WebVTT in MP4 containers (opt-in) 2f. ASS generation — TTML/WebVTT to styled ASS with colours and positioning (opt-in)
  3. Animated artwork — Motion cover art download via MusicKit API (opt-in)
  4. AcoustID fingerprinting — Audio fingerprint + MusicBrainz recording ID extraction (opt-in)
  5. ReplayGain analysis — EBU R128 loudness analysis via FFmpeg (opt-in)
  6. Music video companions — Apple Music API music video lookup and download (opt-in, requires MusicKit) 6b. MusicBrainz video discovery — 3-tier fallback when Apple Music API has no results (opt-in)

All enrichment steps use spawn_blocking for file I/O and yield_now between steps to prevent UI freezes on slow filesystems (FUSE mounts, cloud storage).

Queue Management

Persistence

The download queue is saved to queue.json after every change. On restart:

  • Active/queued items are restored and resumed
  • Failed items are restored in Error state (not auto-retried) for manual review
  • Completed/cancelled items are cleared

Export & Import

  • Export: File > Export Queue saves to a .meedyadl file via native save dialog
  • Import: File > Import Queue loads from a .meedyadl file, re-enqueues with local settings

Pre-Download Checks

Before each download, two checks run:

  1. Internet connectivity — HTTP GET to apple.com. If offline, item is queued but auto-start is skipped
  2. Cookie validation — Checks if cookies are valid/present. Blocks download if expired (skipped for wrapper users)

Crash Reporting

Local Reports

  • Rust panics → JSON crash reports in {app_data_dir}/crashes/
  • Frontend errors → Persisted via log_frontend_error IPC command
  • Download errors → Terminal failures saved as error reports (network errors excluded)
  • Reports older than 30 days auto-cleaned on startup

Logging

  • Dual output: stderr + daily-rotating log file in {app_data_dir}/logs/
  • Uses tracing ecosystem with log compatibility

Reporting to GitHub

Settings > Advanced > Error Reporting lets you submit error reports to GitHub Issues with a pre-filled issue form (privacy preview before submission).

Sentry (Optional)

Opt-in telemetry via Settings > Advanced > Sentry toggle (default: off).

MeedyaDL Wiki

Resources

Clone this wiki locally