calesthio/OpenMontage · error · RuntimeError

Avatar smoke requires an existing narration file: {narration

Error message

Avatar smoke requires an existing narration file: {narration_path}. Run --live-full or --live-all first.

What it means

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.

Source

Thrown at scripts/kling_official_animated_explainer_e2e.py:490

def _run_live_avatar_suite(
    project_dir: Path,
    *,
    timeout_seconds: int,
    poll_interval: float,
) -> dict[str, Any]:
    image = registry.get("image_selector")
    avatar = registry.get("kling_avatar")
    lip_sync = registry.get("kling_lip_sync")
    assert image and avatar and lip_sync

    assets_dir = project_dir / "assets"
    image_dir = assets_dir / "images"
    video_dir = assets_dir / "video"
    artifacts_dir = project_dir / "artifacts"
    narration_path = assets_dir / "audio" / "narration.mp3"
    if not narration_path.is_file():
        raise RuntimeError(
            f"Avatar smoke requires an existing narration file: {narration_path}. "
            "Run --live-full or --live-all first."
        )

    _announce_paid_call(
        "image_selector -> kling_official_image",
        "kling_official",
        "kling-v3 generation",
        "Create one synthetic single-face portrait for the avatar provider smoke.",
        "sample",
    )
    portrait_result = image.execute(
        {
            "preferred_provider": "kling_official",
            "allowed_providers": ["kling_official"],
            "prompt": (
                "Photorealistic studio portrait of one fictional adult presenter, front-facing, "
                "head and shoulders centered, neutral expression, mouth closed, even soft lighting, "

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Run --live-full or --live-all once in the same project directory so assets/audio/narration.mp3 is generated
2. Verify you passed the same --project-dir as the earlier full run (ls <project_dir>/assets/audio/)
3. If narration exists under a different name/codec, rename or transcode it to assets/audio/narration.mp3 with ffmpeg

Example fix

# before
python scripts/kling_official_animated_explainer_e2e.py --live-avatar --project-dir ./proj
# -> RuntimeError if ./proj/assets/audio/narration.mp3 missing

# after
python scripts/kling_official_animated_explainer_e2e.py --live-full --project-dir ./proj
python scripts/kling_official_animated_explainer_e2e.py --live-avatar --project-dir ./proj

from pathlib import Path
narration = project_dir / "assets" / "audio" / "narration.mp3"
if not narration.is_file():
    raise SystemExit("narration missing — run --live-full first in this project dir")

try:
    run_avatar_smoke(project_dir)
except RuntimeError as e:
    if "narration file" in str(e):
        raise SystemExit("run --live-full in this project dir, then retry")
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• {name} failed: {result.error}
• Kling result did not include a remote video URL for lip-sync
• callback_url must be an absolute http(s) URL
• KLING_API_KEY is not set. Configure KLING_API_KEY for offici
• Kling Classic create response missing data.task_id: {data}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/b942a9e2a7156780. Report an issue: GitHub.