{"record":{"id":"28c2040ee48e3293","repo":"mudler/LocalAI","slug":"failed-to-mux-avatar-audio-details","errorCode":null,"errorMessage":"failed to mux avatar audio: {details}","messagePattern":"failed to mux avatar audio: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/python/longcat-video/backend.py","lineNumber":881,"sourceCode":"                \"-b:a\",\n                \"192k\",\n                \"-shortest\",\n                \"-movflags\",\n                \"+faststart\",\n                \"-f\",\n                \"mp4\",\n                dst,\n            ]\n            subprocess.run(\n                command,\n                check=True,\n                stdout=subprocess.DEVNULL,\n                stderr=subprocess.PIPE,\n                text=True,\n            )\n        except subprocess.CalledProcessError as err:\n            details = (err.stderr or \"ffmpeg failed\")[-2000:]\n            raise RuntimeError(f\"failed to mux avatar audio: {details}\") from err\n        finally:\n            try:\n                os.remove(silent_path)\n            except FileNotFoundError:\n                pass\n\n    def _release_model(self):\n        self.pipeline = None\n        self.model_kind = None\n        gc.collect()\n        if hasattr(self, \"torch\") and self.torch.cuda.is_available():\n            self.torch.cuda.empty_cache()\n            self.torch.cuda.ipc_collect()\n\n    @staticmethod\n    def _fail(context, code, message):\n        if context is not None:\n            context.set_code(code)","sourceCodeStart":863,"sourceCodeEnd":899,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/longcat-video/backend.py#L863-L899","documentation":"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).","triggerScenarios":"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.","commonSituations":"Slim Docker images without ffmpeg; NFS/temp volumes with transient write failures; dst path with characters or extensions ffmpeg cannot infer a muxer for.","solutions":["Read the embedded ffmpeg stderr tail — it names the exact failure (no such file, invalid codec, permission denied)","Ensure ffmpeg is installed in the backend environment and the dst directory exists and is writable","For container deployments, use an image or apt/apk install that includes ffmpeg and standard encoders"],"exampleFix":"# before: slim image without ffmpeg\n# Dockerfile\nFROM python:3.11-slim\n\n# after\nFROM python:3.11-slim\nRUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*","handlingStrategy":"retry","validationCode":"import shutil, subprocess\n\ndef ffmpeg_ready() -> bool:\n    exe = shutil.which(\"ffmpeg\")\n    if not exe:\n        return False\n    return subprocess.run([exe, \"-version\"], capture_output=True).returncode == 0\n\n# call during backend/container startup; fail the deployment if False","typeGuard":null,"tryCatchPattern":"try:\n    stub.GenerateVideo(req)\nexcept grpc.RpcError as e:\n    details = e.details() or \"\"\n    if \"failed to mux\" in details:\n        # video frames already generated; inspect stderr tail in details,\n        # fix env (install ffmpeg / fix dst perms), then retry the request once\n        ensure_ffmpeg_installed()\n        stub.GenerateVideo(req)\n    else:\n        raise","preventionTips":["Include ffmpeg in the backend image and verify it at container startup","Ensure the dst directory is created and writable before requesting generation","Log the mux stderr details — they usually pinpoint the codec/container issue"],"tags":["python","longcat-video","ffmpeg","subprocess","video-generation"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}