ytdl-org/youtube-dl · error · EmbedThumbnailPPError

Only mp3 and m4a/mp4 are supported for thumbnail embedding f

Error message

Only mp3 and m4a/mp4 are supported for thumbnail embedding for now.

What it means

Raised by EmbedThumbnailPP.run when info['ext'] is neither mp3 nor m4a/mp4 (and not the earlier ffmpeg/atomicparsley branches). Thumbnail embedding is only implemented for those containers in this post-processor, so any other extension (mkv, webm, 3gp, m4v variants, etc.) is rejected explicitly.

Source

Thrown at youtube_dl/postprocessor/embedthumbnail.py:131

            p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
            stdout, stderr = process_communicate_or_kill(p)

            if p.returncode != 0:
                msg = stderr.decode('utf-8', 'replace').strip()
                raise EmbedThumbnailPPError(msg)

            if not self._already_have_thumbnail:
                os.remove(encodeFilename(thumbnail_filename))
            # for formats that don't support thumbnails (like 3gp) AtomicParsley
            # won't create to the temporary file
            if b'No changes' in stdout:
                self._downloader.report_warning('The file format doesn\'t support embedding a thumbnail')
            else:
                os.remove(encodeFilename(filename))
                os.rename(encodeFilename(temp_filename), encodeFilename(filename))
        else:
            raise EmbedThumbnailPPError('Only mp3 and m4a/mp4 are supported for thumbnail embedding for now.')

        return [], info

View on GitHub (pinned to 956b8c5855)

Solutions

Pick an mp4/m4a format: '-f bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]' before --embed-thumbnail
For audio, prefer mp3/m4a output (-x --audio-format mp3 or m4a)
If you need thumbnails in mkv/webm, switch to yt-dlp (uses ffmpeg, supports more containers) or embed with mkvpropedit afterwards

Example fix

# before
youtube-dl --embed-thumbnail -f best 'https://youtube.com/watch?v=...'
# after
youtube-dl --embed-thumbnail -f 'best[ext=mp4]' 'https://youtube.com/watch?v=...'

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED = {'mp3', 'm4a', 'mp4'}

def plan_supports_embed_thumbnail(requested_ext):
    return requested_ext in SUPPORTED

if opts.get('embedthumbnail') and fmt_ext not in SUPPORTED:
    raise ValueError('embed-thumbnail needs mp3/m4a/mp4; got %s' % fmt_ext)

Try / catch

try:
    ydl.download([url])
except PostProcessingError as e:
    if 'Only mp3 and m4a/mp4 are supported' in str(e):
        # re-run selecting an mp4/m4a format
        ydl.params['format'] = 'best[ext=mp4]/bestaudio[ext=m4a]'
        ydl.download([url])

Prevention

Pair --embed-thumbnail with an explicit mp4/m4a/mp3 format selection
Avoid combining --embed-thumbnail with --recode-video to non-MP4 containers in this fork

When it happens

Trigger: Using --embed-thumbnail while forcing a format/container other than mp3/m4a/mp4, e.g. '-f best[ext=webm]' or re-muxing with --recode-video to mkv before embedding, or downloading a site whose only formats are webm/3gp.

Common situations: Default best format resolves to webm on YouTube; users combine --embed-thumbnail with --recode-video mkv; sites serving 3gp-only streams.

Related errors

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/649bdcf19cd0431c. Report an issue: GitHub.