Skip to content

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.

Add sphere.py: flat-viewport extraction from 360/spherical video (#103)

Shogo Kajiyamaf331bac19af5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index fb2fbf0..0513380 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ npx ffmpeg-skill
![before / after demo](assets/demo.gif)
-`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. Togeth
1. **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. For
On 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 detection
diff --git a/SKILL.md b/SKILL.md
index 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.md
index 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 the
ToolSpec 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 in
that project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's
diff --git a/package.json b/package.json
index 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.md
index 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, never
rounded, 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.py
index 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.py
new file mode 100644
index 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.py
index 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)
+
# ---------------------------------------------------------------- insert
def test_insert_native_size_and_duration(self):
out = OUT / "insert1.mp4"
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 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"}