@remixmate/cli 0.12.8 → 0.13.0

package/skills/render-video/scripts/render_video.py

@@ -37,7 +37,7 @@ import time
 import urllib.error
 import urllib.request
 from datetime import datetime, timezone
-from typing import Optional
+from typing import Callable, Optional
 
 
 
@@ -700,15 +700,10 @@ def validate_and_fix_render_plan(render_plan: dict) -> list:
         if asset.get("duration") is None and needs_video_duration:
 
 
+
             fallback_dur = None
             for entry in render_plan.get("timeline", []):
-                props = entry.get("props") or {}
-                refs = (
-                    props.get("videoAssetId"),
-                    props.get("backgroundAssetId"),
-                    props.get("imageAssetId"),
-                )
-                if asset.get("assetId") in refs:
+                if _props_reference(entry.get("props") or {}, asset.get("assetId")):
                     fallback_dur = entry.get("durationFrames", 150) / fps
                     break
             if fallback_dur:
@@ -785,6 +780,19 @@ def _probe_video_meta(url: str) -> dict:
     return probe_video_meta(url)
 
 
+def _props_reference(value, asset_id) -> bool:
+
+    if not asset_id:
+        return False
+    if isinstance(value, str):
+        return value == asset_id
+    if isinstance(value, dict):
+        return any(_props_reference(v, asset_id) for v in value.values())
+    if isinstance(value, list):
+        return any(_props_reference(v, asset_id) for v in value)
+    return False
+
+
 def build_render_plan(dsl: dict, binding: dict) -> dict:
 
     fps = dsl.get("global", {}).get("fps", 30)
@@ -881,6 +889,7 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
 
 
 
+
     meta_by_url: dict = {}
     for aid, asset in assets_by_id.items():
         url = asset.get("url")
@@ -988,6 +997,10 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
             "subtitleAtSec": subtitle_at_sec,
             "transition": {"type": scene_trans_type, "durationFrames": scene_trans_dur},
         }
+
+
+        if isinstance(scene.get("textLayers"), list) and scene["textLayers"]:
+            entry["textLayers"] = scene["textLayers"]
         timeline.append(entry)
         current_frame += duration_frames
 
@@ -1617,8 +1630,6 @@ def _auto_highlight_map(
 
 
 
-
-
     if not narration_asset:
         return
     line_count = narration_asset.get("narrationLineCount")
@@ -1879,17 +1890,6 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
 
         entry.pop("layers", None)
 
-
-        slides = entry.get("props", {}).get("slides")
-        if slides and isinstance(slides, list) and len(slides) > 0:
-            scene_dur = entry["durationFrames"]
-            per_slide = scene_dur // len(slides)
-            remainder = scene_dur - per_slide * len(slides)
-            for si, slide in enumerate(slides):
-                if not isinstance(slide, dict):
-                    continue
-                slide["durationFrames"] = per_slide + (1 if si < remainder else 0)
-
         current_frame += entry["durationFrames"]
 
     render_plan["renderConfig"]["totalFrames"] = current_frame
@@ -2137,8 +2137,6 @@ def render_with_remote_api(
 
 
 
-    import remote_renderer_client
-
     render_plan["status"] = "rendering"
     render_plan["renderMode"] = "remote"
     render_plan["logs"].append({
@@ -2147,6 +2145,30 @@ def render_with_remote_api(
         "timestamp": now_iso(),
     })
 
+    request = _remote_render_request(render_plan, output_path, upload_title)
+    submitted = _submit_or_resume_remote_task(
+        render_plan, request["payload"], request["render_path"], request["status_path"],
+        private_token=private_token, conversation_id=conversation_id, job_id=job_id,
+    )
+    if submitted is None:
+        return False
+    task_id, status_path = submitted
+    finished, result = _poll_remote_task(
+        render_plan, task_id, status_path,
+        private_token=private_token, poll_timeout=poll_timeout, poll_interval=poll_interval, job_id=job_id,
+    )
+    if not finished:
+        return False
+    return _apply_remote_result(
+        render_plan, result,
+        effective_title=request["effective_title"],
+        cover_composition_id=request["cover_composition_id"],
+        private_token=private_token,
+    )
+
+
+def _remote_render_request(render_plan: dict, output_path: str, upload_title: Optional[str]) -> dict:
+
     https_assets = []
     for asset in render_plan.get("resolvedAssets", []):
         asset = asset.copy()
@@ -2260,6 +2282,27 @@ def render_with_remote_api(
     LogPrint(f"   size: {config.get('width')}x{config.get('height')}", file=sys.stderr)
     LogPrint(f"   total frames: {total_frames}", file=sys.stderr)
     sys.stderr.flush()
+    return {
+        "payload": payload,
+        "render_path": render_path,
+        "status_path": status_path,
+        "effective_title": effective_title,
+        "cover_composition_id": cover_composition_id,
+    }
+
+
+def _submit_or_resume_remote_task(
+    render_plan: dict,
+    payload: dict,
+    render_path: str,
+    status_path: str,
+    *,
+    private_token: str,
+    conversation_id: Optional[str],
+    job_id: Optional[int],
+) -> Optional[tuple[str, str]]:
+
+    import remote_renderer_client
 
 
 
@@ -2290,7 +2333,7 @@ def render_with_remote_api(
                 "message": f"remote start_render failed: {exc}",
                 "timestamp": now_iso(),
             })
-            return False
+            return None
 
         LogPrint(f"   ✅ task submitted, taskId={task_id}", file=sys.stderr)
         render_plan["remoteTaskId"] = task_id
@@ -2306,6 +2349,11 @@ def render_with_remote_api(
 
         _persist_plan_checkpoint(render_plan, job_id, private_token)
 
+    return task_id, status_path
+
+
+def _remote_progress_reporter(render_plan: dict, task_id: str) -> Callable[[dict], None]:
+
     last_progress = -1.0
     last_status: Optional[str] = None
     last_stage: Optional[str] = None
@@ -2364,6 +2412,24 @@ def render_with_remote_api(
             last_stage = stage
             last_emit_at = now
 
+    return _on_progress
+
+
+def _poll_remote_task(
+    render_plan: dict,
+    task_id: str,
+    status_path: str,
+    *,
+    private_token: str,
+    poll_timeout: float,
+    poll_interval: float,
+    job_id: Optional[int],
+) -> tuple[bool, Optional[dict]]:
+
+    import remote_renderer_client
+
+    _on_progress = _remote_progress_reporter(render_plan, task_id)
+
 
 
 
@@ -2411,7 +2477,7 @@ def render_with_remote_api(
             f"用同一个 job_id 再调一次 render_video 即可续上，不会重新渲染。",
             flush=True,
         )
-        return False
+        return False, None
     except Exception as exc:
         LogPrint(f"❌ remote render polling failed: {exc}", file=sys.stderr)
         render_plan["status"] = "failed"
@@ -2426,10 +2492,21 @@ def render_with_remote_api(
             "message": f"remote poll_render failed: {exc}",
             "timestamp": now_iso(),
         })
-        return False
+        return False, None
     finally:
 
         signal.signal(signal.SIGINT, prev_sigint)
+    return True, result
+
+
+def _apply_remote_result(
+    render_plan: dict,
+    result: Optional[dict],
+    *,
+    effective_title: str,
+    cover_composition_id: Optional[str],
+    private_token: str,
+) -> bool:
 
     file_url =(result or {}).get("fileUrl") or (result or {}).get("videoUrl")
     if not file_url:
@@ -2597,9 +2674,7 @@ def _log_render_plan_summary(render_plan: dict) -> None:
         pass
 
 
-def main():
-
-    atexit.register(print_billing_footer)
+def _build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Video render tool — DSL + TemplateBinding → Remotion video.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -2672,154 +2747,164 @@ Examples:
         default=None,
         help="Test mode: every source=gen-video asset is short-circuited to this URL, no gen-video API call (env STUB_VIDEO_URL works too, but the explicit CLI flag is preferred to avoid cross-session leakage).",
     )
+    return parser
 
-    args = parser.parse_args()
 
-    private_token = args.priv_token or os.environ.get("PRIV_TOKEN", "")
+def _load_plan_from_job(job_id: int, private_token: str) -> dict:
 
 
-    if args.priv_token:
-        os.environ["PRIV_TOKEN"] = private_token
+    LogPrint(f"📋 loading RenderPlan from database (jobId={job_id})...", file=sys.stderr)
+    if not private_token:
+        LogPrint("❌ --job-id mode requires PRIV_TOKEN or --priv-token", file=sys.stderr)
+        sys.exit(1)
 
 
-    if args.save_job and not private_token:
-        LogPrint("ℹ️  PRIV_TOKEN not configured; --save-job auto-disabled (will not write to database)", file=sys.stderr)
-        args.save_job = False
 
-    if args.job_id is not None and args.job_id > 0:
+    from render_job_client import get_plan as rjc_get_plan
+    try:
+        render_plan_str = rjc_get_plan(job_id, private_token)
+    except RuntimeError as e:
+        LogPrint(f"❌ failed to fetch RenderPlan: {e}", file=sys.stderr)
+        sys.exit(1)
+    render_plan = json.loads(render_plan_str)
+    LogPrint(f"✅ RenderPlan loaded (jobId={job_id})", file=sys.stderr)
+    _log_render_plan_summary(render_plan)
+    return render_plan
 
-        LogPrint(f"📋 loading RenderPlan from database (jobId={args.job_id})...", file=sys.stderr)
-        if not private_token:
-            LogPrint("❌ --job-id mode requires PRIV_TOKEN or --priv-token", file=sys.stderr)
-            sys.exit(1)
 
+def _load_plan_from_file(plan_path: str, dsl_path: str | None) -> dict:
 
+    if not os.path.exists(plan_path):
+        LogPrint(f"❌ file does not exist: {plan_path}", file=sys.stderr)
+        sys.exit(1)
+    render_plan = load_json(plan_path)
+    LogPrint(f"📋 loaded existing RenderPlan: {plan_path}", file=sys.stderr)
+    _log_render_plan_summary(render_plan)
 
-        from render_job_client import get_plan as rjc_get_plan
+
+
+
+    if dsl_path and os.path.exists(dsl_path):
         try:
-            render_plan_str = rjc_get_plan(args.job_id, private_token)
-        except RuntimeError as e:
-            LogPrint(f"❌ failed to fetch RenderPlan: {e}", file=sys.stderr)
-            sys.exit(1)
-        render_plan = json.loads(render_plan_str)
-        LogPrint(f"✅ RenderPlan loaded (jobId={args.job_id})", file=sys.stderr)
-        _log_render_plan_summary(render_plan)
-    elif args.render_plan:
-        if not os.path.exists(args.render_plan):
-            LogPrint(f"❌ file does not exist: {args.render_plan}", file=sys.stderr)
-            sys.exit(1)
-        render_plan = load_json(args.render_plan)
-        LogPrint(f"📋 loaded existing RenderPlan: {args.render_plan}", file=sys.stderr)
-        _log_render_plan_summary(render_plan)
+            if os.path.getmtime(plan_path) < os.path.getmtime(dsl_path):
+                LogPrint(
+                    f"⚠️  STALE RenderPlan? '{plan_path}' is OLDER than the DSL "
+                    f"'{dsl_path}'. You may be rendering a leftover plan from a previous "
+                    "run. Regenerate with --dsl ... --template-id ... (drop --render-plan) "
+                    "if the summary above doesn't match what you expect.",
+                    file=sys.stderr,
+                )
+        except OSError:
+            pass
+    return render_plan
 
 
+def _parse_dsl_json(dsl_json: str) -> dict:
 
 
-        if args.dsl and os.path.exists(args.dsl):
-            try:
-                if os.path.getmtime(args.render_plan) < os.path.getmtime(args.dsl):
-                    LogPrint(
-                        f"⚠️  STALE RenderPlan? '{args.render_plan}' is OLDER than the DSL "
-                        f"'{args.dsl}'. You may be rendering a leftover plan from a previous "
-                        "run. Regenerate with --dsl ... --template-id ... (drop --render-plan) "
-                        "if the summary above doesn't match what you expect.",
-                        file=sys.stderr,
-                    )
-            except OSError:
-                pass
-    else:
-        if not args.dsl and not args.dsl_json:
-            LogPrint(
-                "❌ render_video needs a DSL source. You provided neither --dsl/--dsl-json "
-                "nor --render-plan/--job-id.\n"
-                "   Typical flow: 1) gen_script → DSL skeleton  2) prepare_video_assets "
-                "(returns a job_id)  3) render_video with job_id=<int>.\n"
-                "   Or pass the DSL inline: render_video --dsl-json '<json>' --template-id <id>.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
 
-        if not args.template_id:
-            LogPrint(
-                "❌ render_video needs --template-id when rendering from --dsl/--dsl-json "
-                "(binding is computed in-memory from the template id; --binding is no longer supported).",
-                file=sys.stderr,
-            )
+
+
+
+
+    try:
+        dsl = json.loads(dsl_json)
+    except json.JSONDecodeError:
+        dsl = None
+    if dsl is None:
+        try:
+
+            _dsl_str = dsl_json
+
+            _dsl_str = _dsl_str.replace('\u201c', '"').replace('\u201d', '"')
+            _dsl_str = _dsl_str.replace('\u2018', "'").replace('\u2019', "'")
+
+            _dsl_str = _dsl_str.replace('\uff1a', ':')
+            _dsl_str = _dsl_str.replace('\uff0c', ',')
+            _dsl_str = _dsl_str.replace('\uff08', '(')
+            _dsl_str = _dsl_str.replace('\uff09', ')')
+            _dsl_str = _dsl_str.replace('\u3010', '[')
+            _dsl_str = _dsl_str.replace('\u3011', ']')
+            _dsl_str = _dsl_str.replace('\uff3b', '[')
+            _dsl_str = _dsl_str.replace('\uff3d', ']')
+            _dsl_str = _dsl_str.replace('\uff5b', '{')
+            _dsl_str = _dsl_str.replace('\uff5d', '}')
+            dsl = json.loads(_dsl_str)
+            LogPrint("⚠️  --dsl-json was not valid JSON; parsed after normalizing full-width punctuation", file=sys.stderr)
+        except json.JSONDecodeError as e:
+            LogPrint(f"❌ --dsl-json parse failed: {e}", file=sys.stderr)
             sys.exit(1)
+    return dsl
 
 
-        if args.dsl_json:
+def _load_dsl(args) -> dict:
 
+    if not args.dsl and not args.dsl_json:
+        LogPrint(
+            "❌ render_video needs a DSL source. You provided neither --dsl/--dsl-json "
+            "nor --render-plan/--job-id.\n"
+            "   Typical flow: 1) gen_script → DSL skeleton  2) prepare_video_assets "
+            "(returns a job_id)  3) render_video with job_id=<int>.\n"
+            "   Or pass the DSL inline: render_video --dsl-json '<json>' --template-id <id>.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
+    if not args.template_id:
+        LogPrint(
+            "❌ render_video needs --template-id when rendering from --dsl/--dsl-json "
+            "(binding is computed in-memory from the template id; --binding is no longer supported).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
 
+    if args.dsl_json:
+        dsl = _parse_dsl_json(args.dsl_json)
+    else:
+        if not os.path.exists(args.dsl):
+            LogPrint(f"❌ file does not exist: {args.dsl}", file=sys.stderr)
+            sys.exit(1)
+        dsl = load_json(args.dsl)
 
 
-            try:
-                dsl = json.loads(args.dsl_json)
-            except json.JSONDecodeError:
-                dsl = None
-            if dsl is None:
-                try:
+    if "version" not in dsl:
+        dsl["version"] = "v1alpha1"
+        LogPrint("⚠️  DSL missing version field; auto-filled with v1alpha1", file=sys.stderr)
 
-                    _dsl_str = args.dsl_json
-
-                    _dsl_str = _dsl_str.replace('\u201c', '"').replace('\u201d', '"')
-                    _dsl_str = _dsl_str.replace('\u2018', "'").replace('\u2019', "'")
-
-                    _dsl_str = _dsl_str.replace('\uff1a', ':')
-                    _dsl_str = _dsl_str.replace('\uff0c', ',')
-                    _dsl_str = _dsl_str.replace('\uff08', '(')
-                    _dsl_str = _dsl_str.replace('\uff09', ')')
-                    _dsl_str = _dsl_str.replace('\u3010', '[')
-                    _dsl_str = _dsl_str.replace('\u3011', ']')
-                    _dsl_str = _dsl_str.replace('\uff3b', '[')
-                    _dsl_str = _dsl_str.replace('\uff3d', ']')
-                    _dsl_str = _dsl_str.replace('\uff5b', '{')
-                    _dsl_str = _dsl_str.replace('\uff5d', '}')
-                    dsl = json.loads(_dsl_str)
-                    LogPrint("⚠️  --dsl-json was not valid JSON; parsed after normalizing full-width punctuation", file=sys.stderr)
-                except json.JSONDecodeError as e:
-                    LogPrint(f"❌ --dsl-json parse failed: {e}", file=sys.stderr)
-                    sys.exit(1)
-        else:
-            if not os.path.exists(args.dsl):
-                LogPrint(f"❌ file does not exist: {args.dsl}", file=sys.stderr)
-                sys.exit(1)
-            dsl = load_json(args.dsl)
+    return dsl
 
 
-        if "version" not in dsl:
-            dsl["version"] = "v1alpha1"
-            LogPrint("⚠️  DSL missing version field; auto-filled with v1alpha1", file=sys.stderr)
+def _reject_skeleton_dsl(dsl: dict) -> None:
 
 
 
+    _skeleton_offenders: list[str] = []
+    _skel_markers = ("[骨架待填充]", "[skeleton placeholder]", "这是需要替换的占位文案")
+    for _scene in dsl.get("scenes", []) or []:
+        _nar = ((_scene.get("audio") or {}).get("narration") or {})
+        _sid = _scene.get("id", "?")
+        if _nar.get("needsFill") is True:
+            _skeleton_offenders.append(f"scene {_sid}: narration.needsFill=true")
+            continue
+        _t = _nar.get("text") or ""
+        if any(m in _t for m in _skel_markers):
+            _skeleton_offenders.append(f"scene {_sid}: narration.text still has the skeleton marker")
+    if _skeleton_offenders:
+        LogPrint("❌ DSL narration is still the gen_script skeleton and was not replaced with real content; refusing to continue:", file=sys.stderr)
+        for _off in _skeleton_offenders[:5]:
+            LogPrint(f"   - {_off}", file=sys.stderr)
+        if len(_skeleton_offenders) > 5:
+            LogPrint(f"   ... ({len(_skeleton_offenders)} total)", file=sys.stderr)
+        LogPrint(
+            "   Fill audio.narration.text with the real narration for every scene "
+            "and remove the needsFill field, then retry.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
 
-        _skeleton_offenders: list[str] = []
-        _skel_markers = ("[骨架待填充]", "[skeleton placeholder]", "这是需要替换的占位文案")
-        for _scene in dsl.get("scenes", []) or []:
-            _nar = ((_scene.get("audio") or {}).get("narration") or {})
-            _sid = _scene.get("id", "?")
-            if _nar.get("needsFill") is True:
-                _skeleton_offenders.append(f"scene {_sid}: narration.needsFill=true")
-                continue
-            _t = _nar.get("text") or ""
-            if any(m in _t for m in _skel_markers):
-                _skeleton_offenders.append(f"scene {_sid}: narration.text still has the skeleton marker")
-        if _skeleton_offenders:
-            LogPrint("❌ DSL narration is still the gen_script skeleton and was not replaced with real content; refusing to continue:", file=sys.stderr)
-            for _off in _skeleton_offenders[:5]:
-                LogPrint(f"   - {_off}", file=sys.stderr)
-            if len(_skeleton_offenders) > 5:
-                LogPrint(f"   ... ({len(_skeleton_offenders)} total)", file=sys.stderr)
-            LogPrint(
-                "   Fill audio.narration.text with the real narration for every scene "
-                "and remove the needsFill field, then retry.",
-                file=sys.stderr,
-            )
-            sys.exit(2)
 
+def _plan_from_dsl(dsl: dict, args) -> tuple[dict, dict]:
 
 
 
@@ -2830,44 +2915,49 @@ Examples:
 
 
 
-        _hydrate_dsl_payload(dsl, args.template_id, args.source_document_url)
 
+    _hydrate_dsl_payload(dsl, args.template_id, args.source_document_url)
 
 
-        _compose_image_prompts(dsl, args.template_id)
 
-        errors = validate_dsl(dsl)
-        if errors:
-            LogPrint("❌ DSL validation failed:", file=sys.stderr)
-            for err in errors:
-                LogPrint(f"   - {err}", file=sys.stderr)
-            sys.exit(1)
+    _compose_image_prompts(dsl, args.template_id)
 
+    errors = validate_dsl(dsl)
+    if errors:
+        LogPrint("❌ DSL validation failed:", file=sys.stderr)
+        for err in errors:
+            LogPrint(f"   - {err}", file=sys.stderr)
+        sys.exit(1)
 
 
 
 
 
-        binding = auto_bind_template(dsl, args.template_id)
 
-        LogPrint(f"📋 Building RenderPlan...", file=sys.stderr)
-        render_plan = build_render_plan(dsl, binding)
-        render_plan["_dsl_assets"] = dsl.get("assets", [])
+    binding = auto_bind_template(dsl, args.template_id)
 
+    LogPrint(f"📋 Building RenderPlan...", file=sys.stderr)
+    render_plan = build_render_plan(dsl, binding)
+    render_plan["_dsl_assets"] = dsl.get("assets", [])
+    return render_plan, binding
 
 
-    if args.job_id or args.render_plan:
-        from registry_loader import get_template
-        from required_props import validate_required_props
-        try:
-            template = get_template(render_plan.get("templateId", ""), include_all_statuses=True)
-            if not template:
-                raise ValueError("Cannot validate RenderPlan: template metadata unavailable")
-            validate_required_props(template, render_plan.get("timeline", []))
-        except ValueError as exc:
-            LogPrint(f"❌ {exc}", file=sys.stderr)
-            sys.exit(2)
+def _validate_saved_plan(render_plan: dict) -> None:
+
+
+    from registry_loader import get_template
+    from required_props import validate_required_props
+    try:
+        template = get_template(render_plan.get("templateId", ""), include_all_statuses=True)
+        if not template:
+            raise ValueError("Cannot validate RenderPlan: template metadata unavailable")
+        validate_required_props(template, render_plan.get("timeline", []))
+    except ValueError as exc:
+        LogPrint(f"❌ {exc}", file=sys.stderr)
+        sys.exit(2)
 
+
+def _reject_bad_asset_refs(render_plan: dict) -> None:
     from video_dsl.runtime.payload_contract import plan_asset_errors
     reference_errors = plan_asset_errors(render_plan)
     if reference_errors:
@@ -2876,212 +2966,197 @@ Examples:
             LogPrint(f"   - {error}", file=sys.stderr)
         sys.exit(2)
 
-    if not args.skip_asset_resolve:
 
+def _resolve_plan_assets(render_plan: dict, args, private_token: str) -> dict:
 
 
-        stub_image_url = args.stub_image_url
-        stub_video_url = args.stub_video_url
-        if stub_image_url is None:
-            env_v = os.environ.get("STUB_IMAGE_URL", "")
-            if env_v:
-                LogPrint(f"⚠️  detected env var STUB_IMAGE_URL={env_v}; using it as the image stub URL (pass --stub-image-url explicitly or unset the env var)", file=sys.stderr)
-            stub_image_url = env_v
-        if stub_video_url is None:
-            env_v = os.environ.get("STUB_VIDEO_URL", "")
-            if env_v:
-                LogPrint(f"⚠️  detected env var STUB_VIDEO_URL={env_v}; using it as the video stub URL (pass --stub-video-url explicitly or unset the env var)", file=sys.stderr)
-            stub_video_url = env_v
-
-        if stub_image_url or stub_video_url:
-            stubbed = apply_stub_urls(
-                render_plan,
-                stub_image_url=stub_image_url,
-                stub_video_url=stub_video_url,
-            )
-            if stubbed:
-                LogPrint(f"🧪 Stub mode: {stubbed} asset(s) using a stub URL; generation API skipped", file=sys.stderr)
-            else:
-                LogPrint(f"🧪 Stub mode is on but no matching assets were found (no pending gen-image / gen-video resources)", file=sys.stderr)
-        pending_count = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "pending")
-        if pending_count > 0:
-
-
-
-            if not private_token:
-                LogPrint("❌ asset generation needs an auth token, but PRIV_TOKEN env var is not set and --priv-token was not passed", file=sys.stderr)
-                LogPrint("   configure it one of these ways:", file=sys.stderr)
-                LogPrint("   1. export PRIV_TOKEN=<your-token>", file=sys.stderr)
-                LogPrint("   2. python3 render_video.py --priv-token <your-token> ...", file=sys.stderr)
-                sys.exit(1)
-
-            LogPrint(f"🔍 Resolving {pending_count} missing asset(s)...", file=sys.stderr)
-            render_plan = resolve_assets(
-                render_plan,
-                private_token=private_token,
-                max_retries=args.max_asset_retries,
-                timeout=args.asset_timeout,
-                defer_digital_human=True,
-            )
+
+
+    stub_image_url = args.stub_image_url
+    stub_video_url = args.stub_video_url
+    if stub_image_url is None:
+        env_v = os.environ.get("STUB_IMAGE_URL", "")
+        if env_v:
+            LogPrint(f"⚠️  detected env var STUB_IMAGE_URL={env_v}; using it as the image stub URL (pass --stub-image-url explicitly or unset the env var)", file=sys.stderr)
+        stub_image_url = env_v
+    if stub_video_url is None:
+        env_v = os.environ.get("STUB_VIDEO_URL", "")
+        if env_v:
+            LogPrint(f"⚠️  detected env var STUB_VIDEO_URL={env_v}; using it as the video stub URL (pass --stub-video-url explicitly or unset the env var)", file=sys.stderr)
+        stub_video_url = env_v
+
+    if stub_image_url or stub_video_url:
+        stubbed = apply_stub_urls(
+            render_plan,
+            stub_image_url=stub_image_url,
+            stub_video_url=stub_video_url,
+        )
+        if stubbed:
+            LogPrint(f"🧪 Stub mode: {stubbed} asset(s) using a stub URL; generation API skipped", file=sys.stderr)
         else:
-            LogPrint(f"✅ all assets ready", file=sys.stderr)
-            render_plan["status"] = "assets-ready"
+            LogPrint(f"🧪 Stub mode is on but no matching assets were found (no pending gen-image / gen-video resources)", file=sys.stderr)
+    pending_count = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "pending")
+    if pending_count > 0:
+
 
-    if not args.skip_asset_resolve:
-        render_plan = adjust_timeline_to_audio(render_plan)
 
+        if not private_token:
+            LogPrint("❌ asset generation needs an auth token, but PRIV_TOKEN env var is not set and --priv-token was not passed", file=sys.stderr)
+            LogPrint("   configure it one of these ways:", file=sys.stderr)
+            LogPrint("   1. export PRIV_TOKEN=<your-token>", file=sys.stderr)
+            LogPrint("   2. python3 render_video.py --priv-token <your-token> ...", file=sys.stderr)
+            sys.exit(1)
 
-        render_plan = resolve_digital_human_segments(
+        LogPrint(f"🔍 Resolving {pending_count} missing asset(s)...", file=sys.stderr)
+        render_plan = resolve_assets(
             render_plan,
             private_token=private_token,
             max_retries=args.max_asset_retries,
             timeout=args.asset_timeout,
+            defer_digital_human=True,
         )
+    else:
+        LogPrint(f"✅ all assets ready", file=sys.stderr)
+        render_plan["status"] = "assets-ready"
 
-    render_plan.pop("_dsl_assets", None)
+    render_plan = adjust_timeline_to_audio(render_plan)
 
-    output_path = os.path.join(OUTPUT_DIR, "video.mp4")
-    rp_output = args.render_plan_output or os.path.join(OUTPUT_DIR, "render-plan.json")
 
+    render_plan = resolve_digital_human_segments(
+        render_plan,
+        private_token=private_token,
+        max_retries=args.max_asset_retries,
+        timeout=args.asset_timeout,
+    )
+    return render_plan
 
-    if args.save_render_plan or not args.save_job:
-        validate_and_fix_render_plan(render_plan)
-        save_json(render_plan, rp_output)
-        LogPrint(f"💾 RenderPlan saved: {rp_output}", file=sys.stderr)
 
+def _persist_render_plan(render_plan: dict, args, private_token: str, dsl: dict | None, binding: dict | None) -> None:
 
 
+    validate_and_fix_render_plan(render_plan)
 
-    if args.save_job:
+    from render_job_client import create_job as rjc_create_job, save_plan as rjc_save_plan
+    render_plan_json_str = json.dumps(render_plan, ensure_ascii=False)
 
-        validate_and_fix_render_plan(render_plan)
+    _job_id = args.job_id
+    if not _job_id:
 
-        from render_job_client import create_job as rjc_create_job, save_plan as rjc_save_plan
-        render_plan_json_str = json.dumps(render_plan, ensure_ascii=False)
 
-        _job_id = args.job_id
-        if not _job_id:
+        _dsl_obj = dsl
+        _binding_obj = binding
+        _meta_summary: dict = {}
 
 
-            _locals = locals()
-            _dsl_obj = _locals.get("dsl")
-            _binding_obj = _locals.get("binding")
-            _meta_summary: dict = {}
+        if _dsl_obj:
+            _src_meta = (_dsl_obj.get("meta") or {})
+            for _k in ("title", "topic", "platform", "templateId", "targetDuration"):
+                _v = _src_meta.get(_k)
+                if _v:
+                    _meta_summary[_k] = _v
+            _ratio = (_dsl_obj.get("global") or {}).get("aspectRatio")
+            if _ratio:
+                _meta_summary["aspectRatio"] = _ratio
+        else:
+            for _k in ("title", "templateId", "targetDuration"):
+                _v = render_plan.get(_k)
+                if _v:
+                    _meta_summary[_k] = _v
+            _rc = render_plan.get("renderConfig") or {}
+            if _rc.get("width") and _rc.get("height"):
+                _meta_summary["resolution"] = f"{_rc['width']}x{_rc['height']}"
+        if _binding_obj and isinstance(_binding_obj, dict):
+            _tid = _binding_obj.get("templateId")
+            if _tid and "templateId" not in _meta_summary:
+                _meta_summary["templateId"] = _tid
+        _dsl_str = json.dumps(_dsl_obj, ensure_ascii=False) if _dsl_obj else ""
+        try:
+            _job_id = rjc_create_job(
+                private_token,
+                dsl=_dsl_str,
+                dsl_meta=_meta_summary or None,
+            )
+            LogPrint(f"✅ render job created: jobId={_job_id}", file=sys.stderr)
+        except RuntimeError as e:
+            LogPrint(f"⚠️  failed to create render job (--save-job auto-disabled, rendering continues): {e}", file=sys.stderr)
+            args.save_job = False
+            _job_id = None
+    if args.save_job and _job_id:
+        try:
+            rjc_save_plan(_job_id, render_plan_json_str, private_token)
+            LogPrint(f"✅ RenderPlan saved to database: jobId={_job_id}", file=sys.stderr)
 
+            args.job_id = _job_id
+            print(f"\n📦 render job jobId: {_job_id}")
+        except RuntimeError as e:
+            LogPrint(f"⚠️  failed to save RenderPlan to database (--save-job auto-disabled, rendering continues): {e}", file=sys.stderr)
+            args.save_job = False
 
-            if _dsl_obj:
-                _src_meta = (_dsl_obj.get("meta") or {})
-                for _k in ("title", "topic", "platform", "templateId", "targetDuration"):
-                    _v = _src_meta.get(_k)
-                    if _v:
-                        _meta_summary[_k] = _v
-                _ratio = (_dsl_obj.get("global") or {}).get("aspectRatio")
-                if _ratio:
-                    _meta_summary["aspectRatio"] = _ratio
-            else:
-                for _k in ("title", "templateId", "targetDuration"):
-                    _v = render_plan.get(_k)
-                    if _v:
-                        _meta_summary[_k] = _v
-                _rc = render_plan.get("renderConfig") or {}
-                if _rc.get("width") and _rc.get("height"):
-                    _meta_summary["resolution"] = f"{_rc['width']}x{_rc['height']}"
-            if _binding_obj and isinstance(_binding_obj, dict):
-                _tid = _binding_obj.get("templateId")
-                if _tid and "templateId" not in _meta_summary:
-                    _meta_summary["templateId"] = _tid
-            _dsl_str = json.dumps(_dsl_obj, ensure_ascii=False) if _dsl_obj else ""
-            try:
-                _job_id = rjc_create_job(
-                    private_token,
-                    dsl=_dsl_str,
-                    dsl_meta=_meta_summary or None,
-                )
-                LogPrint(f"✅ render job created: jobId={_job_id}", file=sys.stderr)
-            except RuntimeError as e:
-                LogPrint(f"⚠️  failed to create render job (--save-job auto-disabled, rendering continues): {e}", file=sys.stderr)
-                args.save_job = False
-                _job_id = None
-        if args.save_job and _job_id:
-            try:
-                rjc_save_plan(_job_id, render_plan_json_str, private_token)
-                LogPrint(f"✅ RenderPlan saved to database: jobId={_job_id}", file=sys.stderr)
 
-                args.job_id = _job_id
-                print(f"\n📦 render job jobId: {_job_id}")
-            except RuntimeError as e:
-                LogPrint(f"⚠️  failed to save RenderPlan to database (--save-job auto-disabled, rendering continues): {e}", file=sys.stderr)
-                args.save_job = False
+def _print_resolve_only_summary(render_plan: dict) -> int:
 
-    if args.resolve_only:
-        generated = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "generated")
-        failed = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "failed")
-        total = len(render_plan["resolvedAssets"])
-        LogPrint(f"\n📊 Asset resolution finished (resolve-only mode): total {total}, generated {generated}, failed {failed}", file=sys.stderr)
+    generated = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "generated")
+    failed = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "failed")
+    total = len(render_plan["resolvedAssets"])
+    LogPrint(f"\n📊 Asset resolution finished (resolve-only mode): total {total}, generated {generated}, failed {failed}", file=sys.stderr)
 
-        fps = render_plan.get("renderConfig", {}).get("fps", 30)
-        target_dur = render_plan.get("targetDuration")
-        actual_dur = render_plan.get("renderConfig", {}).get("totalDuration", 0)
+    fps = render_plan.get("renderConfig", {}).get("fps", 30)
+    target_dur = render_plan.get("targetDuration")
+    actual_dur = render_plan.get("renderConfig", {}).get("totalDuration", 0)
 
 
-        print(f"\n📊 Asset resolution finished: total {total}, generated {generated}, failed {failed}")
-        if target_dur:
-            diff = actual_dur - target_dur
-            sign = "+" if diff >= 0 else ""
-            print(f"⏱  Actual duration: {actual_dur}s (target {target_dur}s, {sign}{diff:.1f}s)")
-        else:
-            print(f"⏱  Actual duration: {actual_dur}s")
-
-        print(f"\n🎬 Scene timeline:")
-        for entry in render_plan.get("timeline", []):
-            scene_dur = round(entry.get("durationFrames", 0) / fps, 1)
-            scene_id = entry.get("sceneId", "?")
-            print(f"   {scene_id:<25} {scene_dur:>6.1f}s")
-
-        audio_assets = [a for a in render_plan.get("resolvedAssets", [])
-                        if a.get("type") == "audio" and a.get("status") == "generated"]
-        if audio_assets:
-            print(f"\n🔊 TTS audio:")
-            for asset in audio_assets:
-                dur_s = round((asset.get("duration") or 0) / 1000, 1)
-                url = asset.get("url", "")
-                print(f"   {asset['assetId']:<25} {dur_s:>6.1f}s  {url}")
-
-        image_assets = [a for a in render_plan.get("resolvedAssets", [])
-                        if a.get("type") == "image" and a.get("status") == "generated"]
-        if image_assets:
-            print(f"\n🖼  Image assets:")
-            for asset in image_assets:
-                url = asset.get("url", "")
-                print(f"   {asset['assetId']:<25} {url}")
-
-
-
-
-        avatar_assets = [a for a in render_plan.get("resolvedAssets", []) if a.get("type") == "avatar"]
-        avatar_scenes: dict = {}
-        for entry in render_plan.get("timeline", []):
-            ref = (entry.get("props") or {}).get("avatarAssetId")
-            if ref:
-                avatar_scenes.setdefault(ref, []).append(entry.get("sceneId", "?"))
-        if avatar_assets:
-            print(f"\n🧑 Digital-human segments:")
-            for asset in avatar_assets:
-                scenes_on = ", ".join(avatar_scenes.get(asset["assetId"], [])) or "(no scene)"
-                print(f"   {asset['assetId']:<25} {asset.get('status', '?'):<10} scenes: {scenes_on}  {asset.get('url', '')}")
-        else:
-            print(f"\n🧑 Digital-human segments: none (this render has no presenter)")
+    print(f"\n📊 Asset resolution finished: total {total}, generated {generated}, failed {failed}")
+    if target_dur:
+        diff = actual_dur - target_dur
+        sign = "+" if diff >= 0 else ""
+        print(f"⏱  Actual duration: {actual_dur}s (target {target_dur}s, {sign}{diff:.1f}s)")
+    else:
+        print(f"⏱  Actual duration: {actual_dur}s")
+
+    print(f"\n🎬 Scene timeline:")
+    for entry in render_plan.get("timeline", []):
+        scene_dur = round(entry.get("durationFrames", 0) / fps, 1)
+        scene_id = entry.get("sceneId", "?")
+        print(f"   {scene_id:<25} {scene_dur:>6.1f}s")
+
+    audio_assets = [a for a in render_plan.get("resolvedAssets", [])
+                    if a.get("type") == "audio" and a.get("status") == "generated"]
+    if audio_assets:
+        print(f"\n🔊 TTS audio:")
+        for asset in audio_assets:
+            dur_s = round((asset.get("duration") or 0) / 1000, 1)
+            url = asset.get("url", "")
+            print(f"   {asset['assetId']:<25} {dur_s:>6.1f}s  {url}")
+
+    image_assets = [a for a in render_plan.get("resolvedAssets", [])
+                    if a.get("type") == "image" and a.get("status") == "generated"]
+    if image_assets:
+        print(f"\n🖼  Image assets:")
+        for asset in image_assets:
+            url = asset.get("url", "")
+            print(f"   {asset['assetId']:<25} {url}")
 
 
-        if failed > 0:
-            sys.exit(1)
-        return
 
-    if render_plan["status"] == "failed":
-        LogPrint("❌ asset resolution had failures; cannot continue rendering", file=sys.stderr)
-        if not args.save_job:
-            save_json(render_plan, rp_output)
-        sys.exit(1)
+
+    avatar_assets = [a for a in render_plan.get("resolvedAssets", []) if a.get("type") == "avatar"]
+    avatar_scenes: dict = {}
+    for entry in render_plan.get("timeline", []):
+        ref = (entry.get("props") or {}).get("avatarAssetId")
+        if ref:
+            avatar_scenes.setdefault(ref, []).append(entry.get("sceneId", "?"))
+    if avatar_assets:
+        print(f"\n🧑 Digital-human segments:")
+        for asset in avatar_assets:
+            scenes_on = ", ".join(avatar_scenes.get(asset["assetId"], [])) or "(no scene)"
+            print(f"   {asset['assetId']:<25} {asset.get('status', '?'):<10} scenes: {scenes_on}  {asset.get('url', '')}")
+    else:
+        print(f"\n🧑 Digital-human segments: none (this render has no presenter)")
+
+    return failed
+
+
+def _render(render_plan: dict, args, private_token: str, output_path: str) -> tuple[bool, str, str]:
 
     render_mode = args.renderer
     upload_title_hint = (
@@ -3114,6 +3189,75 @@ Examples:
         LogPrint(f"💻 Using local render mode", file=sys.stderr)
         render_plan["renderMode"] = "local"
         success = render_with_local_cli(render_plan, output_path)
+    return success, render_mode, upload_title_hint
+
+
+def _print_remote_playback(render_plan: dict, upload_info: dict, remote_url: str, playback_url: str) -> None:
+
+
+    effective_playback = playback_url or remote_url
+    if effective_playback and not effective_playback.startswith("vod://"):
+        print(f"\n🎬 Video playback URL: {effective_playback}")
+
+
+        if upload_info.get("coverUrl"):
+            print(f"🖼️ Cover image URL: {upload_info['coverUrl']}")
+
+
+
+
+
+
+
+
+
+
+
+
+        asset = {"url": effective_playback}
+        cover = upload_info.get("coverUrl")
+        if cover:
+            asset["coverUrl"] = cover
+        total_duration = (render_plan.get("renderConfig") or {}).get("totalDuration")
+        if isinstance(total_duration, (int, float)) and total_duration > 0:
+            asset["durationSec"] = total_duration
+        print("__render_video_asset__ " + json.dumps(asset, ensure_ascii=False))
+
+
+def _upload_local_render(output_path: str, upload_title_hint: str, manifest: dict, manifest_path: str | None) -> None:
+
+    try:
+        from upload_video import upload_media_file
+
+        upload_title = upload_title_hint
+        LogPrint(f"\n📤 Uploading video to OSS...", file=sys.stderr)
+        upload_result = upload_media_file(
+            file_path=output_path,
+            title=upload_title,
+            role="final_video",
+            retention="output",
+        )
+        manifest["upload"] = {
+            "fileUrl": upload_result["fileUrl"],
+            "title": upload_title,
+            "uploadedAt": now_iso(),
+
+            "fileId": upload_result.get("fileId"),
+        }
+
+        if upload_result.get("fileUrl"):
+            print(f"\n🎬 Video playback URL: {upload_result['fileUrl']}")
+        if manifest_path:
+            save_json(manifest, manifest_path)
+            LogPrint(f"   Manifest updated: {manifest_path}", file=sys.stderr)
+    except Exception as e:
+        LogPrint(f"\n⚠️  upload failed (the video stays local): {e}", file=sys.stderr)
+
+
+def _report_render(
+        render_plan: dict, args, private_token: str, success: bool, render_mode: str,
+        upload_title_hint: str, output_path: str, rp_output: str,
+) -> None:
 
 
     if not args.save_job:
@@ -3145,34 +3289,7 @@ Examples:
             LogPrint(f"   Remote video: {remote_url}", file=sys.stderr)
             if playback_url:
                 LogPrint(f"   Playback URL: {playback_url}", file=sys.stderr)
-
-            effective_playback = playback_url or remote_url
-            if effective_playback and not effective_playback.startswith("vod://"):
-                print(f"\n🎬 Video playback URL: {effective_playback}")
-
-
-                if upload_info.get("coverUrl"):
-                    print(f"🖼️ Cover image URL: {upload_info['coverUrl']}")
-
-
-
-
-
-
-
-
-
-
-
-
-                asset = {"url": effective_playback}
-                cover = upload_info.get("coverUrl")
-                if cover:
-                    asset["coverUrl"] = cover
-                total_duration = (render_plan.get("renderConfig") or {}).get("totalDuration")
-                if isinstance(total_duration, (int, float)) and total_duration > 0:
-                    asset["durationSec"] = total_duration
-                print("__render_video_asset__ " + json.dumps(asset, ensure_ascii=False))
+            _print_remote_playback(render_plan, upload_info, remote_url, playback_url)
         else:
             LogPrint(f"   Video: {output_path}", file=sys.stderr)
         if args.save_job:
@@ -3189,32 +3306,7 @@ Examples:
                 save_json(manifest, manifest_path)
                 LogPrint(f"   Manifest updated (remote fileUrl): {manifest_path}", file=sys.stderr)
         elif args.upload and not args.no_upload:
-            try:
-                from upload_video import upload_media_file
-
-                upload_title = upload_title_hint
-                LogPrint(f"\n📤 Uploading video to OSS...", file=sys.stderr)
-                upload_result = upload_media_file(
-                    file_path=output_path,
-                    title=upload_title,
-                    role="final_video",
-                    retention="output",
-                )
-                manifest["upload"] = {
-                    "fileUrl": upload_result["fileUrl"],
-                    "title": upload_title,
-                    "uploadedAt": now_iso(),
-
-                    "fileId": upload_result.get("fileId"),
-                }
-
-                if upload_result.get("fileUrl"):
-                    print(f"\n🎬 Video playback URL: {upload_result['fileUrl']}")
-                if manifest_path:
-                    save_json(manifest, manifest_path)
-                    LogPrint(f"   Manifest updated: {manifest_path}", file=sys.stderr)
-            except Exception as e:
-                LogPrint(f"\n⚠️  upload failed (the video stays local): {e}", file=sys.stderr)
+            _upload_local_render(output_path, upload_title_hint, manifest, manifest_path)
 
 
         if args.save_job and args.job_id:
@@ -3229,5 +3321,75 @@ Examples:
         sys.exit(1)
 
 
+def main():
+
+    atexit.register(print_billing_footer)
+    args = _build_arg_parser().parse_args()
+
+    private_token = args.priv_token or os.environ.get("PRIV_TOKEN", "")
+
+
+    if args.priv_token:
+        os.environ["PRIV_TOKEN"] = private_token
+
+
+    if args.save_job and not private_token:
+        LogPrint("ℹ️  PRIV_TOKEN not configured; --save-job auto-disabled (will not write to database)", file=sys.stderr)
+        args.save_job = False
+
+    dsl = binding = None
+    if args.job_id is not None and args.job_id > 0:
+        render_plan = _load_plan_from_job(args.job_id, private_token)
+    elif args.render_plan:
+        render_plan = _load_plan_from_file(args.render_plan, args.dsl)
+    else:
+        dsl = _load_dsl(args)
+        _reject_skeleton_dsl(dsl)
+        render_plan, binding = _plan_from_dsl(dsl, args)
+
+    if args.job_id or args.render_plan:
+        _validate_saved_plan(render_plan)
+    _reject_bad_asset_refs(render_plan)
+
+    if not args.skip_asset_resolve:
+        render_plan = _resolve_plan_assets(render_plan, args, private_token)
+
+    render_plan.pop("_dsl_assets", None)
+
+    output_path = os.path.join(OUTPUT_DIR, "video.mp4")
+    rp_output = args.render_plan_output or os.path.join(OUTPUT_DIR, "render-plan.json")
+
+
+    if args.save_render_plan or not args.save_job:
+        validate_and_fix_render_plan(render_plan)
+        save_json(render_plan, rp_output)
+        LogPrint(f"💾 RenderPlan saved: {rp_output}", file=sys.stderr)
+
+
+
+
+    if args.save_job:
+        _persist_render_plan(render_plan, args, private_token, dsl, binding)
+        if not args.save_job and not args.save_render_plan:
+
+
+            save_json(render_plan, rp_output)
+            LogPrint(f"💾 RenderPlan saved: {rp_output}", file=sys.stderr)
+
+    if args.resolve_only:
+        if _print_resolve_only_summary(render_plan) > 0:
+            sys.exit(1)
+        return
+
+    if render_plan["status"] == "failed":
+        LogPrint("❌ asset resolution had failures; cannot continue rendering", file=sys.stderr)
+        if not args.save_job:
+            save_json(render_plan, rp_output)
+        sys.exit(1)
+
+    success, render_mode, upload_title_hint = _render(render_plan, args, private_token, output_path)
+    _report_render(render_plan, args, private_token, success, render_mode, upload_title_hint, output_path, rp_output)
+
+
 if __name__ == "__main__":
     main()