@optima-chat/optima-agent 0.8.91 → 0.8.93

package/.claude/skills/video-clone/scripts/analyze_source.py

@@ -0,0 +1,113 @@
+"""Phase 1: analyze a source video — ffprobe metadata + scene detection.
+
+Usage:
+    python scripts/analyze_source.py --project <name> --video <path-or-url>
+
+Behavior:
+    1. No gate required. Runs autonomously as part of prep.
+    2. If --video looks like a URL, the caller must download it first; this
+       script operates on a local file path only (downloads are caller's job,
+       because platform parsing is listed in references/url-parsing.md).
+    3. Runs ffprobe to extract duration, resolution, fps, codec info.
+    4. Runs ffmpeg scene detection with select='gt(scene,0.3)' and reports
+       cut count → single or multi-segment classification.
+    5. Writes analysis to <project>/source/analysis.json (versioned).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+
+from _project import resolve_project, next_version, append_log
+
+
+def _ffprobe(video: Path) -> dict:
+    r = subprocess.run(
+        ["ffprobe", "-v", "quiet", "-print_format", "json",
+         "-show_format", "-show_streams", str(video)],
+        capture_output=True, text=True, check=True,
+    )
+    return json.loads(r.stdout)
+
+
+def _scene_detect(video: Path) -> list[float]:
+    """Return list of scene-change timestamps (seconds)."""
+    r = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-i", str(video),
+         "-vf", "select='gt(scene,0.3)',showinfo",
+         "-vsync", "vfr", "-f", "null", "-"],
+        capture_output=True, text=True,
+    )
+    # scene-change info shows up on stderr
+    return [float(m.group(1)) for m in re.finditer(r"pts_time:(\d+\.?\d*)", r.stderr)]
+
+
+def _parse_fps(rate: str | None) -> float | None:
+    """Parse ffprobe avg_frame_rate ('30000/1001') into a float, safely.
+
+    Replaces the old eval()-based parsing. Returns None for malformed input
+    instead of raising.
+    """
+    if not rate:
+        return None
+    try:
+        return float(Fraction(rate))
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def _summarize(meta: dict) -> dict:
+    fmt = meta.get("format", {})
+    streams = meta.get("streams", [])
+    vstream = next((s for s in streams if s.get("codec_type") == "video"), {})
+    astream = next((s for s in streams if s.get("codec_type") == "audio"), {})
+    return {
+        "duration_s": float(fmt.get("duration", 0)),
+        "width": vstream.get("width"),
+        "height": vstream.get("height"),
+        "fps": _parse_fps(vstream.get("avg_frame_rate")) if vstream else None,
+        "vcodec": vstream.get("codec_name"),
+        "has_audio": bool(astream),
+        "acodec": astream.get("codec_name"),
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    ap.add_argument("--video", required=True, help="local path to source video")
+    args = ap.parse_args()
+
+    project_dir = resolve_project(args.project)
+
+    video = Path(args.video)
+    if not video.is_file():
+        print(f"ERROR: video not found at {video}", file=sys.stderr)
+        return 1
+
+    print(f"Analyzing {video} …")
+    meta = _ffprobe(video)
+    summary = _summarize(meta)
+    cuts = _scene_detect(video)
+    cuts_significant = [t for t in cuts if t > 0.5]
+    segment_count = 1 if len(cuts_significant) <= 1 else len(cuts_significant) + 1
+
+    summary["scene_cuts"] = cuts_significant
+    summary["segments"] = segment_count
+    summary["classification"] = "multi" if segment_count >= 2 else "single"
+
+    out = next_version(project_dir / "source", "analysis_", ".json")
+    out.write_text(json.dumps(summary, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps(summary, indent=2, ensure_ascii=False))
+    print(f"\nWrote: {out}")
+    append_log(project_dir, f"analysis_completed → {out.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/analyze_source_test.py

@@ -0,0 +1,52 @@
+"""Unit tests for analyze_source._parse_fps — verifies the eval()→Fraction migration (R3)."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+from analyze_source import _parse_fps  # noqa: E402
+
+
+def test_parse_fps_30000_over_1001():
+    result = _parse_fps("30000/1001")
+    assert result is not None
+    assert abs(result - 29.97002997) < 1e-6
+    print("PASS test_parse_fps_30000_over_1001")
+
+
+def test_parse_fps_30_over_1():
+    assert _parse_fps("30/1") == 30.0
+    print("PASS test_parse_fps_30_over_1")
+
+
+def test_parse_fps_zero_over_zero():
+    assert _parse_fps("0/0") is None
+    print("PASS test_parse_fps_zero_over_zero")
+
+
+def test_parse_fps_garbage():
+    assert _parse_fps("abc") is None
+    print("PASS test_parse_fps_garbage")
+
+
+def test_parse_fps_none():
+    assert _parse_fps(None) is None
+    print("PASS test_parse_fps_none")
+
+
+def test_parse_fps_empty():
+    assert _parse_fps("") is None
+    print("PASS test_parse_fps_empty")
+
+
+if __name__ == "__main__":
+    test_parse_fps_30000_over_1001()
+    test_parse_fps_30_over_1()
+    test_parse_fps_zero_over_zero()
+    test_parse_fps_garbage()
+    test_parse_fps_none()
+    test_parse_fps_empty()
+    print("\nAll 6 _parse_fps tests passed.")

package/.claude/skills/video-clone/scripts/assemble.py

@@ -0,0 +1,106 @@
+"""Phase 4: post-process and assemble the final video.
+
+Usage:
+    # single-segment — normalize only
+    python scripts/assemble.py --project <name> --single videos/video_v1_10s.mp4
+
+    # multi-segment — normalize each + concat
+    python scripts/assemble.py --project <name> \
+        --multi videos/scene1_v1_5s.mp4 videos/scene2_v1_5s.mp4
+
+Writes to <project>/videos/final_v{N}.mp4 (versioned).
+
+No gate: post-processing always runs on already-generated videos, which by
+definition must have passed the preview_confirmed gate.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from _project import resolve_project, next_version, append_log
+
+
+def _normalize_single(video: Path, out: Path) -> None:
+    subprocess.run(
+        ["ffmpeg", "-y", "-i", str(video),
+         "-r", "30", "-c:v", "libx264", "-crf", "18",
+         "-c:a", "aac", "-b:a", "192k",
+         str(out)],
+        check=True,
+    )
+
+
+def _normalize_clip(video: Path, out: Path) -> None:
+    subprocess.run(
+        ["ffmpeg", "-y", "-i", str(video),
+         "-vf", "scale=720:1280", "-r", "30",
+         "-c:v", "libx264", "-crf", "18",
+         "-c:a", "aac", "-b:a", "128k",
+         str(out)],
+        check=True,
+    )
+
+
+def _concat(norm_clips: list[Path], out: Path, workdir: Path) -> None:
+    concat_list = workdir / "concat_list.txt"
+    concat_list.write_text(
+        "\n".join(f"file '{p.name}'" for p in norm_clips) + "\n",
+        encoding="utf-8",
+    )
+    subprocess.run(
+        ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+         "-i", str(concat_list),
+         "-c:v", "libx264", "-crf", "18",
+         "-c:a", "aac", "-b:a", "192k",
+         str(out)],
+        check=True, cwd=workdir,
+    )
+    concat_list.unlink(missing_ok=True)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    group = ap.add_mutually_exclusive_group(required=True)
+    group.add_argument("--single", help="single video to normalize")
+    group.add_argument("--multi", nargs="+", help="2+ videos to normalize and concat")
+    args = ap.parse_args()
+
+    project_dir = resolve_project(args.project)
+    videos_dir = project_dir / "videos"
+    out = next_version(videos_dir, "final_", ".mp4")
+
+    if args.single:
+        src = Path(args.single)
+        if not src.is_absolute():
+            src = project_dir / args.single
+        if not src.is_file():
+            print(f"ERROR: {src} not found", file=sys.stderr)
+            return 1
+        _normalize_single(src, out)
+    else:
+        norm_clips = []
+        for i, clip in enumerate(args.multi, 1):
+            src = Path(clip)
+            if not src.is_absolute():
+                src = project_dir / clip
+            if not src.is_file():
+                print(f"ERROR: {src} not found", file=sys.stderr)
+                return 1
+            norm = videos_dir / f"_norm_{i}.mp4"
+            _normalize_clip(src, norm)
+            norm_clips.append(norm)
+        _concat(norm_clips, out, videos_dir)
+        for n in norm_clips:
+            n.unlink(missing_ok=True)
+
+    print(f"\nFinal video: {out}")
+    append_log(project_dir, f"assembled → {out.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/confirm.py

@@ -0,0 +1,12 @@
+"""Entry point: record user confirmation for preview_confirmed.
+
+Usage:
+    python scripts/confirm.py --project <name> --quote "<verbatim user words>"
+
+The actual logic lives in _confirm.run_confirm().
+"""
+import sys
+from _confirm import run_confirm
+
+if __name__ == "__main__":
+    sys.exit(run_confirm())

package/.claude/skills/video-clone/scripts/edit_first_frame.py

@@ -0,0 +1,66 @@
+"""Phase 2: edit the first frame — swap product via gen image.
+
+Usage:
+    python scripts/edit_first_frame.py --project <name> --frame <path> \
+        --product <path> --prompt "<instruction>" [--seed <int>]
+
+Behavior:
+    - No gate required. Runs autonomously as part of prep.
+    - Invokes `gen image -i <frame> -i <product>` with the given prompt.
+    - Writes output to <project>/frames/frame_v{N}.png (versioned, never
+      overwrites).
+    - Prints the output path so the caller can show it to the user in
+      the preview bundle.
+
+The --prompt argument is the *image edit instruction* (e.g. "swap the coffee
+cup on the table for this water bottle, match lighting"), not the motion
+prompt used for video generation.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from _project import resolve_project, next_version, append_log
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    ap.add_argument("--frame", required=True, help="source frame image")
+    ap.add_argument("--product", required=True, help="product reference image")
+    ap.add_argument("--prompt", required=True, help="image edit instruction")
+    ap.add_argument("--seed", type=int, default=None)
+    args = ap.parse_args()
+
+    project_dir = resolve_project(args.project)
+
+    frame = Path(args.frame)
+    product = Path(args.product)
+    for p, label in ((frame, "frame"), (product, "product")):
+        if not p.is_file():
+            print(f"ERROR: {label} not found at {p}", file=sys.stderr)
+            return 1
+
+    out = next_version(project_dir / "frames", "frame_", ".png")
+    cmd = ["gen", "image", "-i", str(frame), "-i", str(product),
+           "-o", str(out), "-p", args.prompt]
+    if args.seed is not None:
+        cmd += ["--seed", str(args.seed)]
+
+    print(f"Running: {' '.join(cmd)}")
+    r = subprocess.run(cmd)
+    if r.returncode != 0:
+        print(f"ERROR: gen image failed with exit {r.returncode}", file=sys.stderr)
+        return r.returncode
+
+    print(f"\nEdited frame: {out}")
+    print("This frame will be included in the preview bundle.")
+    append_log(project_dir, f"first_frame_edited → {out.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/extract_frames.py

@@ -0,0 +1,108 @@
+"""Phase 1: extract equidistant frames from a video for Claude Opus analysis.
+
+Usage:
+    python scripts/extract_frames.py --project <name> --video <path> [--count 10] [--grid]
+
+Behavior:
+    - No gate required. Runs autonomously as part of prep.
+    - Extracts N equidistant frames to <project>/frames/extract_vN/ via ffmpeg.
+    - If --grid is passed, additionally stitches frames into a 5×2 (or 3×4)
+      contact sheet with ffmpeg's tile filter — this is what Claude Opus
+      reads for frame-by-frame analysis.
+
+The frame set is the input to Phase 1 prompt generation. Each call creates a
+new versioned subdirectory so earlier extractions are preserved.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from _project import resolve_project, next_version, append_log
+
+
+def _duration(video: Path) -> float:
+    r = subprocess.run(
+        ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",
+         "-of", "default=noprint_wrappers=1:nokey=1", str(video)],
+        capture_output=True, text=True, check=True,
+    )
+    return float(r.stdout.strip())
+
+
+def _extract_at(video: Path, t: float, out: Path) -> None:
+    subprocess.run(
+        ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
+         "-ss", f"{t:.2f}", "-i", str(video),
+         "-frames:v", "1", "-q:v", "2", str(out)],
+        check=True,
+    )
+
+
+def _tile(frames: list[Path], out: Path, cols: int, rows: int) -> None:
+    # use ffmpeg concat + tile to build a contact sheet
+    # write a temp concat list of still images
+    concat = out.parent / "_concat.txt"
+    concat.write_text(
+        "\n".join(f"file '{p.as_posix()}'\nduration 0.04" for p in frames)
+        + f"\nfile '{frames[-1].as_posix()}'\n",
+        encoding="utf-8",
+    )
+    subprocess.run(
+        ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
+         "-f", "concat", "-safe", "0", "-i", str(concat),
+         "-vf", f"tile={cols}x{rows}", "-frames:v", "1", str(out)],
+        check=True,
+    )
+    concat.unlink(missing_ok=True)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    ap.add_argument("--video", required=True)
+    ap.add_argument("--count", type=int, default=10)
+    ap.add_argument("--grid", action="store_true")
+    args = ap.parse_args()
+
+    project_dir = resolve_project(args.project)
+
+    video = Path(args.video)
+    if not video.is_file():
+        print(f"ERROR: video not found at {video}", file=sys.stderr)
+        return 1
+
+    dur = _duration(video)
+    if dur <= 0:
+        print(f"ERROR: could not read duration from {video}", file=sys.stderr)
+        return 1
+
+    frames_root = project_dir / "frames"
+    out_dir = next_version(frames_root, "extract_", "")
+    out_dir.mkdir(parents=True)
+
+    step = dur / (args.count + 1)
+    frames = []
+    for i in range(1, args.count + 1):
+        t = step * i
+        p = out_dir / f"frame_{i:02d}_t{t:.2f}s.jpg"
+        _extract_at(video, t, p)
+        frames.append(p)
+        print(f"  extracted t={t:.2f}s → {p.name}")
+
+    if args.grid and frames:
+        cols = 5 if args.count % 5 == 0 else 4
+        rows = (args.count + cols - 1) // cols
+        grid_out = out_dir / "grid.jpg"
+        _tile(frames, grid_out, cols, rows)
+        print(f"\nGrid: {grid_out}")
+
+    print(f"\nExtracted {len(frames)} frames to {out_dir}")
+    append_log(project_dir, f"frames_extracted → {out_dir.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/gen_video.py

@@ -0,0 +1,59 @@
+"""Phase 3 (no-audio path): generate video via `gen video` (Wan 2.6 I2V).
+
+Usage:
+    python scripts/gen_video.py --project <name> --frame <path> \
+        [--duration 10]
+
+Use this instead of kling_generate.py when the video does NOT need audio /
+lip sync (cost ~$0.02 vs ~$1). Prompt is read from <project>/prompt.md.
+
+Gate: requires preview_confirmed.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from _gate import require_gate
+from _project import resolve_project, next_version, append_log
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--project", required=True)
+    ap.add_argument("--frame", required=True)
+    ap.add_argument("--duration", type=int, default=10, choices=[5, 10])
+    args = ap.parse_args()
+
+    project_dir = resolve_project(args.project)
+    require_gate(project_dir, "preview_confirmed")
+
+    frame = Path(args.frame)
+    if not frame.is_file():
+        print(f"ERROR: frame not found at {frame}", file=sys.stderr)
+        return 1
+
+    prompt_path = project_dir / "prompt.md"
+    if not prompt_path.is_file():
+        print(f"ERROR: {prompt_path} missing. Write prompt.md first.", file=sys.stderr)
+        return 1
+    prompt = prompt_path.read_text(encoding="utf-8").strip()
+
+    out = next_version(project_dir / "videos", f"video_{args.duration}s_", ".mp4")
+    cmd = ["gen", "video", "-i", str(frame), "-o", str(out),
+           "-p", prompt, "--duration", str(args.duration)]
+    print(f"Running: {' '.join(cmd[:4])} … (prompt trimmed)")
+    r = subprocess.run(cmd)
+    if r.returncode != 0:
+        print(f"ERROR: gen video failed with exit {r.returncode}", file=sys.stderr)
+        return r.returncode
+
+    print(f"\nDone: {out}")
+    append_log(project_dir, f"video_generated_silent → {out.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/init_project.py

@@ -0,0 +1,103 @@
+"""Initialize a new video-clone project directory + phase state.
+
+Usage:
+    python scripts/init_project.py --name <project-name> --task-type video_clone
+    python scripts/init_project.py --name <project-name> --task-type video_gen
+
+Creates:
+    <gen-output>/video-clone/<name>/
+        source/
+        frames/
+        videos/
+        .state/phase.json   (copied from assets/phase-state-template.json)
+
+By default <gen-output> is `./gen-output`. Override with GEN_OUTPUT_ROOT env.
+
+Refuses to overwrite an existing project directory — pick a new name or
+bump a version suffix (e.g. handheld-phone-swap-v2).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+VALID_TASK_TYPES = ("video_clone", "video_gen")
+
+SKILL_ROOT = Path(__file__).parent.parent
+TEMPLATE = SKILL_ROOT / "assets" / "phase-state-template.json"
+
+
+def _gen_output_root() -> Path:
+    override = os.environ.get("GEN_OUTPUT_ROOT")
+    if override:
+        return Path(override)
+    return Path.cwd() / "gen-output"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Initialize a video-clone project.")
+    ap.add_argument("--name", required=True, help="Project name (slug).")
+    ap.add_argument(
+        "--task-type",
+        required=True,
+        choices=VALID_TASK_TYPES,
+        help="video_clone or video_gen",
+    )
+    args = ap.parse_args()
+
+    if not TEMPLATE.is_file():
+        print(f"ERROR: state template missing at {TEMPLATE}", file=sys.stderr)
+        return 1
+
+    base = _gen_output_root() / "video-clone" / args.name
+    if base.exists():
+        print(
+            f"ERROR: project already exists at {base}\n"
+            f"Pick a new name or bump a version suffix (e.g. {args.name}-v2).",
+            file=sys.stderr,
+        )
+        return 1
+
+    for sub in ("source", "frames", "videos", ".state"):
+        (base / sub).mkdir(parents=True)
+
+    state = json.loads(TEMPLATE.read_text(encoding="utf-8"))
+    state["project"] = args.name
+    state["task_type"] = args.task_type
+    state["created_at"] = _now_iso()
+    state["history"].append({"event": "project_created", "at": state["created_at"]})
+
+    (base / ".state" / "phase.json").write_text(
+        json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8"
+    )
+
+    print(f"Created project: {base}")
+    print(f"  phase state: {base / '.state' / 'phase.json'}")
+    print()
+    print("Next steps:")
+    print("  1. (Phase 0 sanity check) Tell the user one sentence describing your")
+    print("     understanding of the task and reference workflow. Wait for 'yes'.")
+    print("  2. Run prep autonomously: analyze_source → extract_frames → write")
+    print("     prompt.md → edit_first_frame → write cost.json → preview.py")
+    print(f"  3. Show preview to user, then run:")
+    print(
+        f"       python scripts/confirm.py --project {args.name} "
+        f"--quote \"<user's actual confirmation>\""
+    )
+    print(f"  4. Run kling_generate.py / gen_video.py → assemble.py")
+    print()
+    print(f"At any time, check status:")
+    print(f"       python scripts/status.py --project {args.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())