Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Add sphere.py: flat-viewport extraction from 360/spherical video (#103)
Shogo Kajiyamaf331bac19af5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9549b6c..d511751 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,15 @@(nothing yet)+## 0.13.0 — add `sphere.py`: flat-viewport extraction from 360/spherical video++New tool wrapping FFmpeg's `v360` filter for the most common 360-video job: pointing a fixed,+typed camera (`--yaw`/`--pitch`/`--roll`, `--h-fov`/`--v-fov`) at an equirectangular (or+fisheye/cubemap/etc., via `--input-projection`) source and baking out an ordinary flat video.+Consistent with this skill's design boundary: it aims and extracts a viewport, it does not detect+or track a subject — that decision stays with the calling agent. Registered in `TOOL_META`/+`REENCODE_META`, 29 tools total.+## 0.12.6 — stop shipping `__pycache__` in the npm tarball`package.json`'s `files` array scopes the tarball to `bin/`, `scripts/`, `mcp/`, `references/`,diff --git a/README.md b/README.mdindex fb2fbf0..0513380 100644--- a/README.md+++ b/README.md@@ -25,7 +25,7 @@ npx ffmpeg-skill-`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **28 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **29 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.@@ -139,7 +139,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.-4. **Machine-readable contract.** `contract --json` describes all 28 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 28 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.+4. **Machine-readable contract.** `contract --json` describes all 29 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 29 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.@@ -148,7 +148,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth## Tools-28 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.+29 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.**Analysis and inspection**@@ -167,6 +167,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list || `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad or crop, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps || `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |+| `sphere.py` | Extract a flat rectilinear viewport from a 360/spherical video (`--yaw --pitch --roll --h-fov --v-fov`); no subject tracking, only the aim you give it || `insert.py` | Turn a still image into a silent, fixed-duration video clip (title card, end slate) at an exact frame size / fps, with an optional Ken Burns zoom/pan || `background.py` | Generate a solid-colour or two-colour gradient clip at an exact size/duration — no input file || `reverse.py` | Reverse playback (video and, unless `--no-audio`, audio) |@@ -259,7 +260,7 @@ npx ffmpeg-skill contract --json # or: python3 scripts/_contract.py -npx ffmpeg-skill contract --json --static # without environment detection```-The contract is generated from the code that runs, not maintained beside it. For each of the 28 tools (`ffmpeg-skill/<name>`) it states:+The contract is generated from the code that runs, not maintained beside it. For each of the 29 tools (`ffmpeg-skill/<name>`) it states:| Field | Meaning ||---|---|@@ -284,7 +285,7 @@ The contract is generated from the code that runs, not maintained beside it. ForOn Windows, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — if your MCP client reports the server failed to start, change `"command"` above to `"python"` (or the full path from `where python`).-`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 28 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.+`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 29 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.### Capability detectiondiff --git a/SKILL.md b/SKILL.mdindex 3a47bf0..38db366 100644--- a/SKILL.md+++ b/SKILL.md@@ -131,6 +131,7 @@ If a request needs an FFmpeg feature none of the 28 scripts expose, say so and n| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) || "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) || "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |+| "pull a flat clip out of this 360/spherical video, looking this way" (known yaw/pitch/fov, not "find the interesting part") | `sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70` || "turn this image into a N-second clip", "title card / end slate" | `insert.py title.png --duration 3` || "slow zoom on a photo", "Ken Burns effect" | `insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080` || "rotate this 90 degrees", "mirror it horizontally" | `fit.py input.mp4 --rotate 90` / `fit.py input.mp4 --flip h` |diff --git a/docs/contract.md b/docs/contract.mdindex 6588fc3..b12df42 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:| Field | Meaning | Changes when ||---|---|---|| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |-| `skill.version` | the npm / package.json version (`0.12.6`) | any release |+| `skill.version` | the npm / package.json version (`0.13.0`) | any release |A release that adds a tool or a flag keeps `contract_version`; a breaking change to theToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`@@ -39,7 +39,7 @@ drifting silently.```json{"contract_version": "1.0",- "skill": {"id": "ffmpeg-skill", "version": "0.12.6", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.13.0", "execution_mode": "local", "kind": "execution","entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},@@ -129,7 +129,7 @@ gives you:## `provides`-`provides` lists these 28 tools by a cross-repository Capability id, for+`provides` lists these 29 tools by a cross-repository Capability id, for`kajisho5/AI-video-production-OS`'s `CapabilityContract.provides`(`docs/SPEC.md` there), matching the ids already assigned to this Skill inthat project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill'sdiff --git a/package.json b/package.jsonindex 3a959bf..a62f633 100644--- a/package.json+++ b/package.json@@ -1,7 +1,7 @@{"name": "ffmpeg-skill",- "version": "0.12.6",- "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 28 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",+ "version": "0.13.0",+ "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 29 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.","keywords": ["ffmpeg","video",diff --git a/references/scripts.md b/references/scripts.mdindex e8e7bc0..c8cc14c 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -86,6 +86,25 @@ lie entirely inside the source frame (after accounting for display rotation);`--width`/`--height` must be even (4:2:0 chroma) and are refused, neverrounded, if they aren't.+### sphere.py — flat viewport extraction from 360/spherical video+```+sphere.py INPUT [--input-projection equirect|fisheye|dfisheye|c3x2|c6x1|barrel|cylindrical|hequirect]+ [--yaw D] [--pitch D] [--roll D] [--h-fov D] [--v-fov D]+ [--width W] [--height H] [--interp METHOD] [--stereo mono|sbs|tb]+ [--audio-stream N] [-o OUT]+```+Wraps FFmpeg's `v360` filter to bake out an ordinary flat clip pointed at a+fixed direction — the same "look this way" operation a VR headset or a 360+player's viewport does. `--yaw`/`--pitch`/`--roll` aim the camera (each+-180..180, default 0); `--h-fov`/`--v-fov` set how wide the view is (each+1..170, default 90/60). `--input-projection` must match the source's own+projection (default `equirect`, the most common capture/export format) —+this tool cannot detect it from the pixels, so a wrong value produces a+distorted or garbled output, not an error. There is no subject detection or+tracking here: only the typed aim you give it. For a shot that follows a+moving subject, call this once per keyframe viewpoint from outside this+tool. `--width`/`--height` must be even (4:2:0 chroma); default 1920x1080.+### insert.py — still image to a timed silent clip```insert.py IMAGE --duration T [--width W] [--height H] [--fps N]diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 1d985a2..1fce2a0 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -79,6 +79,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {"crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],required=FF + [X264, AAC], optional=[HDR_X265],video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),+ "sphere": dict(role="execution", inputs=["360/spherical video asset"], outputs=["flat rectilinear video artifact of the chosen viewport"],+ required=FF + [X264, AAC, "filter:v360"], optional=[HDR_X265],+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),"insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),@@ -189,6 +192,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {"cut": dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),"fit": dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),"crop": dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),+ "sphere": dict(video="always", audio="always", note="the v360 filter always forces a re-encode of the video stream; audio is passed through to AAC unchanged"),"insert": dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),"background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),"reverse": dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),diff --git a/scripts/sphere.py b/scripts/sphere.pynew file mode 100644index 0000000..546ec4e--- /dev/null+++ b/scripts/sphere.py@@ -0,0 +1,124 @@+#!/usr/bin/env python3+"""Extract a flat (rectilinear) viewport from a 360/spherical video.++This wraps FFmpeg's v360 filter for the one job it is most often needed for:+turning an equirectangular (or other spherical-projection) source into an+ordinary flat video pointed at a chosen direction -- the same "look this way"+operation a VR headset or a 360 video player's viewport does, baked into a+real file. --yaw/--pitch/--roll aim the camera; --h-fov/--v-fov set how wide+the view is.++This tool does not decide WHERE to point the camera -- there is no subject+detection or tracking here, only the typed rotation/FOV you give it (see this+skill's design principles: it measures and transforms, it does not judge+"what's interesting" in a frame). For a shot that follows a moving subject,+call this once per keyframe viewpoint (or render a short segment per angle)+from outside this tool.++Nor does it detect whether an input actually IS a 360/spherical video --+probe.py's frame dimensions don't distinguish a 2:1 equirectangular capture+from an ordinary flat clip that happens to be that aspect ratio. Point+--input-projection at what the source actually is; wrong information here+produces a distorted or garbled output, not an error (a real limit of what a+frame's own pixels can prove about how they were projected -- ffmpeg's own+v360 filter has the same limit).++Examples:+ python3 sphere.py insta360.mp4 --yaw 0 --pitch 0 -o front.mp4+ python3 sphere.py insta360.mp4 --yaw 90 --h-fov 100 --v-fov 70 -o right_wide.mp4+ python3 sphere.py gopro_max.mp4 --input-projection fisheye --yaw -45 --pitch 10 -o angle.mp4+"""+import argparse+import sys++from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args++# v360's own AVOption names for the input projections real 360 cameras/exports actually+# produce (ffmpeg -h filter=v360 documents 24 total; this is the subset a caller is likely+# to have on hand, not the full list -- narrower, typed choices over an open string).+INPUT_PROJECTIONS = ["equirect", "fisheye", "dfisheye", "c3x2", "c6x1", "barrel", "cylindrical", "hequirect"]+INTERP_METHODS = ["nearest", "linear", "cubic", "lanczos", "spline16", "gaussian", "mitchell"]+STEREO_MODES = {"mono": "2d", "sbs": "sbs", "tb": "tb"}+++def main() -> int:+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("input")+ ap.add_argument("-o", "--output", help="output file (default: <name>_view.<ext>)")+ ap.add_argument("--audio-stream", type=int, default=0,+ help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "+ "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "+ "the first track")+ ap.add_argument("--input-projection", choices=INPUT_PROJECTIONS, default="equirect",+ help="the source's own 360 projection (default equirect, the most common capture/export format)")+ ap.add_argument("--stereo", choices=list(STEREO_MODES), default="mono",+ help="input stereo packing: mono (default), sbs (side-by-side), tb (top-bottom) -- always flattened to a mono output")+ aim = ap.add_argument_group("camera aim")+ aim.add_argument("--yaw", type=float, default=0.0, help="left/right rotation in degrees, -180..180 (default 0, straight ahead)")+ aim.add_argument("--pitch", type=float, default=0.0, help="up/down rotation in degrees, -180..180 (default 0, level)")+ aim.add_argument("--roll", type=float, default=0.0, help="tilt/roll rotation in degrees, -180..180 (default 0)")+ fov = ap.add_argument_group("field of view")+ fov.add_argument("--h-fov", type=float, default=90.0, help="output horizontal field of view in degrees, 1..170 (default 90)")+ fov.add_argument("--v-fov", type=float, default=60.0, help="output vertical field of view in degrees, 1..170 (default 60)")+ out = ap.add_argument_group("output frame")+ out.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")+ out.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")+ out.add_argument("--interp", choices=INTERP_METHODS, default="lanczos", help="resampling method (default lanczos)")+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")+ ap.add_argument("--preset", default="medium", help="x264 preset")+ ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")+ add_common(ap)+ args = ap.parse_args()+ apply_common(args)++ if not -180 <= args.yaw <= 180:+ die(f"--yaw must be -180..180, got {args.yaw}")+ if not -180 <= args.pitch <= 180:+ die(f"--pitch must be -180..180, got {args.pitch}")+ if not -180 <= args.roll <= 180:+ die(f"--roll must be -180..180, got {args.roll}")+ if not 1 <= args.h_fov <= 170:+ die(f"--h-fov must be 1..170, got {args.h_fov}")+ if not 1 <= args.v_fov <= 170:+ die(f"--v-fov must be 1..170, got {args.v_fov}")+ if args.width <= 0 or args.height <= 0:+ die(f"--width/--height must be > 0, got width={args.width} height={args.height}")+ if args.width % 2 or args.height % 2:+ die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")++ meta = probe(args.input)+ if not meta.get("video"):+ die("input has no video stream")+ has_audio = bool(meta.get("audio"))+ audio_streams = meta.get("audio_streams") or []+ if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")+ if args.audio_stream and not audio_streams:+ die("--audio-stream needs an input with audio streams")+ output = args.output or default_output(args.input, "view")++ v360 = (f"v360=input={args.input_projection}:output=rectilinear:"+ f"in_stereo={STEREO_MODES[args.stereo]}:out_stereo=2d:"+ f"yaw={args.yaw:g}:pitch={args.pitch:g}:roll={args.roll:g}:"+ f"h_fov={args.h_fov:g}:v_fov={args.v_fov:g}:"+ f"w={args.width}:h={args.height}:interp={args.interp}")+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", v360, "-map", "0:v:0"]+ if has_audio:+ cmd += ["-map", f"0:a:{args.audio_stream}?"]+ cmd += video_args(meta, args.crf, args.preset)+ cmd += cfr_args(meta, args.fps)+ if has_audio:+ cmd += aac_args()+ else:+ cmd += ["-an"]+ dropped_streams = run_keeping_subtitles(cmd, output)++ result = probe(output, role="output")+ v = result["video"]+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, yaw={args.yaw:g} pitch={args.pitch:g})")+ emit(output, dropped_non_av_streams=dropped_streams)+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tests/test_all.py b/tests/test_all.pyindex 527f31b..e040293 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -301,6 +301,38 @@ class FFmpegSkillTests(unittest.TestCase):def test_crop_negative_offset_refused(self):script("crop.py", self.src, "--x", "-5", "--y", "0", "--width", "100", "--height", "100", expect_fail=True)+ # ---------------------------------------------------------------- sphere+ def test_sphere_extracts_a_flat_viewport(self):+ out = OUT / "sphere1.mp4"+ script("sphere.py", self.src, "--yaw", "90", "--pitch", "10", "--h-fov", "100", "--v-fov", "70",+ "--width", "640", "--height", "360", "-o", out)+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))+ self.assertClose(m["duration"], 12.0, 0.2)+ self.assertIsNotNone(m["audio"])++ def test_sphere_defaults_and_no_audio_source(self):+ no_audio = OUT / "sphere_no_audio_src.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x320:rate=25",+ "-t", "2", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", no_audio)+ out = OUT / "sphere2.mp4"+ script("sphere.py", no_audio, "-o", out)+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1920, 1080))+ self.assertIsNone(m["audio"])++ def test_sphere_yaw_out_of_range_refused(self):+ script("sphere.py", self.src, "--yaw", "200", expect_fail=True)++ def test_sphere_fov_out_of_range_refused(self):+ script("sphere.py", self.src, "--h-fov", "0", expect_fail=True)++ def test_sphere_odd_dimensions_refused(self):+ script("sphere.py", self.src, "--width", "641", "--height", "360", expect_fail=True)++ def test_sphere_audio_stream_out_of_range_refused(self):+ script("sphere.py", self.src, "--audio-stream", "5", expect_fail=True)+# ---------------------------------------------------------------- insertdef test_insert_native_size_and_duration(self):out = OUT / "insert1.mp4"diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 9313035..794d68e 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -484,7 +484,7 @@ class ContractTests(unittest.TestCase):self.assertEqual(self.tools["cut"]["verification"]["tools"], ["ffmpeg-skill/probe"])def test_visual_verification_metadata(self):- picture = {"fit", "crop", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy"}+ picture = {"fit", "crop", "sphere", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy"}# join is the one picture tool that also accepts audio-only inputs (audio concat); look applies# to its video output only, which SKILL.md states next to "Look: not needed"both = {"join"}