What causes "audio conversion failed: " in ytdl-org/youtube-dl?

Read the ffmpeg error appended after the colon — it names the exact problem

ytdl-org/youtube-dl · error · PostProcessingError

audio conversion failed:

Error message

audio conversion failed:

What it means

Raised by FFmpegExtractAudioPP.run when run_ffmpeg fails with AudioConversionError: the ffmpeg invocation itself errored (FFmpegPostProcessorError was caught in run_ffmpeg and re-wrapped). The suffix e.msg carries the underlying ffmpeg output, so 'audio conversion failed: <ffmpeg error>' tells you what ffmpeg rejected.

Source

Thrown at youtube_dl/postprocessor/ffmpeg.py:334

                more_opts += ['-f', 'wav']

        prefix, sep, ext = path.rpartition('.')  # not os.path.splitext, since the latter does not work on unicode in all setups
        new_path = prefix + sep + extension

        information['filepath'] = new_path
        information['ext'] = extension

        # If we download foo.mp3 and convert it to... foo.mp3, then don't delete foo.mp3, silly.
        if (new_path == path
                or (self._nopostoverwrites and os.path.exists(encodeFilename(new_path)))):
            self._downloader.to_screen('[ffmpeg] Post-process file %s exists, skipping' % new_path)
            return [], information

        try:
            self._downloader.to_screen('[ffmpeg] Destination: ' + new_path)
            self.run_ffmpeg(path, new_path, acodec, more_opts)
        except AudioConversionError as e:
            raise PostProcessingError(
                'audio conversion failed: ' + e.msg)
        except Exception:
            raise PostProcessingError('error running ' + self.basename)

        # Try to update the date time for extracted audio file.
        if information.get('filetime') is not None:
            self.try_utime(
                new_path, time.time(), information['filetime'],
                errnote='Cannot update utime of audio file')

        return [path], information


class FFmpegVideoConvertorPP(FFmpegPostProcessor):
    def __init__(self, downloader=None, preferedformat=None):
        super(FFmpegVideoConvertorPP, self).__init__(downloader)
        self._preferedformat = preferedformat

View on GitHub (pinned to 956b8c5855)

Solutions

Read the ffmpeg error appended after the colon — it names the exact problem
Install a full-featured ffmpeg build (with libmp3lame for --audio-format mp3)
Update ffmpeg to >= 1.0 as check_version warns
Verify the output directory is writable and the input file is not truncated

Example fix

# before (ffmpeg without libmp3lame)
youtube-dl -x --audio-format mp3 URL
# after (full build)
sudo apt-get install ffmpeg   # Debian: enables libmp3lame
youtube-dl -x --audio-format mp3 URL

Defensive patterns

Strategy: try-catch

Validate before calling

import subprocess

def ffmpeg_has_encoder(codec):
    out = subprocess.run(['ffmpeg', '-hide_banner', '-encoders'], capture_output=True).stdout.decode()
    return codec in out

if target == 'mp3' and not ffmpeg_has_encoder('libmp3lame'):
    target = 'm4a'  # pick a codec this build supports

Try / catch

try:
    ydl.download([url])
except PostProcessingError as e:
    if str(e).startswith('audio conversion failed:'):
        # e.msg tail contains ffmpeg's own error; usually a missing encoder
        log.error('ffmpeg said: %s — install full ffmpeg build', str(e).split(':', 1)[1])

Prevention

Use a full ffmpeg build (libmp3lame etc.) in environments that convert audio
Update ffmpeg to at least 1.0; heed the version warning youtube-dl prints
Parse the ffmpeg suffix after 'audio conversion failed:' — it names the real cause

When it happens

Trigger: -x/--audio-format conversion where ffmpeg exits non-zero: target codec not available in the ffmpeg build (e.g. no libmp3lame), corrupt input file, unreadable output path, or an outdated ffmpeg (<1.0) that does not understand the options used.

Common situations: Distros shipping ffmpeg without libmp3lame (mp3 extraction fails); ffmpeg 0.x builds predating required version '1.0'; output directories without write permission; input files with unsupported codecs.

Related errors

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