ffmpeg-skill 1.8.1 → 1.9.1

package/SKILL.md

@@ -66,7 +66,8 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
 7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays,
-   graphics, crop/pad, resize, colour, transitions) run `look.py OUTPUT`
+   graphics, crop/pad, resize, colour, transitions, a `join.py` that scaled or
+   padded a clip to the first clip's frame) run `look.py OUTPUT`
    (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not
    finished until the report's `Look:` line names that PNG; a probe alone
    cannot see a caption sitting on someone's face. Audio-only jobs (sync,
@@ -162,6 +163,7 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 | "remove the green screen", "chroma key this" | `overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00` |
 | "sync the lav mic to the camera", "line up the two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
+| "cut this and make it HEVC / AV1", "a ProRes intermediate of the trimmed clip" (an edit whose *output codec* the user named) | `cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc` (`--codec h264\|hevc\|av1\|prores` and `--quality N` on every editing tool that re-encodes; ProRes needs `-o NAME.mov`; without a named codec leave the default) |
 | "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` (`--normalize` meets the platform's loudness spec in the same call, no separate `loudness.py` pass) |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
 | "make a small/low-res proxy for an analysis pass", "a cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset, see `export.py` for those |
@@ -253,6 +255,18 @@ Look: final_sheet.png (captions inside the safe area, logo top-right)
 Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo
 ```
 
+The same five lines for a Japanese request, prose in Japanese around the English labels
+(this is the shape a short job keeps too; English `Done:`/`Steps:` sentences with one Japanese
+word in `Notes:` is not a Japanese report):
+
+```
+Done: final.mp4 — 59.98 秒、1080x1920、30 fps、H.264、AAC ステレオ、-14.1 LUFS
+Steps: 0:12-1:12 をカット（無劣化）-> 9:16 にクロップ -> 字幕（ポップ、カラオケ）-> ラウドネス -14 -> Reels 書き出し
+Check: reels — 12 項目すべて合格（verified: true）
+Look: final_sheet.png（字幕はセーフエリア内、ロゴは右上）
+Notes: 元は VFR だったので 30 fps に揃えた。音声はモノラルだったのでステレオにした
+```
+
 Keep it to those five lines plus anything the user must decide. Attach the contact sheet when the edit touched the picture. Never report success without the probe of the output; never describe a fix you did not run.
 
 When a step fails, replace `Done:` with `Failed:` and keep the rest honest:

package/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 (`1.8.1`) | any release |
+| `skill.version` | the npm / package.json version (`1.9.1`) | 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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.8.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.9.1", "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"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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",

package/references/scripts.md

@@ -2,6 +2,18 @@
 
 Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
+## Time grammar (every time-taking flag, 1.9)
+
+One parser, `time_arg()`, behind every `--start`, `--end`, `--at`, `--from`,
+`--duration`, `--segments`, cue file and project field: seconds (`12.5`),
+`mm:ss(.fff)` (`1:30`), `hh:mm:ss(.fff)` (`00:01:30.250`; a comma also works,
+as in SRT). A four-part `hh:mm:ss:ff` is SMPTE non-drop-frame timecode at the
+source's frame rate; append `@fps` (`00:01:02:15@29.97`) to name the rate
+yourself, which is the only way for a tool with no input file (`caption.py
+--text` without a video, and `--fps` there). A four-part value with no fps
+anywhere is `kind: input` naming the flag. Nothing else about times differs
+between tools.
+
 ## Contents
 - probe.py — inspect
 - cut.py — cut / join segments
@@ -43,7 +55,9 @@ Every script prints the same information with `--help`; this file exists so the
 ```
 probe.py INPUT... [--compact] [--field duration|video.fps|...]
 ```
-JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected}`,
+JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,hdr_format}`
+(`hdr_signal` is true only for a PQ / HLG transfer or Dolby Vision; `hdr` also counts
+BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR" -- 2.0 renames),
 `audio{codec,channels,sample_rate}`. `--compact` gives one line per file.
 
 ### cut.py — cut / join segments
@@ -386,7 +400,9 @@ for a `--platform` or a platform export preset), and reports `plan`, `tool`,
 `tool_result` and `check`. Show the plan to the user, get the yes, execute:
 one round trip instead of re-deriving the command.
 `"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize`
-so the rendered file meets the platform's loudness without a separate pass.
+so the rendered file meets the platform's loudness without a separate pass. Since
+1.9.0 it is on by default when the preset is a platform (`youtube|youtube4k|reels|x`)
+and the project has no `loudness` stage; `"normalize": false` opts out.
 
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 captions → graphics → overlays → audio → loudness → export → check. Keys mirror the

package/scripts/_common.py

@@ -1322,6 +1322,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "pix_fmt": video.get("pix_fmt"),
             "bit_depth": _bit_depth(pix),
             "hdr": hdr,
+            # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
+            # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
+            # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
+            "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
             "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
                            "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
             "dolby_vision": dovi,
@@ -1429,10 +1433,25 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
     v = value.strip().replace(",", ".")
     if not v:
         raise ValueError("empty time")
+    if "@" in v:
+        # 1.9: 'hh:mm:ss:ff@29.97' names the timecode's rate explicitly (docs/design-decisions.md,
+        # time grammar); it overrides the source fps a tool passed in, and is meaningless without
+        # the four-part form
+        v, _, rate = v.rpartition("@")
+        if "@" in v:
+            raise ValueError(f"'{value}': only one @fps suffix is allowed")
+        try:
+            fps = float(rate)
+        except ValueError:
+            raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
+        if fps <= 0:
+            raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
+        if len(v.split(":")) != 4:
+            raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
     parts = v.split(":")
     if len(parts) == 4:
         if fps is None or fps <= 0:
-            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds")
+            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds (append @fps, e.g. {value}@29.97, or use seconds / mm:ss / hh:mm:ss.ms)")
         h, m, s, f = parts
         if "." in f:
             raise ValueError(f"bad SMPTE timecode: {value}")
@@ -1462,7 +1481,7 @@ def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
     except MissingFpsError as e:
         die(f"{flag} {value!r}: {e}")
     except ValueError as e:
-        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms or, with a known fps, hh:mm:ss:ff)")
+        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
     return 0.0  # unreachable
 
 

package/scripts/broll.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 
 
 def main() -> int:
@@ -69,13 +69,13 @@ def main() -> int:
         meta_b = probe(path)
         if not meta_b.get("video"):
             die(f"{path} has no video stream")
-        at = parse_time(args.at[i], fps)
-        start_b = parse_time(per(args.from_, i, "0"), fps)
+        at = time_arg(args.at[i], "--at", fps)
+        start_b = time_arg(per(args.from_, i, "0"), "--from", fps)
         if args.end:
-            end = parse_time(per(args.end, i, "0"), fps)
+            end = time_arg(per(args.end, i, "0"), "--end", fps)
             length = end - at
         else:
-            length = parse_time(per(args.duration, i, "4"), fps)
+            length = time_arg(per(args.duration, i, "4"), "--duration", fps)
         if length <= 0:
             die(f"cutaway {i + 1}: length must be > 0 (at {at:g}s, got {length:g}s)")
         if dur_a and at >= dur_a:

package/scripts/caption.py

@@ -19,7 +19,7 @@ The subtitle codec is picked from the output container: mov_text for
 Text-to-SRT input format (one cue per line, blank lines ignored):
   0:00-0:03 Hello and welcome
   00:00:03.500 --> 00:00:06 Second line | with a manual line break
-  00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps)
+  00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps or an @fps suffix: 00:00:03:15@29.97)
   Text without a time is auto-timed after the previous cue (--auto-seconds)
 
 Examples:
@@ -41,7 +41,7 @@ from _common import STATE, color_hex, load_brand, video_args, add_common, apply_
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
 TIME_RE = re.compile(
-    r"^\s*(?P<a>[\d:.,]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,]+)\s+(?P<text>.+)$"
+    r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
 )
 
 

package/scripts/cut.py

@@ -30,7 +30,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs
+from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
 DROPPED_STREAMS: List[str] = []
@@ -39,13 +39,9 @@ DROPPED_STREAMS: List[str] = []
 NEAREST_KEYFRAMES: list = []
 
 
-def _t(value: str, fps) -> float:
-    """parse_time() with the input's fps (SMPTE hh:mm:ss:ff) and every failure as kind input."""
-    try:
-        return parse_time(value, fps)
-    except (ValueError, MissingFpsError) as e:
-        die(f"bad time {value!r}: {e}")
-    return 0.0  # unreachable
+def _t(value: str, fps, flag: str = "--segments") -> float:
+    """time_arg() with the input's fps (SMPTE hh:mm:ss:ff, or @fps): the one parser every tool uses (1.9)."""
+    return time_arg(value, flag, fps)
 
 
 def parse_segments(spec: str, fps=None) -> List[Tuple[float, float]]:
@@ -183,17 +179,17 @@ def main() -> int:
     if args.segments:
         segments = parse_segments(args.segments, fps)
     else:
-        start = _t(args.start, fps)
+        start = _t(args.start, fps, "--start")
         if start < 0:
             die(f"--start must not be negative, got {args.start!r}")
         if args.end and args.duration:
             die("use --end or --duration, not both")
         if args.end:
-            end = _t(args.end, fps)
+            end = _t(args.end, fps, "--end")
             if end < 0:
                 die(f"--end must not be negative, got {args.end!r}")
         elif args.duration:
-            end = start + _t(args.duration, fps)
+            end = start + _t(args.duration, fps, "--duration")
         else:
             end = total
         if end <= start:

package/scripts/freeze.py

@@ -19,7 +19,7 @@ Examples:
 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, X264_PRESETS, MissingFpsError, parse_time, fmt_secs, run
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, time_arg, fmt_secs, run
 
 
 def main() -> int:
@@ -45,10 +45,7 @@ def main() -> int:
     dur = meta.get("duration") or 0.0
     fps = meta["video"].get("fps") or 30.0
     if args.at is not None:
-        try:
-            at = parse_time(args.at, (meta.get("video") or {}).get("fps"))
-        except (ValueError, MissingFpsError) as e:
-            die(f"--at {args.at!r}: {e}")
+        at = time_arg(args.at, "--at", (meta.get("video") or {}).get("fps"))
     else:
         at = dur
     if at < 0 or at > dur:

package/scripts/metadata.py

@@ -30,7 +30,7 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, STATE, read_text_or_die
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, STATE, read_text_or_die
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -46,10 +46,8 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         if not line or line.startswith("#"):
             continue
         parts = line.split(None, 1)
-        try:
-            start = parse_time(parts[0])
-        except ValueError:  # MissingFpsError is a ValueError: chapter files carry no fps
-            die(f"{path}:{n}: cannot read the time in {line!r} (use seconds, mm:ss or hh:mm:ss.ms)")
+        # chapter files carry no fps, so hh:mm:ss:ff needs its @fps suffix; time_arg() says so
+        start = time_arg(parts[0], f"{path}:{n}")
         title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
         if entries and start <= entries[-1]["start"]:
             die(f"{path}:{n}: chapter at {start:g}s does not come after the previous one at {entries[-1]['start']:g}s")

package/scripts/multicam.py

@@ -29,7 +29,7 @@ import argparse
 import sys
 from typing import List, Tuple
 
-from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args, X264_PRESETS, fmt_secs
+from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs
 from sync import measure_offset
 
 
@@ -42,9 +42,10 @@ def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:
         try:
             rng, cam = raw.rsplit(":", 1)
             a, b = rng.rsplit("-", 1)
-            s, e, c = parse_time(a), parse_time(b), int(cam)
+            c = int(cam)
         except ValueError:
             die(f"bad switch entry '{raw}' (want START-END:CAM)")
+        s, e = time_arg(a, f"--switch {raw!r} start"), time_arg(b, f"--switch {raw!r} end")
         if not 0 <= c < n:
             die(f"camera {c} does not exist (inputs are 0..{n - 1})")
         if e <= s:

package/scripts/render.py

@@ -27,7 +27,7 @@ Project format (all keys optional except clips):
   "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2},
   "loudness": {"lufs": -14, "tp": -1},
   "fit": {"duration": 60},
-  "export": {"preset": "reels", "normalize": true},
+  "export": {"preset": "reels", "normalize": true},   (default for platform presets; false opts out)
   "check": {"platform": "reels"}
 }
 
@@ -56,7 +56,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from export import PRESETS
+from export import PRESETS, PLATFORM_OF
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION
 
 HERE = Path(__file__).resolve().parent
@@ -464,7 +464,14 @@ def main() -> int:
             argv += ["--fit", ex["fit"]]
         if ex.get("crf") is not None:
             argv += ["--crf", str(ex["crf"])]
-        if ex.get("normalize"):
+        normalize = ex.get("normalize")
+        if normalize is None and ex["preset"] in PLATFORM_OF and not proj.get("loudness"):
+            # eval 8: a reels project without the key rendered fully, failed the loudness check and
+            # was rendered again; a platform preset with no loudness stage of its own gets the
+            # one-export behaviour by default ("normalize": false opts out)
+            normalize = True
+            info(f"export: --normalize on by default for the {ex['preset']} preset (set \"normalize\": false to skip)")
+        if normalize:
             argv += ["--normalize"]  # one export that meets the platform's loudness (export.py --normalize)
         sh("export.py", *argv)
         stages_done.append("export")

package/scripts/speedramp.py

@@ -19,7 +19,7 @@ import argparse
 import sys
 from typing import List, Tuple
 
-from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, parse_time
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_arg
 
 MAX_SPEED = 20.0
 MIN_SPEED = 0.05
@@ -43,9 +43,10 @@ def parse_segment(raw: str) -> Tuple[float, float, float]:
     try:
         span, factor_s = raw.rsplit(":", 1)
         start_s, end_s = span.rsplit("-", 1)
-        start, end, factor = parse_time(start_s), parse_time(end_s), float(factor_s)
+        factor = float(factor_s)
     except ValueError:
-        die(f"--segment must look like START-END:FACTOR (times in seconds or mm:ss), got '{raw}'")
+        die(f"--segment must look like START-END:FACTOR, got '{raw}'")
+    start, end = time_arg(start_s, f"--segment {raw!r} start"), time_arg(end_s, f"--segment {raw!r} end")
     if end <= start:
         die(f"--segment {raw}: END must be after START")
     if not MIN_SPEED <= factor <= MAX_SPEED: