ytdl-org/youtube-dl · error · EmbedThumbnailPPError

stderr.decode('utf-8', 'replace').strip() (dynamic AtomicPar

Error message

stderr.decode('utf-8', 'replace').strip() (dynamic AtomicParsley stderr)

What it means

Raised by EmbedThumbnailPP when AtomicParsley ran but returned a non-zero exit code. The raised message is the tool's stderr (decoded, stripped), so the actual text comes from AtomicParsley itself — commonly unsupported file variants, corrupt input, or known AtomicParsley bugs (e.g. the 2020 'This file contains no cover art path' style failures).

Source

Thrown at youtube_dl/postprocessor/embedthumbnail.py:119

            cmd = [encodeFilename(atomicparsley, True),
                   encodeFilename(filename, True),
                   encodeArgument('--artwork'),
                   encodeFilename(thumbnail_filename, True),
                   encodeArgument('-o'),
                   encodeFilename(temp_filename, True)]

            self._downloader.to_screen('[atomicparsley] Adding thumbnail to "%s"' % filename)

            if self._downloader.params.get('verbose', False):
                self._downloader.to_screen('[debug] AtomicParsley command line: %s' % shell_quote(cmd))

            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

Read the embedded stderr message — it names the exact AtomicParsley failure
Install a fixed AtomicParsley build (e.g. wez/atomicparsley or the mpeg4base patches) instead of the ancient 0.9.0 packages
Re-download the file (truncated input makes AtomicParsley fail) and retry
Or use yt-dlp, which uses ffmpeg to embed mp4/m4a thumbnails and avoids AtomicParsley entirely

Example fix

# before (buggy distro AtomicParsley)
apt install atomicparsley && youtube-dl --embed-thumbnail URL
# after (modern fork)
pip install yt-dlp   # yt-dlp embeds mp4 thumbnails via ffmpeg
yt-dlp --embed-thumbnail URL

Defensive patterns

Strategy: fallback

Validate before calling

import subprocess, shutil

def atomicparsley_healthy():
    exe = shutil.which('AtomicParsley') or shutil.which('atomicparsley')
    if not exe:
        return False
    return subprocess.call([exe, '-v'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) == 0

Try / catch

try:
    ydl.download([url])
except PostProcessingError as e:
    # e.msg is AtomicParsley's stderr — surface it, and keep the downloaded file
    log.warning('Thumbnail embed failed (AtomicParsley): %s', e.msg)

Prevention

Use a maintained AtomicParsley fork; the 0.9.0 distro builds are crash-prone
Note that the media file is already downloaded when this fires — only the embed step failed
Keep AtomicParsley stderr in job logs; it identifies corrupt vs bug cases

When it happens

Trigger: --embed-thumbnail on m4a/mp4 where AtomicParsley fails mid-run: damaged download, unusual container flags, or the widely-shipped buggy AtomicParsley 0.9.0 ('Error:.*?) builds from Homebrew/debian that crash on certain files.

Common situations: The old Homebrew/Debian AtomicParsley builds have a malloc bug that crashes on many m4a files; interrupted downloads producing truncated mp4s; DRM-adjacent or non-standard containers from some sites.

Related errors

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