mudler/LocalAI · error · RuntimeError

failed to mux avatar audio: {details}

Error message

failed to mux avatar audio: {details}

What it means

RuntimeError raised when the ffmpeg subprocess that muxes the generated silent video with the audio track exits non-zero (subprocess.run(..., check=True) raises CalledProcessError). The last 2000 chars of ffmpeg stderr are appended as 'details'. This is a post-generation packaging step, so the expensive diffusion work already succeeded; typical causes are a missing/broken ffmpeg binary, an unwritable destination, or a codec/container mismatch (e.g. pcm in mp4).

Source

Thrown at backend/python/longcat-video/backend.py:881

                "-b:a",
                "192k",
                "-shortest",
                "-movflags",
                "+faststart",
                "-f",
                "mp4",
                dst,
            ]
            subprocess.run(
                command,
                check=True,
                stdout=subprocess.DEVNULL,
                stderr=subprocess.PIPE,
                text=True,
            )
        except subprocess.CalledProcessError as err:
            details = (err.stderr or "ffmpeg failed")[-2000:]
            raise RuntimeError(f"failed to mux avatar audio: {details}") from err
        finally:
            try:
                os.remove(silent_path)
            except FileNotFoundError:
                pass

    def _release_model(self):
        self.pipeline = None
        self.model_kind = None
        gc.collect()
        if hasattr(self, "torch") and self.torch.cuda.is_available():
            self.torch.cuda.empty_cache()
            self.torch.cuda.ipc_collect()

    @staticmethod
    def _fail(context, code, message):
        if context is not None:
            context.set_code(code)

View on GitHub (pinned to 44413a9d06)

Solutions

  1. Read the embedded ffmpeg stderr tail — it names the exact failure (no such file, invalid codec, permission denied)
  2. Ensure ffmpeg is installed in the backend environment and the dst directory exists and is writable
  3. For container deployments, use an image or apt/apk install that includes ffmpeg and standard encoders

Example fix

# before: slim image without ffmpeg
# Dockerfile
FROM python:3.11-slim

# after
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
Defensive patterns

Strategy: retry

Validate before calling

import shutil, subprocess

def ffmpeg_ready() -> bool:
    exe = shutil.which("ffmpeg")
    if not exe:
        return False
    return subprocess.run([exe, "-version"], capture_output=True).returncode == 0

# call during backend/container startup; fail the deployment if False

Try / catch

try:
    stub.GenerateVideo(req)
except grpc.RpcError as e:
    details = e.details() or ""
    if "failed to mux" in details:
        # video frames already generated; inspect stderr tail in details,
        # fix env (install ffmpeg / fix dst perms), then retry the request once
        ensure_ffmpeg_installed()
        stub.GenerateVideo(req)
    else:
        raise

Prevention

When it happens

Trigger: ffmpeg not installed or not on PATH inside the backend container/image; dst directory removed between request start and mux time; audio parameters libav cannot store in the target container; disk full.

Common situations: Slim Docker images without ffmpeg; NFS/temp volumes with transient write failures; dst path with characters or extensions ffmpeg cannot infer a muxer for.

Related errors

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/28c2040ee48e3293. Report an issue: GitHub.