Skip to content

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

Add BMTS-Lite fast beat montage route (#753)

sharbvanef4ac4a7db670
diff --git a/docs/bgm-montage-lite.md b/docs/bgm-montage-lite.md
new file mode 100644
index 00000000..5d3e6149
--- /dev/null
+++ b/docs/bgm-montage-lite.md
@@ -0,0 +1,64 @@
+# BGM Montage Lite
+
+BMTS-Lite is OpenMontage's fast, local, audio-led montage route. It accepts one music file and one or more supplied video clips, analyzes the complete track, plans beat/phrase-aware cuts, reuses clips when needed, adapts the output frame to the selected or majority-detected aspect ratio, and renders an MP4. It does not require a reference video or API key.
+
+## Choose the right mode
+
+| Mode | Best for | Required media | Selection and review |
+| --- | --- | --- | --- |
+| **BMTS-Lite** (`bgm_montage_lite`) | Fast, full-song beat montage from footage the user already chose | One audio file and 1–100 video clips | Random, balanced reuse; automatic aspect ratio; no semantic selection or tool-specific agent visual review |
+| **BGM Montage** (separate integration in [PR #751](https://github.com/calesthio/OpenMontage/pull/751)) | Professional reference-guided edit with style analysis and stricter source selection | Audio, reference video, and source-footage library | Reference-style analysis, intelligent selection, renderer QA, and the full integration's review gates |
+
+The Lite tool deliberately calls BMTS-Lite's existing `worker.run()` and `engine/` modules. It does not copy that engine into OpenMontage or route through the BGM Montage full workflow. Its existing random assignment, 12-shot render batches, full-track audio mux, automatic aspect-ratio vote, and blur-fill framing are preserved.
+
+## Install the optional local runtime
+
+The integration keeps BMTS-Lite dependencies outside OpenMontage's main Python environment. Use a clean BMTS-Lite checkout and a dedicated Python 3.11 environment:
+
+```powershell
+git clone https://github.com/sharbvane/BMTS-Lite.git
+cd BMTS-Lite
+py -3.11 -m venv .venv-openmontage
+.\.venv-openmontage\Scripts\python.exe -m pip install -r requirements-runtime.txt
+$env:BGM_MONTAGE_LITE_ROOT = (Get-Location).Path
+$env:BGM_MONTAGE_LITE_PYTHON = (Resolve-Path .\.venv-openmontage\Scripts\python.exe).Path
+```
+
+Install FFmpeg (including `ffprobe`) on `PATH`. On macOS/Linux, create the virtual environment with `python3.11 -m venv .venv-openmontage`, install the same requirements file, and export the two variables to the checkout and environment interpreter paths.
+
+No network access or API credentials are used during a montage run. The tool reports as unavailable until the source checkout, runtime packages, FFmpeg, and ffprobe are present.
+
+## Call from the cinematic compose stage
+
+The tool is an optional `video_post` capability in the cinematic pipeline's compose stage. Choose it only for an uncomplicated, full-song music montage without reference matching, narration, titles, or semantic clip selection. Keep the existing video-compose route for authored compositions, mixed media, and the professional reference-guided workflow.
+
+```python
+from tools.tool_registry import registry
+
+registry.discover()
+result = registry.get("bgm_montage_lite").execute({
+ "audio_path": "project/assets/music.mp3",
+ "video_paths": [
+ "project/assets/clip-01.mp4",
+ "project/assets/clip-02.mp4",
+ "project/assets/clip-03.mp4",
+ ],
+ "project_dir": "project",
+ "aspect_ratio": "auto",
+})
+if not result.success:
+ raise RuntimeError(result.error)
+print(result.data["output_path"])
+```
+
+Supported explicit aspect ratios are `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, and `4:5`; `auto` selects the closest supported ratio to the majority of source clips. Mismatched clips retain their full frame in the existing blur-fill treatment. The full audio is never silently shortened: BMTS-Lite accepts music tracks from 1 second through 10 minutes and fails outside that range.
+
+The tool returns three OpenMontage artifacts: the MP4, `*.timeline.json`, and `*.audiomap.json`. The render report includes probed codec, dimensions, frame rate, duration, file size, and the renderer's full-decode verification. Outputs are never overwritten; choose a new `output_path` if any of the three files already exists.
+
+## End-to-end verification
+
+On 2026-10-09, the OpenMontage tool adapter rendered a local 21.768-second music track with five local video clips and no reference video or API key. It produced a 33-shot, 1920×1080 H.264/AAC MP4; the output audio stream covered the full 21.768-second track. BMTS-Lite detected 45 beats: cut boundaries had a 62.8 ms mean and 250.9 ms maximum distance to the nearest detected beat, with 78.1% within 120 ms (the remainder include half-beat/phrase cuts). All five clips were reused 6–7 times at varying source offsets, and the renderer plus an independent FFmpeg full-decode check succeeded. The source media and rendered files are local test inputs/outputs and are intentionally not redistributed with this project.
+
+## Licensing and attribution
+
+BMTS-Lite source at the current main revision and later is licensed under AGPL-3.0-only, copyright © 2026 Cui (sharbvane). Historical snapshots retain the license that accompanied them. No BMTS-Lite engine source or third-party media is vendored in this OpenMontage contribution. See [BMTS-Lite](https://github.com/sharbvane/BMTS-Lite) and its [`requirements-runtime.txt`](https://github.com/sharbvane/BMTS-Lite/blob/main/requirements-runtime.txt) for the separately installed engine and runtime dependencies.
diff --git a/pipeline_defs/cinematic.yaml b/pipeline_defs/cinematic.yaml
index 23f44201..d5c74130 100644
--- a/pipeline_defs/cinematic.yaml
+++ b/pipeline_defs/cinematic.yaml
@@ -244,6 +244,7 @@ stages:
- video_trimmer
- color_grade
- audio_enhance
+ - bgm_montage_lite
tools_available:
- video_compose
- hyperframes_compose
@@ -252,6 +253,7 @@ stages:
- video_trimmer
- color_grade
- audio_enhance
+ - bgm_montage_lite
checkpoint_required: true
human_approval_default: false
review_focus:
diff --git a/schemas/tools/bgm_montage_lite.schema.json b/schemas/tools/bgm_montage_lite.schema.json
new file mode 100644
index 00000000..74a0ebdb
--- /dev/null
+++ b/schemas/tools/bgm_montage_lite.schema.json
@@ -0,0 +1,30 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "openmontage/tools/bgm_montage_lite",
+ "title": "BGM Montage Lite",
+ "description": "Create a reference-free, full-song beat montage from one audio file and supplied video clips.",
+ "type": "object",
+ "required": ["audio_path", "video_paths"],
+ "properties": {
+ "audio_path": {"type": "string", "minLength": 1},
+ "video_paths": {
+ "type": "array",
+ "items": {"type": "string", "minLength": 1},
+ "minItems": 1,
+ "maxItems": 100
+ },
+ "aspect_ratio": {
+ "type": "string",
+ "enum": ["auto", "16:9", "9:16", "4:3", "3:4", "1:1", "4:5"],
+ "default": "auto"
+ },
+ "project_dir": {
+ "type": "string",
+ "description": "Optional OpenMontage project root; defaults output to its renders folder."
+ },
+ "output_path": {
+ "type": "string",
+ "description": "Optional MP4 destination; defaults beside the music file or under project_dir/renders."
+ }
+ }
+}
diff --git a/skills/pipelines/cinematic/compose-director.md b/skills/pipelines/cinematic/compose-director.md
index 9bf349a8..705cfe95 100644
--- a/skills/pipelines/cinematic/compose-director.md
+++ b/skills/pipelines/cinematic/compose-director.md
@@ -16,6 +16,24 @@ For a Blender world film, FFmpeg is the approved packager for the numbered
Blender image sequence and audio. It must not synthesize camera motion or replace
missing Blender frames with pan/zoom effects.
+### Fast Full-Song Beat Montage (BMTS-Lite)
+
+When the approved brief calls for a quick montage from one supplied music track
+and already-selected video clips—with no reference matching, narration, titles,
+or semantic clip selection—use `bgm_montage_lite` as the complete render path.
+Pass the source audio, all intended source clips, the project directory, and the
+requested aspect ratio (`auto` by default). The tool returns the MP4, timeline,
+audiomap, and an OpenMontage render report after stream, dimension, duration,
+and full-decode checks.
+
+This is distinct from the professional reference-guided BGM Montage integration:
+Lite does not need a reference video or API key and intentionally retains BMTS-Lite
+source reuse and automatic framing. Do not add semantic selection, strict reuse
+limits, Agent visual-review dependencies, or a second rendering engine to this
+route. Use the existing composition runtimes for authored scenes and mixed-media
+work; the professional BGM Montage route remains the choice for reference-style
+matching and its stricter quality gates.
+
`delivery_promise.motion_required=true` means the locked runtime is a commitment. Silent swap to another runtime (including FFmpeg Ken Burns) is a CRITICAL governance violation. If the locked runtime fails, escalate per AGENT_GUIDE.md > "Escalate Blockers Explicitly."
**Pass `proposal_packet` to `video_compose.execute()`** so the tool's `runtime_swap_detected` check compares directly against `proposal_packet.production_plan.render_runtime`. Without it the swap check is skipped in-tool and only the reviewer skill catches the drift.
diff --git a/tests/tools/test_bmts_lite.py b/tests/tools/test_bmts_lite.py
new file mode 100644
index 00000000..fd40ae91
--- /dev/null
+++ b/tests/tools/test_bmts_lite.py
@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from unittest.mock import patch
+
+from jsonschema import validate
+
+from lib.pipeline_loader import load_pipeline
+from schemas.artifacts import validate_artifact
+from tools.tool_registry import registry
+from tools.video.bmts_lite import BgmMontageLite
+
+
+def _inputs(tmp_path: Path, output: Path) -> dict:
+ audio = tmp_path / "music.mp3"
+ clips = [tmp_path / "clip-a.mp4", tmp_path / "clip-b.mp4"]
+ audio.write_bytes(b"audio fixture")
+ for clip in clips:
+ clip.write_bytes(b"video fixture")
+ return {
+ "audio_path": str(audio),
+ "video_paths": [str(path) for path in clips],
+ "output_path": str(output),
+ "aspect_ratio": "auto",
+ }
+
+
+def test_schema_and_registry_expose_a_reference_free_local_tool() -> None:
+ tool = BgmMontageLite()
+ schema_path = Path(__file__).resolve().parents[2] / "schemas" / "tools" / "bgm_montage_lite.schema.json"
+
+ schema = json.loads(schema_path.read_text(encoding="utf-8"))
+ assert tool.input_schema["properties"] == schema["properties"]
+ assert tool.input_schema["required"] == schema["required"]
+ assert "reference_video" not in tool.input_schema["properties"]
+ assert tool.supports["reference_video_required"] is False
+ assert tool.supports["api_key_required"] is False
+
+ registry.discover()
+ assert registry.get("bgm_montage_lite") is not None
+
+
+def test_cinematic_compose_advertises_lite_as_an_optional_route() -> None:
+ manifest = load_pipeline("cinematic")
+ compose = next(stage for stage in manifest["stages"] if stage["name"] == "compose")
+
+ assert "bgm_montage_lite" in compose["optional_tools"]
+ assert "bgm_montage_lite" in compose["tools_available"]
+ assert "bgm_montage_lite" not in compose["required_tools"]
+ assert "video_compose" in compose["required_tools"]
+
+
+def test_run_emits_mp4_timeline_audiomap_and_openmontage_report(tmp_path: Path) -> None:
+ tool = BgmMontageLite()
+ output = tmp_path / "renders" / "montage.mp4"
+ inputs = _inputs(tmp_path, output)
+ engine = tmp_path / "engine"
+ engine.mkdir()
+ for name in ("worker.py", "analyze_bgm.py", "timeline_planner.py", "montage.py", "visual_intelligence.py"):
+ target = tmp_path / name if name == "worker.py" else engine / name
+ target.write_text("", encoding="utf-8")
+ seen_request: dict = {}
+
+ def fake_run(command: list[str], *, timeout: int | None = None, cwd: Path | None = None):
+ if "--request" in command:
+ request_path = Path(command[command.index("--request") + 1])
+ workspace = Path(command[command.index("--workspace") + 1])
+ seen_request.update(json.loads(request_path.read_text(encoding="utf-8")))
+ (workspace / "result.mp4").write_bytes(b"rendered mp4")
+ (workspace / "timeline.json").write_text('{"shots":[]}', encoding="utf-8")
+ (workspace / "audiomap.json").write_text('{"beats":[]}', encoding="utf-8")
+ return subprocess.CompletedProcess(command, 0, '{"duration":2.0,"ratio":"16:9","shots":3}', "")
+
+ return subprocess.CompletedProcess(
+ command,
+ 0,
+ json.dumps(
+ {
+ "format": {"duration": "2.0", "format_name": "mov,mp4"},
+ "streams": [
+ {"codec_type": "video", "codec_name": "h264", "width": 1920, "height": 1080, "avg_frame_rate": "30/1"},
+ {"codec_type": "audio", "codec_name": "aac"},
+ ],
+ }
+ ),
+ "",
+ )
+
+ with (
+ patch.dict("os.environ", {"BGM_MONTAGE_LITE_ROOT": str(tmp_path), "BGM_MONTAGE_LITE_PYTHON": "python"}),
+ patch.object(tool, "check_dependencies"),
+ patch.object(tool, "run_command", side_effect=fake_run),
+ ):
+ result = tool.execute(inputs)
+
+ assert result.success, result.error
+ assert result.data["aspect_ratio"] == "16:9"
+ assert result.data["shot_count"] == 3
+ assert result.data["render_report"]["outputs"][0]["resolution"] == "1920x1080"
+ validate(instance=result.data, schema=tool.output_schema)
+ validate_artifact("render_report", result.data["render_report"])
+ assert [Path(path).name for path in result.artifacts] == [
+ "montage.mp4",
+ "montage.timeline.json",
+ "montage.audiomap.json",
+ ]
+ assert all(Path(path).is_file() for path in result.artifacts)
+ assert seen_request["ratio"] == "auto"
+ assert seen_request["media"][-1]["file"] == str(Path(inputs["audio_path"]).resolve())
+ assert len(seen_request["media"]) == 3
+
+
+def test_existing_output_is_never_overwritten(tmp_path: Path) -> None:
+ tool = BgmMontageLite()
+ output = tmp_path / "montage.mp4"
+ output.write_bytes(b"user data")
+ inputs = _inputs(tmp_path, output)
+
+ with patch.object(tool, "check_dependencies", side_effect=AssertionError("must fail before launch")):
+ result = tool.execute(inputs)
+
+ assert not result.success
+ assert "already exists" in result.error
+ assert output.read_bytes() == b"user data"
+
+
+def test_missing_video_fails_before_runtime_checks(tmp_path: Path) -> None:
+ tool = BgmMontageLite()
+ audio = tmp_path / "music.mp3"
+ audio.write_bytes(b"audio fixture")
+
+ with patch.object(tool, "check_dependencies", side_effect=AssertionError("must fail before launch")):
+ result = tool.execute({"audio_path": str(audio), "video_paths": []})
+
+ assert not result.success
+ assert "at least one" in result.error.lower()
diff --git a/tools/video/bmts_lite.py b/tools/video/bmts_lite.py
new file mode 100644
index 00000000..7f78dec9
--- /dev/null
+++ b/tools/video/bmts_lite.py
@@ -0,0 +1,396 @@
+"""OpenMontage adapter for the standalone BMTS-Lite rendering engine."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from tools.base_tool import (
+ BaseTool,
+ DependencyError,
+ Determinism,
+ ExecutionMode,
+ ResourceProfile,
+ ResumeSupport,
+ RetryPolicy,
+ ToolResult,
+ ToolRuntime,
+ ToolStability,
+ ToolTier,
+)
+
+
+_ROOT_ENV = "BGM_MONTAGE_LITE_ROOT"
+_PYTHON_ENV = "BGM_MONTAGE_LITE_PYTHON"
+_RUNTIME_MODULES = ("librosa", "numpy", "cv2", "scipy", "soundfile")
+_RATIOS = {
+ "16:9": (1920, 1080),
+ "9:16": (1080, 1920),
+ "4:3": (1440, 1080),
+ "3:4": (1080, 1440),
+ "1:1": (1080, 1080),
+ "4:5": (1080, 1350),
+}
+_RUNNER = Path(__file__).with_name("bmts_lite_runner.py")
+
+
+def _fraction(value: Any) -> float | None:
+ try:
+ numerator, denominator = str(value).split("/", 1)
+ return float(numerator) / float(denominator)
+ except (ValueError, ZeroDivisionError):
+ return None
+
+
+class BgmMontageLite(BaseTool):
+ name = "bgm_montage_lite"
+ version = "0.1.0"
+ tier = ToolTier.CORE
+ capability = "video_post"
+ provider = "bmts-lite"
+ stability = ToolStability.BETA
+ execution_mode = ExecutionMode.SYNC
+ determinism = Determinism.STOCHASTIC
+ runtime = ToolRuntime.LOCAL
+
+ dependencies = ["cmd:ffmpeg", "cmd:ffprobe"]
+ install_instructions = (
+ "Clone https://github.com/sharbvane/BMTS-Lite, create an isolated Python 3.11 "
+ "environment, and install its requirements-runtime.txt. Set BGM_MONTAGE_LITE_ROOT "
+ "to that checkout and optionally BGM_MONTAGE_LITE_PYTHON to the environment's "
+ "interpreter. Install FFmpeg and ffprobe on PATH. See docs/bgm-montage-lite.md."
+ )
+
+ capabilities = [
+ "audio_led_montage",
+ "beat_synced_cuts",
+ "whole_track_coverage",
+ "automatic_aspect_ratio",
+ "source_reuse",
+ "full_decode_check",
+ ]
+ supports = {
+ "reference_video_required": False,
+ "api_key_required": False,
+ "whole_audio_track": True,
+ "source_reuse": True,
+ "automatic_aspect_ratio": True,
+ "semantic_asset_selection": False,
+ "agent_visual_review": False,
+ }
+ best_for = [
+ "Fast beat-led montage from one music track and supplied video clips",
+ "Reference-free local rendering with automatic framing and source reuse",
+ ]
+ not_good_for = [
+ "Reference-style matching, semantic clip selection, strict source-diversity gates, or a narrated composition",
+ ]
+ agent_skills = ["ffmpeg", "video-toolkit"]
+
+ input_schema = {
+ "type": "object",
+ "required": ["audio_path", "video_paths"],
+ "properties": {
+ "audio_path": {"type": "string", "minLength": 1},
+ "video_paths": {
+ "type": "array",
+ "items": {"type": "string", "minLength": 1},
+ "minItems": 1,
+ "maxItems": 100,
+ },
+ "aspect_ratio": {
+ "type": "string",
+ "enum": ["auto", "16:9", "9:16", "4:3", "3:4", "1:1", "4:5"],
+ "default": "auto",
+ },
+ "project_dir": {
+ "type": "string",
+ "description": "Optional OpenMontage project root; defaults output to its renders folder.",
+ },
+ "output_path": {
+ "type": "string",
+ "description": "Optional MP4 destination; defaults beside the music file or under project_dir/renders.",
+ },
+ },
+ }
+ output_schema = {
+ "type": "object",
+ "required": [
+ "output_path",
+ "timeline_path",
+ "audiomap_path",
+ "duration_seconds",
+ "aspect_ratio",
+ "shot_count",
+ "render_report",
+ ],
+ "properties": {
+ "output_path": {"type": "string"},
+ "timeline_path": {"type": "string"},
+ "audiomap_path": {"type": "string"},
+ "duration_seconds": {"type": "number", "minimum": 1},
+ "aspect_ratio": {"type": "string"},
+ "shot_count": {"type": "integer", "minimum": 1},
+ "render_report": {"type": "object"},
+ },
+ }
+ artifact_schema = {"type": "array", "items": {"type": "string"}}
+
+ resource_profile = ResourceProfile(
+ cpu_cores=4,
+ ram_mb=4096,
+ vram_mb=0,
+ disk_mb=8192,
+ network_required=False,
+ )
+ retry_policy = RetryPolicy(max_retries=0)
+ resume_support = ResumeSupport.FROM_START
+ idempotency_key_fields = ["audio_path", "video_paths", "output_path", "aspect_ratio"]
+ side_effects = ["writes an MP4, timeline JSON, and audiomap JSON"]
+ user_visible_verification = [
+ "BMTS-Lite checks the output streams, dimensions, duration, and full FFmpeg decode; play the MP4 to review its creative result.",
+ ]
+
+ def _python_executable(self) -> str:
+ requested = os.environ.get(_PYTHON_ENV, "").strip() or sys.executable
+ path = Path(requested).expanduser()
+ if path.is_file():
+ return str(path.resolve())
+ found = shutil.which(requested)
+ if found:
+ return found
+ raise DependencyError(f"Python interpreter not found: {requested}")
+
+ def _engine_root(self) -> Path:
+ configured = os.environ.get(_ROOT_ENV, "").strip()
+ if not configured:
+ raise DependencyError(f"Set {_ROOT_ENV} to a BMTS-Lite source checkout.")
+ root = Path(configured).expanduser().resolve()
+ required = [
+ root / "worker.py",
+ root / "engine" / "analyze_bgm.py",
+ root / "engine" / "timeline_planner.py",
+ root / "engine" / "montage.py",
+ root / "engine" / "visual_intelligence.py",
+ ]
+ missing = [str(path) for path in required if not path.is_file()]
+ if missing:
+ raise DependencyError(
+ f"{_ROOT_ENV} is not a complete BMTS-Lite checkout; missing: {', '.join(missing)}"
+ )
+ return root
+
+ def check_dependencies(self) -> None:
+ super().check_dependencies()
+ root = self._engine_root()
+ python = self._python_executable()
+ code = (
+ "import importlib.util, json, sys; "
+ f"modules={_RUNTIME_MODULES!r}; "
+ "missing=[name for name in modules if importlib.util.find_spec(name) is None]; "
+ "print(json.dumps(missing)); sys.exit(bool(missing))"
+ )
+ try:
+ result = subprocess.run(
+ [python, "-c", code], capture_output=True, text=True, timeout=30, check=False
+ )
+ except (OSError, subprocess.TimeoutExpired) as exc:
+ raise DependencyError(f"Could not check the BMTS-Lite Python environment: {exc}") from exc
+ if result.returncode:
+ try:
+ missing = json.loads(result.stdout)
+ except (json.JSONDecodeError, TypeError):
+ missing = list(_RUNTIME_MODULES)
+ raise DependencyError(
+ f"BMTS-Lite Python dependencies are missing: {', '.join(missing)}. "
+ "Install requirements-runtime.txt in the configured environment."
+ )
+ if not _RUNNER.is_file():
+ raise DependencyError(f"BMTS-Lite runner is missing: {_RUNNER}")
+
+ def execute(self, inputs: dict[str, Any]) -> ToolResult:
+ started = time.monotonic()
+ try:
+ audio = Path(inputs["audio_path"]).expanduser().resolve(strict=True)
+ videos = [Path(path).expanduser().resolve(strict=True) for path in inputs["video_paths"]]
+ if not audio.is_file() or not videos or any(not path.is_file() for path in videos):
+ raise ValueError("Provide one existing music file and at least one existing video file.")
+ if len(videos) > 100:
+ raise ValueError("BMTS-Lite accepts at most 100 source videos per run.")
+ total_bytes = sum(path.stat().st_size for path in [audio, *videos])
+ if total_bytes > 4 * 1024**3:
+ raise ValueError("BMTS-Lite inputs exceed its 4 GiB total upload limit.")
+
+ ratio = str(inputs.get("aspect_ratio", "auto")).strip().lower()
+ if ratio != "auto" and ratio not in _RATIOS:
+ raise ValueError(f"Unsupported aspect_ratio {ratio!r}; choose auto or a supported ratio.")
+
+ if inputs.get("output_path"):
+ output = Path(inputs["output_path"]).expanduser().resolve()
+ elif inputs.get("project_dir"):
+ output = Path(inputs["project_dir"]).expanduser().resolve() / "renders" / "bgm-montage-lite.mp4"
+ else:
+ output = audio.with_name(f"{audio.stem}_montage.mp4")
+ if output.suffix.lower() != ".mp4":
+ raise ValueError("output_path must use the .mp4 extension.")
+
+ timeline_path = output.with_suffix(".timeline.json")
+ audiomap_path = output.with_suffix(".audiomap.json")
+ destinations = [output, timeline_path, audiomap_path]
+ source_paths = {audio, *videos}
+ if any(path in source_paths for path in destinations):
+ raise ValueError("Output artifacts must not overwrite the supplied audio or video files.")
+ existing = [str(path) for path in destinations if path.exists()]
+ if existing:
+ raise FileExistsError(
+ "Output already exists; choose a new output_path: " + ", ".join(existing)
+ )
+
+ self.check_dependencies()
+ root = self._engine_root()
+ python = self._python_executable()
+ output.parent.mkdir(parents=True, exist_ok=True)
+
+ with tempfile.TemporaryDirectory(prefix=".bmts-lite-", dir=output.parent) as temp_name:
+ workspace = Path(temp_name)
+ request_path = workspace / "request.json"
+ request_path.write_text(
+ json.dumps(
+ {
+ "ratio": ratio,
+ "media": [{"file": str(path)} for path in [*videos, audio]],
+ },
+ ensure_ascii=False,
+ ),
+ encoding="utf-8",
+ )
+ process = self.run_command(
+ [
+ python,
+ str(_RUNNER),
+ "--root",
+ str(root),
+ "--workspace",
+ str(workspace),
+ "--request",
+ str(request_path),
+ ],
+ timeout=3600,
+ cwd=workspace,
+ )
+ summary = json.loads(process.stdout)
+ video_file = workspace / "result.mp4"
+ timeline_file = workspace / "timeline.json"
+ audiomap_file = workspace / "audiomap.json"
+ if any(not path.is_file() or path.stat().st_size == 0 for path in (video_file, timeline_file, audiomap_file)):
+ raise RuntimeError("BMTS-Lite returned without producing all expected artifacts.")
+
+ probe = json.loads(
+ self.run_command(
+ [
+ "ffprobe",
+ "-v",
+ "error",
+ "-show_format",
+ "-show_streams",
+ "-of",
+ "json",
+ str(video_file),
+ ],
+ timeout=60,
+ ).stdout
+ )
+ video_stream = next(
+ (stream for stream in probe.get("streams", []) if stream.get("codec_type") == "video"),
+ None,
+ )
+ audio_stream = next(
+ (stream for stream in probe.get("streams", []) if stream.get("codec_type") == "audio"),
+ None,
+ )
+ output_duration = float(probe.get("format", {}).get("duration", 0))
+ selected_ratio = str(summary.get("ratio", ""))
+ if (
+ video_stream is None
+ or audio_stream is None
+ or selected_ratio not in _RATIOS
+ or (video_stream.get("width"), video_stream.get("height")) != _RATIOS[selected_ratio]
+ or output_duration <= 0
+ or abs(output_duration - float(summary["duration"])) > 0.15
+ ):
+ raise RuntimeError("BMTS-Lite output failed OpenMontage's independent ffprobe checks.")
+
+ fps = _fraction(video_stream.get("avg_frame_rate")) or _fraction(
+ video_stream.get("r_frame_rate")
+ )
+ render_report = {
+ "version": "1.0",
+ "outputs": [
+ {
+ "path": str(output),
+ "format": "mp4",
+ "codec": video_stream.get("codec_name", "h264"),
+ "audio_codec": audio_stream.get("codec_name", "aac"),
+ "resolution": f"{video_stream['width']}x{video_stream['height']}",
+ **({"fps": fps} if fps is not None else {}),
+ "duration_seconds": output_duration,
+ "file_size_bytes": video_file.stat().st_size,
+ }
+ ],
+ "render_time_seconds": round(time.monotonic() - started, 2),
+ "verification_notes": [
+ "BMTS-Lite passed its ffprobe and full FFmpeg decode checks.",
+ "OpenMontage independently confirmed video/audio streams, dimensions, and duration.",
+ "No reference video, API key, semantic asset selection, or agent visual review was used by this tool.",
+ ],
+ "metadata": {
+ "renderer": "BMTS-Lite",
+ "aspect_ratio": selected_ratio,
+ "shot_count": int(summary["shots"]),
+ "timeline_path": str(timeline_path),
+ "audiomap_path": str(audiomap_path),
+ },
+ }
+ published: list[Path] = []
+ try:
+ for source, destination in (
+ (timeline_file, timeline_path),
+ (audiomap_file, audiomap_path),
+ (video_file, output),
+ ):
+ source.rename(destination)
+ published.append(destination)
+ except OSError:
+ for path in published:
+ path.unlink(missing_ok=True)
+ raise
+
+ return ToolResult(
+ success=True,
+ data={
+ "output_path": str(output),
+ "timeline_path": str(timeline_path),
+ "audiomap_path": str(audiomap_path),
+ "duration_seconds": output_duration,
+ "aspect_ratio": selected_ratio,
+ "shot_count": int(summary["shots"]),
+ "render_report": render_report,
+ },
+ artifacts=[str(output), str(timeline_path), str(audiomap_path)],
+ cost_usd=0.0,
+ duration_seconds=round(time.monotonic() - started, 2),
+ )
+ except Exception as exc:
+ return ToolResult(
+ success=False,
+ error=str(exc),
+ cost_usd=0.0,
+ duration_seconds=round(time.monotonic() - started, 2),
+ )
diff --git a/tools/video/bmts_lite_runner.py b/tools/video/bmts_lite_runner.py
new file mode 100644
index 00000000..3fe58d6c
--- /dev/null
+++ b/tools/video/bmts_lite_runner.py
@@ -0,0 +1,34 @@
+"""Small subprocess entry point that invokes the installed BMTS-Lite worker."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--root", required=True)
+ parser.add_argument("--workspace", required=True)
+ parser.add_argument("--request", required=True)
+ args = parser.parse_args()
+
+ root = Path(args.root).expanduser().resolve()
+ workspace = Path(args.workspace).expanduser().resolve()
+ try:
+ request = json.loads(Path(args.request).read_text(encoding="utf-8"))
+ sys.path[:0] = [str(root), str(root / "engine")]
+ from worker import run
+
+ result = run(workspace, request, lambda _message, _percent: None)
+ except Exception as exc:
+ print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
+ return 1
+ print(json.dumps(result, ensure_ascii=False))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())