Advanced Topics: Download Formats Explained

MeTube provides a user-friendly way to select video and audio formats, but behind the scenes, it translates these selections into complex format strings that yt-dlp understands. This page details that translation process, as defined in app/dl_formats.py.

Core Logic

The function get_format(format: str, quality: str) is responsible for generating the final yt-dlp format string.

Video Formats (any, mp4)

When you select a video format, MeTube constructs a format string that prioritizes finding the best separate video and audio streams and merging them.

  • Base String: bestvideo[...] + bestaudio[...] / best[...]

  • This tells yt-dlp to first try finding the best video stream matching certain criteria (...) and the best audio stream, then merge them. If that fails, it falls back to the best pre-merged stream.

  • Quality/Resolution ([height<=...]): When a specific resolution like '1080p' is selected, a filter [height<=1080] is added to the bestvideo selector. This ensures yt-dlp doesn't pick a higher-resolution video stream.

  • Format Container ([ext=...]): If mp4 is chosen, [ext=mp4] is added to the video selector and [ext=m4a] to the audio selector to ensure the resulting file is in the MP4 container format.

Example: mp4 at 720p

  • Selection: Quality='720', Format='mp4'
  • Resulting String: bestvideo[height<=720][ext=mp4]+bestaudio[ext=m4a]/best[height<=720][ext=mp4]

Special Case: best_ios

iOS devices have strict requirements for video playback (H.264/H.265 video and AAC audio in an MP4 container). The 'Best (iOS)' option generates a highly specific format string to prioritize compatibility:

bestvideo[vcodec~='^((he|a)vc|h26[45])'][height<=...]+bestaudio[acodec=aac] / 
bestvideo[vcodec~='^((he|a)vc|h26[45])'][height<=...]+bestaudio[ext=m4a] / 
bestvideo[height<=...][ext=mp4]+bestaudio[ext=m4a] / 
best[height<=...][ext=mp4]
This string tries the following combinations in order:

  1. Best compatible video (h264/h265) + best compatible audio (aac).
  2. Best compatible video + best M4A audio (which can be easily converted).
  3. Best MP4 video + best M4A audio.
  4. Best pre-merged MP4 stream.

Audio Formats (mp3, m4a, opus, etc.)

When an audio-only format is selected, the process is different. MeTube instructs yt-dlp to download the best available audio and then use ffmpeg to convert it to the desired format and quality.

  • Download String: bestaudio[ext=...] / bestaudio / best This tells yt-dlp to download the best audio stream, preferring one already in the target extension to avoid conversion if possible.

  • Post-processing Options: The get_opts(...) function adds post-processor configurations to the yt-dlp options. For audio formats, this includes:

postprocessors.append({
    'key': 'FFmpegExtractAudio',
    'preferredcodec': 'mp3', // or 'm4a', 'flac', etc.
    'preferredquality': '192', // or '320', etc.
})

This ensures that after the download, ffmpeg is used to create the final audio file in the correct format and bitrate.

Thumbnail Downloads

When 'Thumbnail' is selected, MeTube tells yt-dlp to skip the actual media download and only fetch the thumbnail image.

  • Download String: bestaudio/best (a placeholder, as the download is skipped).
  • Options:
    • skip_download: True
    • writethumbnail: True
    • A post-processor (FFmpegThumbnailsConvertor) is added to ensure the thumbnail is saved as a JPG.