premiere-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{premiere_cli-0.4.2/src/premiere_cli.egg-info → premiere_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: premiere-cli
-Version: 0.4.2
+Version: 0.4.3
 Summary: Drive Adobe Premiere Pro from the command line: a Python CLI plus a bundled CEP bridge panel exposing Premiere's scripting APIs over local HTTP
 License: CC-BY-SA-4.0
 Project-URL: Repository, https://github.com/stefanwebb/premiere-cli

{premiere_cli-0.4.2 → premiere_cli-0.4.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "premiere-cli"
 # Keep in lockstep with premiere_cli.__version__ and PANEL_VERSION in
 # src/premiere_cli/panel/js/main.js.
-version = "0.4.2"
+version = "0.4.3"
 description = "Drive Adobe Premiere Pro from the command line: a Python CLI plus a bundled CEP bridge panel exposing Premiere's scripting APIs over local HTTP"
 readme = "README.md"
 license = {text = "CC-BY-SA-4.0"}

{premiere_cli-0.4.2 → premiere_cli-0.4.3}/src/premiere_cli/__init__.py

@@ -8,4 +8,4 @@ server (port 47823).
 # Kept in lockstep with PANEL_VERSION in panel/js/main.js and the version in
 # pyproject.toml — `premiere-cli doctor` compares the installed panel's
 # version against this one.
-__version__ = "0.4.2"
+__version__ = "0.4.3"

premiere_cli-0.4.3/src/premiere_cli/add_background.py

@@ -0,0 +1,230 @@
+"""Fill spans of a timeline with a looped background clip.
+
+Composed from existing panel commands rather than added as a new one:
+`set-item-in-out` controls how much of the source is placed, and
+`overwrite-clip-at` puts it on the timeline. That reuses
+`overwrite-clip-at`'s verified placement path — including its cleanup of the
+auto-linked audio Premiere silently drops onto an audio track — and needs no
+panel reload.
+
+Which spans to fill is the caller's business: pass them in a cuts-style
+intervals file. The spans a *video project* wants (say, every motion graphic
+with no talking head behind it) come from that project's own script metadata,
+which this package knows nothing about.
+
+**⚠️ A background clip WITH AN AUDIO STREAM will destroy audio underneath it.**
+Placing video via `overwrite-clip-at` makes Premiere auto-link the source's
+audio onto an audio track; that command removes the audio it *added*, but the
+audio it *overwrote* is gone and undo does not work on this build. Observed
+live: filling 9 spans with a 5s h264+aac clip silently blew 221s of holes in
+the dialogue on A1. Before running, either strip the audio from the background
+file, or confirm the audio tracks it would land on are empty. `--dry-run`
+reports the plan; it cannot warn you about this, because the damage happens in
+Premiere, not here.
+"""
+
+from __future__ import annotations
+
+from math import gcd
+from typing import Optional
+
+#: Anything shorter than this many frames is not worth an edit point.
+MIN_PLACEMENT_FRAMES = 1
+
+
+def clip_intervals(
+    intervals: list[dict], start: Optional[float], end: Optional[float]
+) -> list[dict]:
+    """Restrict intervals to [start, end], dropping and truncating as needed."""
+    out = []
+    for interval in intervals:
+        lo, hi = interval["start"], interval["end"]
+        if start is not None:
+            lo = max(lo, start)
+        if end is not None:
+            hi = min(hi, end)
+        if hi > lo:
+            out.append({"start": lo, "end": hi})
+    return out
+
+
+def plan_fill(
+    intervals: list[dict],
+    source_duration: float,
+    fps: float,
+    source_fps: Optional[float] = None,
+) -> list[dict]:
+    """Plan the placements that tile each interval with the source clip.
+
+    The source repeats until the span is full and the final repeat is trimmed,
+    so a span is covered exactly — no gap, no overhang. Every start and length
+    is quantised to a whole frame: at sub-frame precision the repeats drift and
+    leave a one-frame hole between them.
+
+    When the source's frame rate differs from the sequence's, the loop length
+    must be a whole number of frames in **both** grids. Premiere trims the
+    source on the SOURCE's grid, so a length that is whole only on the
+    sequence's grid lands sub-frame on the timeline and gets floored — every
+    repeat comes out a frame short and leaves a hole. A 5.033s 30fps clip on a
+    25fps sequence did exactly that across 43 repeats. The common grid for
+    25 and 30 is 0.2s, so the loop floors to 5.0s and tiles cleanly.
+    """
+    if source_duration <= 0:
+        raise ValueError("source_duration must be positive")
+
+    frame = 1.0 / fps
+    loop_frames = max(1, int(round(source_duration * fps)))
+    if source_fps and abs(source_fps - fps) > 1e-9:
+        # Frames of the sequence grid that are also whole frames of the source's.
+        step = int(round(fps)) // gcd(int(round(fps)), int(round(source_fps)))
+        loop_frames = max(step, (loop_frames // step) * step)
+    placements = []
+    for interval in intervals:
+        start_frame = int(round(interval["start"] * fps))
+        end_frame = int(round(interval["end"] * fps))
+        cursor = start_frame
+        while cursor < end_frame:
+            remaining = end_frame - cursor
+            length = min(loop_frames, remaining)
+            if length < MIN_PLACEMENT_FRAMES:
+                break
+            placements.append(
+                {
+                    "start": round(cursor * frame, 6),
+                    "out": round(length * frame, 6),
+                    "trimmed": length < loop_frames,
+                }
+            )
+            cursor += length
+    return placements
+
+
+def summarise(placements: list[dict]) -> dict:
+    """Counts a caller can report without re-deriving them."""
+    return {
+        "placements": len(placements),
+        "trimmed": sum(1 for p in placements if p["trimmed"]),
+        "total_seconds": round(sum(p["out"] for p in placements), 3),
+    }
+
+
+def run(
+    submit,
+    sequence_name: Optional[str],
+    track_index: int,
+    item_node_id: Optional[str],
+    item_name: Optional[str],
+    intervals: list[dict],
+    start_seconds: Optional[float],
+    end_seconds: Optional[float],
+    source_duration_seconds: Optional[float],
+    fps: Optional[float],
+    dry_run: bool,
+) -> dict:
+    """Resolve the source clip, plan the fill, and place it.
+
+    `submit` is the panel client (command, args) -> response dict, injected so
+    this is testable against a fake panel.
+    """
+    # --- resolve the source item ------------------------------------------
+    node_id = item_node_id
+    if node_id is None:
+        found = submit("search-project-items", {"nameContains": item_name})
+        if not found.get("ok"):
+            return {"ok": False, "error": f"could not search for {item_name!r}: {found.get('error')}"}
+        matches = [
+            i for i in (found["result"].get("items") or [])
+            if i.get("name") == item_name and not i.get("isSequence")
+        ]
+        if not matches:
+            return {"ok": False, "error": f"no project item named {item_name!r}"}
+        if len(matches) > 1:
+            return {
+                "ok": False,
+                "error": f"{len(matches)} project items are named {item_name!r} — pass --item-node-id",
+            }
+        node_id = matches[0]["nodeId"]
+
+    info = submit("get-project-item-info", {"nodeId": node_id})
+    if not info.get("ok"):
+        return {"ok": False, "error": f"could not read the source item: {info.get('error')}"}
+    item = info["result"]
+    original_in = item.get("inPointSeconds") or 0.0
+    original_out = item.get("outPointSeconds")
+    # Premiere trims on the source's own frame grid — see plan_fill.
+    source_fps = item.get("frameRate")
+
+    duration = source_duration_seconds
+    if duration is None:
+        if original_out is None:
+            return {
+                "ok": False,
+                "error": "the source item reports no out point — pass --source-duration-seconds",
+            }
+        duration = original_out - original_in
+    if duration <= 0:
+        return {"ok": False, "error": f"source duration is not positive ({duration})"}
+
+    # --- frame grid: the SEQUENCE's, not the source's ---------------------
+    if fps is None:
+        project = submit("get-project-info", {})
+        if not project.get("ok"):
+            return {"ok": False, "error": f"could not read the project: {project.get('error')}"}
+        sequences = project["result"].get("sequences") or []
+        target = sequence_name or (sequences[0]["name"] if sequences else None)
+        match = next((s for s in sequences if s["name"] == target), None)
+        if match is None:
+            return {"ok": False, "error": f"no sequence named {target!r} is open"}
+        fps = float(match["frameRate"])
+
+    spans = clip_intervals(intervals, start_seconds, end_seconds)
+    placements = plan_fill(spans, duration, fps, source_fps=source_fps)
+    plan = {
+        "sequenceName": sequence_name,
+        "trackIndex": track_index,
+        "itemNodeId": node_id,
+        "sourceDurationSeconds": round(duration, 3),
+        "fps": fps,
+        "sourceFps": source_fps,
+        "spans": len(spans),
+        **summarise(placements),
+    }
+    if dry_run:
+        return {"ok": True, "result": {**plan, "dryRun": True, "placementList": placements}}
+
+    # --- place ------------------------------------------------------------
+    placed, failures = 0, []
+    for p in placements:
+        trim = submit(
+            "set-item-in-out",
+            {"nodeId": node_id, "inSeconds": original_in,
+             "outSeconds": round(original_in + p["out"], 6), "mediaType": 1},
+        )
+        if not trim.get("ok"):
+            failures.append({"start": p["start"], "stage": "set-item-in-out", "error": trim.get("error")})
+            continue
+        put = submit(
+            "overwrite-clip-at",
+            {"itemNodeId": node_id, "trackType": "video", "trackIndex": track_index,
+             "startSeconds": p["start"], "sequenceName": sequence_name},
+        )
+        if put.get("ok"):
+            placed += 1
+        else:
+            failures.append({"start": p["start"], "stage": "overwrite-clip-at", "error": put.get("error")})
+
+    # Leave the source item as we found it — a trimmed out point would silently
+    # shorten every later use of this clip.
+    restored = True
+    if original_out is not None:
+        restore = submit(
+            "set-item-in-out",
+            {"nodeId": node_id, "inSeconds": original_in, "outSeconds": original_out, "mediaType": 1},
+        )
+        restored = bool(restore.get("ok"))
+
+    return {
+        "ok": not failures,
+        "result": {**plan, "placed": placed, "sourceInOutRestored": restored,
+                   "failureCount": len(failures), "failures": failures[:10]},
+    }

{premiere_cli-0.4.2 → premiere_cli-0.4.3}/src/premiere_cli/cli.py

@@ -73,6 +73,12 @@ def _parse_intervals_file(path: str) -> list:
     return intervals
 
 
+def _timecode_to_seconds(timecode: str, fps: float) -> float:
+    """Convert an "MM:SS:FF" timecode to seconds at `fps`."""
+    minutes, seconds, frames = (int(part) for part in timecode.split(":"))
+    return minutes * 60 + seconds + frames / fps
+
+
 def submit_command(command: str, args: dict | None = None, port: int = DEFAULT_PORT) -> dict:
     """POST a command to the Premiere Bridge panel's /command endpoint.
 
@@ -769,6 +775,19 @@ def main() -> None:
         "--item-name", help="Exact name of a PROJECT ITEM to delete the marker from instead of a sequence"
     )
 
+    delete_all_markers_parser = subparsers.add_parser(
+        "delete-all-markers", help="Delete every marker on a sequence or project item"
+    )
+    delete_all_markers_parser.add_argument(
+        "--sequence-name", help="Name of the sequence to clear markers from (default: the currently active sequence)"
+    )
+    delete_all_markers_parser.add_argument(
+        "--node-id", help="Node ID of a PROJECT ITEM to clear markers from instead of a sequence"
+    )
+    delete_all_markers_parser.add_argument(
+        "--item-name", help="Exact name of a PROJECT ITEM to clear markers from instead of a sequence"
+    )
+
     add_marker_to_item_parser = subparsers.add_parser(
         "add-marker-to-project-item", help="Add a source marker to a project item"
     )
@@ -1380,30 +1399,96 @@ def main() -> None:
     set_color_value_parser.add_argument("--blue", type=float, required=True, help="Blue channel, 0-255")
 
     add_transition_parser = subparsers.add_parser(
-        "add-transition", help="Add a video transition to a clip's start or end (QE DOM, disputed signature)"
+        "add-transition", help="Add a video or audio transition to a clip's start or end (QE DOM, disputed signature)"
     )
-    add_transition_parser.add_argument("--track-type", required=True, choices=["video"], help="Track type the clip is on (video only)")
-    add_transition_parser.add_argument("--track-index", type=int, required=True, help="0-based index of the video track")
+    add_transition_parser.add_argument("--track-type", required=True, choices=["video", "audio"], help="Track type the clip is on")
+    add_transition_parser.add_argument("--track-index", type=int, required=True, help="0-based index of the track")
     add_transition_parser.add_argument("--clip-index", type=int, required=True, help="0-based index of the clip on that track")
     add_transition_parser.add_argument("--at-end", required=True, choices=["true", "false"], help="true = apply at the clip's end, false = at its start")
-    add_transition_parser.add_argument("--transition-name", help="Transition name, e.g. 'Cross Dissolve' (omit for the default transition)")
+    add_transition_parser.add_argument("--transition-name", help="Transition name, e.g. 'Cross Dissolve' (video) or 'Constant Power' (audio); omit for the track type's default")
     add_transition_parser.add_argument("--duration-seconds", type=float, help="Transition duration in seconds (default: 1.0)")
     add_transition_parser.add_argument(
         "--sequence-name", help="Name of the sequence to edit (default: the currently active sequence)"
     )
 
     batch_add_transitions_parser = subparsers.add_parser(
-        "batch-add-transitions", help="Add the same transition to every clip on one video track (capped at 100)"
+        "batch-add-transitions", help="Add the same transition to every clip on one video or audio track (capped at 100)"
     )
-    batch_add_transitions_parser.add_argument("--track-type", choices=["video"], help="Track type (video only, default: video)")
-    batch_add_transitions_parser.add_argument("--track-index", type=int, help="0-based index of the video track (default: 0)")
+    batch_add_transitions_parser.add_argument("--track-type", choices=["video", "audio"], help="Track type (default: video)")
+    batch_add_transitions_parser.add_argument("--track-index", type=int, help="0-based index of the track (default: 0)")
     batch_add_transitions_parser.add_argument("--at-end", choices=["true", "false"], help="true = apply at each clip's end (default), false = at its start")
-    batch_add_transitions_parser.add_argument("--transition-name", help="Transition name, e.g. 'Cross Dissolve' (omit for the default transition)")
+    batch_add_transitions_parser.add_argument("--transition-name", help="Transition name, e.g. 'Cross Dissolve' (video) or 'Constant Power' (audio); omit for the track type's default")
     batch_add_transitions_parser.add_argument("--duration-seconds", type=float, help="Transition duration in seconds (default: 1.0)")
     batch_add_transitions_parser.add_argument(
         "--sequence-name", help="Name of the sequence to edit (default: the currently active sequence)"
     )
 
+    sync_assets_parser = subparsers.add_parser(
+        "sync-assets",
+        help="Import every media file under an assets/ tree into matching bins, relinking any item that already has the name",
+    )
+    sync_assets_parser.add_argument(
+        "--assets-dir", required=True,
+        help="the assets/ directory to sync (bins mirror its subdirectories)",
+    )
+    sync_assets_parser.add_argument(
+        "--dry-run", action="store_true", help="report the plan without changing the project"
+    )
+
+    insert_clips_parser = subparsers.add_parser(
+        "insert-clips",
+        help="Place a bin's clips whose names start with an MM-SS-FF timecode onto a track at that time",
+    )
+    insert_clips_parser.add_argument("--bin-path", required=True, help="'/'-separated bin to read")
+    insert_clips_parser.add_argument(
+        "--track-type", choices=["video", "audio"], default="video", help="Track type (default: video)"
+    )
+    insert_clips_parser.add_argument("--track-index", type=int, required=True, help="0-based track index")
+    insert_clips_parser.add_argument(
+        "--fps", type=float, help="Frame rate the timecodes are in (default: the sequence's)"
+    )
+    insert_clips_parser.add_argument(
+        "--sequence-name", help="Name of the sequence to edit (default: the currently active sequence)"
+    )
+    insert_clips_parser.add_argument(
+        "--dry-run", action="store_true", help="report the plan without changing the timeline"
+    )
+
+    add_background_parser = subparsers.add_parser(
+        "add-background",
+        help="Fill given time spans of a video track with a looped background clip, trimming the last repeat",
+    )
+    add_background_parser.add_argument(
+        "--sequence-name", help="Name of the sequence to edit (default: the currently active sequence)"
+    )
+    add_background_parser.add_argument(
+        "--track-index", type=int, required=True, help="0-based index of the video track to fill"
+    )
+    bg_source = add_background_parser.add_mutually_exclusive_group(required=True)
+    bg_source.add_argument("--item-node-id", help="Node ID of the background project item")
+    bg_source.add_argument("--item-name", help="Name of the background project item (must be unique)")
+    add_background_parser.add_argument(
+        "--intervals-file", required=True,
+        help="Cuts-style file of spans to fill, one 'MM:SS:FF - MM:SS:FF' per line. "
+             "Which spans a video needs is the caller's business — see the command's docs.",
+    )
+    add_background_parser.add_argument(
+        "--start-seconds", type=float, help="Only fill at or after this time"
+    )
+    add_background_parser.add_argument(
+        "--end-seconds", type=float, help="Only fill up to this time"
+    )
+    add_background_parser.add_argument(
+        "--source-duration-seconds", type=float,
+        help="Loop length to use (default: the source item's own in/out span)",
+    )
+    add_background_parser.add_argument(
+        "--fps", type=float, help="Frame grid to quantise to (default: the sequence's frame rate)"
+    )
+    add_background_parser.add_argument(
+        "--dry-run", action="store_true", help="Report the planned placements without changing the timeline"
+    )
+
     remove_transition_parser = subparsers.add_parser(
         "remove-transition", help="Remove a transition from a track (standard DOM, disputed remove() arity); lists transitions if the index is out of range"
     )
@@ -2267,6 +2352,72 @@ def main() -> None:
         from premiere_cli import init_project
 
         sys.exit(init_project.init_project(args.project_name, args.series, args.base_dir))
+    if args.subcommand == "sync-assets":
+        from premiere_cli import sync_assets as sync_assets_mod
+
+        response = sync_assets_mod.run(
+            lambda command, command_args: submit_command(command, command_args, port=args.port),
+            args.assets_dir, dry_run=args.dry_run,
+        )
+        print(json.dumps(response, indent=2))
+        sys.exit(0 if response.get("ok") else 1)
+    if args.subcommand == "insert-clips":
+        from premiere_cli import insert_clips as insert_clips_mod
+
+        response = insert_clips_mod.run(
+            lambda command, command_args: submit_command(command, command_args, port=args.port),
+            sequence_name=args.sequence_name,
+            bin_path=args.bin_path,
+            track_type=args.track_type,
+            track_index=args.track_index,
+            fps=args.fps,
+            dry_run=args.dry_run,
+        )
+        print(json.dumps(response, indent=2))
+        sys.exit(0 if response.get("ok") else 1)
+    if args.subcommand == "add-background":
+        from premiere_cli import add_background as add_background_mod
+
+        try:
+            spans = _parse_intervals_file(args.intervals_file)
+        except (OSError, ValueError) as exc:
+            print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+            sys.exit(1)
+        fps_for_parse = args.fps
+        if fps_for_parse is None:
+            probe = submit_command("get-project-info", {}, port=args.port)
+            if not probe.get("ok"):
+                print(json.dumps(probe), file=sys.stderr)
+                sys.exit(1)
+            sequences = probe["result"].get("sequences") or []
+            target = args.sequence_name or (sequences[0]["name"] if sequences else None)
+            match = next((sq for sq in sequences if sq["name"] == target), None)
+            if match is None:
+                print(json.dumps({"ok": False, "error": f"no sequence named {target!r} is open"}), file=sys.stderr)
+                sys.exit(1)
+            fps_for_parse = float(match["frameRate"])
+        seconds = [
+            {
+                "start": _timecode_to_seconds(sp["start"], fps_for_parse),
+                "end": _timecode_to_seconds(sp["end"], fps_for_parse),
+            }
+            for sp in spans
+        ]
+        response = add_background_mod.run(
+            lambda command, command_args: submit_command(command, command_args, port=args.port),
+            sequence_name=args.sequence_name,
+            track_index=args.track_index,
+            item_node_id=args.item_node_id,
+            item_name=args.item_name,
+            intervals=seconds,
+            start_seconds=args.start_seconds,
+            end_seconds=args.end_seconds,
+            source_duration_seconds=args.source_duration_seconds,
+            fps=fps_for_parse,
+            dry_run=args.dry_run,
+        )
+        print(json.dumps(response, indent=2))
+        sys.exit(0 if response.get("ok") else 1)
     if args.subcommand == "desktop-take-screenshot":
         desktop_driver = _load_desktop_driver(args.subcommand)
         sys.exit(desktop_driver.take_screenshot(args.output_path, port=args.port))
@@ -2538,6 +2689,13 @@ def main() -> None:
             "itemName": args.item_name,
         }
         command_args = {k: v for k, v in command_args.items() if v is not None}
+    elif args.subcommand == "delete-all-markers":
+        command_args = {
+            "sequenceName": args.sequence_name,
+            "nodeId": args.node_id,
+            "itemName": args.item_name,
+        }
+        command_args = {k: v for k, v in command_args.items() if v is not None}
     elif args.subcommand == "add-marker-to-project-item":
         if not args.node_id and not args.name:
             parser.error("at least one of --node-id, --name is required")

premiere_cli-0.4.3/src/premiere_cli/insert_clips.py

@@ -0,0 +1,129 @@
+"""Place already-imported clips whose names begin with their insertion time.
+
+A delivered motion graphic is named ``MM-SS-FF - <type> - <description>.mov``,
+where the leading field is where it belongs on the timeline. This reads one
+bin, takes every item whose name starts with such a timecode, and overwrites it
+onto the given track at that time. Items without a leading timecode are skipped
+and named in the report rather than guessed at.
+
+Composed from existing panel commands (``get-bin-contents``,
+``overwrite-clip-at``), so it needs no panel reload.
+
+**A source with an audio stream will destroy audio underneath it.** Premiere
+auto-links a source's audio onto A1 whenever its video is placed, and the
+overwrite takes whatever was there; `-1` does not suppress it on PPro 2026 (see
+PREMIERE_API_NOTES.md). This command therefore snapshots the audio tracks before
+and after and reports if their clip counts changed — it cannot prevent the
+damage, only tell you it happened.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+#: MM-SS-FF at the very start of the name, then a separator.
+_TIMECODE_RE = re.compile(r"^(\d{2})-(\d{2})-(\d{2})(?=[\s._-]|$)")
+
+
+def parse_leading_timecode(name: str, fps: float) -> Optional[float]:
+    """Seconds for a name beginning ``MM-SS-FF``, or None if it does not.
+
+    A frame field at or beyond `fps` is rejected rather than folded into the
+    next second: it means the name was not written against this sequence, and
+    silently placing the clip a second late is worse than skipping it.
+    """
+    match = _TIMECODE_RE.match(name)
+    if not match:
+        return None
+    minutes, seconds, frames = (int(g) for g in match.groups())
+    if frames >= round(fps) or seconds >= 60:
+        return None
+    return minutes * 60 + seconds + frames / fps
+
+
+def plan_inserts(items: list[dict], fps: float) -> tuple[list[dict], list[str]]:
+    """Split a bin's items into a time-ordered placement plan and the skipped."""
+    plan, skipped = [], []
+    for item in items:
+        name = item.get("name") or ""
+        at = parse_leading_timecode(name, fps)
+        if at is None:
+            skipped.append(name)
+            continue
+        plan.append({"name": name, "nodeId": item.get("nodeId"), "startSeconds": round(at, 6)})
+    plan.sort(key=lambda p: p["startSeconds"])
+    return plan, skipped
+
+
+def _audio_snapshot(submit, sequence_name: Optional[str]) -> Optional[list[int]]:
+    args = {"sequenceName": sequence_name} if sequence_name else {}
+    response = submit("get-timeline-summary", args)
+    if not response.get("ok"):
+        return None
+    return [t.get("clipCount") for t in (response["result"].get("audioTracks") or [])]
+
+
+def run(
+    submit,
+    sequence_name: Optional[str],
+    bin_path: str,
+    track_type: str,
+    track_index: int,
+    fps: Optional[float],
+    dry_run: bool,
+) -> dict:
+    """Read `bin_path` and place its timestamped clips onto the track."""
+    if fps is None:
+        project = submit("get-project-info", {})
+        if not project.get("ok"):
+            return {"ok": False, "error": f"could not read the project: {project.get('error')}"}
+        sequences = project["result"].get("sequences") or []
+        target = sequence_name or (sequences[0]["name"] if sequences else None)
+        match = next((s for s in sequences if s["name"] == target), None)
+        if match is None:
+            return {"ok": False, "error": f"no sequence named {target!r} is open"}
+        fps = float(match["frameRate"])
+
+    contents = submit("get-bin-contents", {"binPath": bin_path})
+    if not contents.get("ok"):
+        return {"ok": False, "error": f"could not read bin {bin_path!r}: {contents.get('error')}"}
+    result = contents.get("result") or {}
+    items = result if isinstance(result, list) else result.get("items") or []
+    items = [i for i in items if isinstance(i, dict) and i.get("type") != "BIN"]
+
+    plan, skipped = plan_inserts(items, fps)
+    summary = {
+        "sequenceName": sequence_name, "binPath": bin_path, "trackType": track_type,
+        "trackIndex": track_index, "fps": fps, "found": len(items),
+        "timestamped": len(plan), "skipped": skipped,
+    }
+    if dry_run:
+        return {"ok": True, "result": {**summary, "dryRun": True, "plan": plan}}
+
+    before = _audio_snapshot(submit, sequence_name)
+    placed, failures = 0, []
+    for entry in plan:
+        response = submit("overwrite-clip-at", {
+            "itemNodeId": entry["nodeId"], "trackType": track_type,
+            "trackIndex": track_index, "startSeconds": entry["startSeconds"],
+            "sequenceName": sequence_name,
+        })
+        if response.get("ok"):
+            placed += 1
+        else:
+            failures.append({"name": entry["name"], "startSeconds": entry["startSeconds"],
+                             "error": response.get("error")})
+    after = _audio_snapshot(submit, sequence_name)
+
+    changed = None
+    if before is not None and after is not None:
+        changed = before != after
+
+    return {
+        "ok": not failures,
+        "result": {**summary, "placed": placed,
+                   "audioTracksBefore": before, "audioTracksAfter": after,
+                   "audioTracksChanged": changed,
+                   "failureCount": len(failures), "failures": failures[:10]},
+    }