{"record":{"id":"b942a9e2a7156780","repo":"calesthio/OpenMontage","slug":"avatar-smoke-requires-an-existing-narration-file","errorCode":null,"errorMessage":"Avatar smoke requires an existing narration file: {narration_path}. Run --live-full or --live-all first.","messagePattern":"Avatar smoke requires an existing narration file: (.+?)\\. Run --live-full or --live-all first\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"scripts/kling_official_animated_explainer_e2e.py","lineNumber":490,"sourceCode":"\ndef _run_live_avatar_suite(\n    project_dir: Path,\n    *,\n    timeout_seconds: int,\n    poll_interval: float,\n) -> dict[str, Any]:\n    image = registry.get(\"image_selector\")\n    avatar = registry.get(\"kling_avatar\")\n    lip_sync = registry.get(\"kling_lip_sync\")\n    assert image and avatar and lip_sync\n\n    assets_dir = project_dir / \"assets\"\n    image_dir = assets_dir / \"images\"\n    video_dir = assets_dir / \"video\"\n    artifacts_dir = project_dir / \"artifacts\"\n    narration_path = assets_dir / \"audio\" / \"narration.mp3\"\n    if not narration_path.is_file():\n        raise RuntimeError(\n            f\"Avatar smoke requires an existing narration file: {narration_path}. \"\n            \"Run --live-full or --live-all first.\"\n        )\n\n    _announce_paid_call(\n        \"image_selector -> kling_official_image\",\n        \"kling_official\",\n        \"kling-v3 generation\",\n        \"Create one synthetic single-face portrait for the avatar provider smoke.\",\n        \"sample\",\n    )\n    portrait_result = image.execute(\n        {\n            \"preferred_provider\": \"kling_official\",\n            \"allowed_providers\": [\"kling_official\"],\n            \"prompt\": (\n                \"Photorealistic studio portrait of one fictional adult presenter, front-facing, \"\n                \"head and shoulders centered, neutral expression, mouth closed, even soft lighting, \"","sourceCodeStart":472,"sourceCodeEnd":508,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/scripts/kling_official_animated_explainer_e2e.py#L472-L508","documentation":"Raised at the start of the avatar smoke run when the expected narration file assets/audio/narration.mp3 does not exist in the project directory. The avatar/lip-sync smoke intentionally reuses narration audio produced by the full pipeline instead of generating it, so the file is a hard prerequisite. The message explicitly tells you which earlier mode (--live-full or --live-all) produces it.","triggerScenarios":"Running scripts/kling_official_animated_explainer_e2e.py with the avatar-smoke flag on a fresh project_dir where the narration stage has never executed; or running it with a different --project-dir than the one the full run wrote assets into.","commonSituations":"Wrong project directory argument (assets land elsewhere); a previous full run failed before the narration/TTS stage; the narration file was moved or cleaned up; CI starting from a clean workspace without cached assets.","solutions":["Run --live-full or --live-all once in the same project directory so assets/audio/narration.mp3 is generated","Verify you passed the same --project-dir as the earlier full run (ls <project_dir>/assets/audio/)","If narration exists under a different name/codec, rename or transcode it to assets/audio/narration.mp3 with ffmpeg"],"exampleFix":"# before\npython scripts/kling_official_animated_explainer_e2e.py --live-avatar --project-dir ./proj\n# -> RuntimeError if ./proj/assets/audio/narration.mp3 missing\n\n# after\npython scripts/kling_official_animated_explainer_e2e.py --live-full --project-dir ./proj\npython scripts/kling_official_animated_explainer_e2e.py --live-avatar --project-dir ./proj","handlingStrategy":"validation","validationCode":"from pathlib import Path\nnarration = project_dir / \"assets\" / \"audio\" / \"narration.mp3\"\nif not narration.is_file():\n    raise SystemExit(\"narration missing — run --live-full first in this project dir\")","typeGuard":null,"tryCatchPattern":"try:\n    run_avatar_smoke(project_dir)\nexcept RuntimeError as e:\n    if \"narration file\" in str(e):\n        raise SystemExit(\"run --live-full in this project dir, then retry\")\n    raise","preventionTips":["Always run --live-full before --live-avatar in the same --project-dir","Check assets/audio/narration.mp3 exists before invoking smoke","Cache generated assets between runs so the prerequisite survives cleanup"],"tags":["e2e","prerequisite","kling","file-check"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}