lcode-cli 0.42.0__py3-none-any.whl → 0.44.0__py3-none-any.whl

lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.42.0"
+__version__ = "0.44.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

lcode/agent.py

@@ -309,6 +309,7 @@ class Settings:
     comfyui_path: str | None = None  # a ComfyUI install lcode doesn't find by itself (lcode.comfy)
     media_dir: str = ".lcode/media"  # where image and video mode save their files (lcode.media)
     image_model: str = "flux2-klein-4b"  # the media catalog's model image mode uses (lcode.media_catalog)
+    video_model: str = "wan22-ti2v-5b"  # and video mode's
     preview: str = "auto"  # images in the terminal: auto, kitty, iterm, blocks or off (lcode.preview)
     num_batch: int | None = None
     keep_alive: str = "30m"
@@ -380,7 +381,8 @@ class Agent:
 
         self.image_options = ImageOptions()  # image mode's defaults for this session (/options)
         self.media_results: list[dict] = []  # the session's images, numbered (/gallery, /vary, /open)
-        self.last_request: tuple[str, ImageOptions] | None = None  # for /again
+        self.last_request: dict | None = None  # what /again repeats (lcode.media.redo)
+        self.image_refs: list[str] = []  # images every next request follows (/use)
         self.reflected = 0  # messages before this index were already checked for notes to remember
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
@@ -697,7 +699,8 @@ class Agent:
             "model": self.settings.model,
             "mode": self.settings.mode,
             "image_model": self.settings.image_model,
-            "media": {"results": self.media_results, "options": self.image_options.to_json()},
+            "video_model": self.settings.video_model,
+            "media": {"results": self.media_results, "options": self.image_options.to_json(), "refs": self.image_refs},
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
@@ -748,9 +751,12 @@ class Agent:
             self.settings.mode = data["mode"]  # a session belongs to the mode it was made in
         if isinstance(data.get("image_model"), str):
             self.settings.image_model = data["image_model"]
+        if isinstance(data.get("video_model"), str):
+            self.settings.video_model = data["video_model"]
         media = data.get("media") or {}
         self.media_results = [r for r in media.get("results") or [] if isinstance(r, dict) and "path" in r]
         self.image_options = type(self.image_options).from_json(media.get("options") or {})
+        self.image_refs = [r for r in media.get("refs") or [] if isinstance(r, str)]
         self.session_title = data.get("title") or sessions.title_from(self.messages)
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
         self.tools.todos = list(data.get("todos") or [])

lcode/api.py

@@ -201,6 +201,7 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         comfyui_path=cfg["comfyui_path"],
         media_dir=cfg["media_dir"],
         image_model=cfg["image_model"],
+        video_model=cfg["video_model"],
         preview=cfg["preview"],
         web=switch(options.web, cfg["web"], "on"),
         search_backend=cfg["search_backend"],

lcode/cli.py

@@ -801,16 +801,8 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
     """`lcode --mode image -p "…"`: make the image, say where it went (or, with --output json, a result object)."""
     import json
 
-    from lcode import api, media, modes
+    from lcode import api, media
 
-    if agent.settings.mode == "video":
-        message = modes.COMING["video"]
-        if quiet:
-            print(json.dumps({"type": "result", "status": "error", "error": message}), flush=True)
-        else:
-            out.print(f"[yellow]{escape(message)}[/]")
-        api.close_agent(agent)
-        sys.exit(2)
     try:
         made = media.request(agent, prompt)
     except (media.MediaError, KeyboardInterrupt) as e:
@@ -825,7 +817,7 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
         result = {
             "type": "result",
             "status": "success",
-            "mode": "image",
+            "mode": agent.settings.mode,
             "files": [str(path) for one in made for path in one.files],
             "model": made[0].model,
             "seed": made[0].seed,
@@ -1106,10 +1098,14 @@ def cmd_media(args) -> None:
     where = (
         f"ComfyUI at {server.url}" if running else (f"{install.path} (not running)" if install else "no ComfyUI found")
     )
-    console.print(f"[dim]{hw.describe()} · {where} · image model: {cfg['image_model']}[/]\n")
-    for mode in ("image", "video"):
+    console.print(f"[dim]{hw.describe()} · {where} · image: {cfg['image_model']} · video: {cfg['video_model']}[/]\n")
+    for mode in ("image", "video", "tool"):
         models = cat.for_mode(mode)
-        console.print(f"[bold]{mode.capitalize()} models[/]")
+        console.print(
+            "[bold]Tools for images[/] [dim](/upscale, /nobg)[/]"
+            if mode == "tool"
+            else f"[bold]{mode.capitalize()} models[/]"
+        )
         if not models:
             console.print(f"  [dim]{media.SOON[mode]}[/]\n")
             continue

lcode/comfy.py

@@ -336,8 +336,9 @@ def describe_rejection(r: requests.Response) -> str:
     lines = [str((data.get("error") or {}).get("message") or "ComfyUI refused the workflow")]
     for node, info in (data.get("node_errors") or {}).items():
         for err in info.get("errors", [])[:3]:
-            detail = err.get("details") or err.get("message") or ""
-            lines.append(f"{info.get('class_type', 'node')} ({node}): {detail}")
+            message, detail = err.get("message") or "", err.get("details") or ""
+            why = f"{message}: {detail}" if message and detail and detail not in message else (detail or message)
+            lines.append(f"{info.get('class_type', 'node')} ({node}): {why}")
     return "; ".join(lines)
 
 

lcode/config.py

@@ -46,6 +46,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "comfyui_path": (None, str, "your ComfyUI folder, if lcode doesn't find it (lcode starts it when needed)"),
     "media_dir": (".lcode/media", str, "where images and videos go: a folder in the project, or an absolute path"),
     "image_model": ("flux2-klein-4b", str, "the model image mode uses: a key from `lcode media`"),
+    "video_model": ("wan22-ti2v-5b", str, "the model video mode uses: a key from `lcode media`"),
     "preview": ("auto", str, "images in the terminal: auto | kitty | iterm | blocks (colour text) | off"),
     "think": (True, bool, "let the model reason before answering (slower, better)"),
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
@@ -217,12 +218,12 @@ def coerce(key: str, value: object) -> object:
 
         if value not in PROTOCOLS:
             raise ConfigError(f"preview must be one of {', '.join(PROTOCOLS)}")
-    if key == "image_model":
+    if key in ("image_model", "video_model"):
         from lcode import media_catalog
 
-        keys = [m.key for m in media_catalog.load().for_mode("image")]
+        keys = [m.key for m in media_catalog.load().for_mode(key.removesuffix("_model"))]
         if value not in keys:
-            raise ConfigError(f"image_model must be one of {', '.join(keys)} (see lcode media)")
+            raise ConfigError(f"{key} must be one of {', '.join(keys)} (see lcode media)")
     if typ is bool and isinstance(value, str):
         if value.lower() not in ("true", "false", "1", "0", "yes", "no", "on", "off"):
             raise ConfigError(f"{key} must be true or false")

lcode/edits.py

@@ -0,0 +1,283 @@
+"""Image edits as changes to a ComfyUI workflow: reference images, inpainting through a mask, outpainting.
+
+A model that edits with reference latents (FLUX.2 klein) takes the images through its own text-to-image workflow:
+each image is scaled, encoded by the VAE and attached to both conditionings before the guider, and the instruction is
+the prompt. On top of that:
+
+- **Inpainting** keeps the original outside a mask: the edited picture is pasted into the original only where the
+  mask is white (with a soft edge).
+- **Outpainting** puts the image on a bigger canvas, lets the model fill the new border, and pastes the original back,
+  so it stays exactly as it was.
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+from pathlib import Path
+
+BASE = 8000  # node ids lcode adds start here (the workflows' own are small numbers)
+SIZE_NODE = str(BASE + 9)
+IMAGE_TYPES = (".png", ".jpg", ".jpeg", ".webp", ".bmp")
+EXTEND_HINT = (
+    "Replace the blurry border around the sharp picture with sharp, detailed scenery that continues the picture "
+    "outward, matching its light, perspective and style. Keep the sharp middle exactly as it is. No frame, no bars."
+)
+
+
+class EditError(ValueError):
+    pass
+
+
+def node_of(graph: dict, class_type: str) -> str | None:
+    return next((nid for nid, node in graph.items() if node.get("class_type") == class_type), None)
+
+
+def save_node(graph: dict) -> str:
+    nid = node_of(graph, "SaveImage")
+    if nid is None:
+        raise EditError("the workflow saves no image")
+    return nid
+
+
+def load_images(graph: dict, names: list[str]) -> list[list]:
+    """LoadImage nodes for uploaded images; their IMAGE outputs."""
+    links = []
+    for k, name in enumerate(names):
+        nid = str(BASE + 100 + k)
+        graph[nid] = {"class_type": "LoadImage", "inputs": {"image": name}}
+        links.append([nid, 0])
+    return links
+
+
+def add_references(graph: dict, images: list[list], megapixels: float, size_from_first: bool) -> list:
+    """Attach the images as reference latents to the guider's positive and negative conditionings.
+
+    Each is scaled to `megapixels` first. With `size_from_first`, the picture made has the first image's size
+    (its width and height go to every node of the workflow that takes them). Returns the first scaled image.
+    """
+    guider = node_of(graph, "CFGGuider")
+    vae = node_of(graph, "VAELoader")
+    if guider is None or vae is None:
+        raise EditError("this workflow can't take reference images")
+    positive, negative = graph[guider]["inputs"]["positive"], graph[guider]["inputs"]["negative"]
+    first = None
+    for k, image in enumerate(images):
+        scale, encode, ref_pos, ref_neg = (str(BASE + 10 * (k + 1) + i) for i in range(4))
+        graph[scale] = {
+            "class_type": "ImageScaleToTotalPixels",
+            "inputs": {"image": image, "upscale_method": "lanczos", "megapixels": megapixels, "resolution_steps": 16},
+        }
+        graph[encode] = {"class_type": "VAEEncode", "inputs": {"pixels": [scale, 0], "vae": [vae, 0]}}
+        graph[ref_pos] = {"class_type": "ReferenceLatent", "inputs": {"conditioning": positive, "latent": [encode, 0]}}
+        graph[ref_neg] = {"class_type": "ReferenceLatent", "inputs": {"conditioning": negative, "latent": [encode, 0]}}
+        positive, negative = [ref_pos, 0], [ref_neg, 0]
+        first = first or [scale, 0]
+    graph[guider]["inputs"]["positive"], graph[guider]["inputs"]["negative"] = positive, negative
+    if size_from_first and first:
+        set_size(graph, first)
+    return first
+
+
+def set_size(graph: dict, image: list) -> None:
+    """The picture made takes `image`'s size: its width and height go to every workflow node that takes them."""
+    graph[SIZE_NODE] = {"class_type": "GetImageSize", "inputs": {"image": image}}
+    for nid, node in graph.items():
+        if nid.isdigit() and int(nid) >= BASE:
+            continue  # lcode's own nodes keep their sizes
+        inputs = node.get("inputs", {})
+        for key, out in (("width", 0), ("height", 1)):
+            if key in inputs and not isinstance(inputs[key], list):
+                inputs[key] = [SIZE_NODE, out]
+
+
+def scale_to(graph: dict, image: list, megapixels: float) -> list:
+    nid = str(BASE + 301)
+    graph[nid] = {
+        "class_type": "ImageScaleToTotalPixels",
+        "inputs": {"image": image, "upscale_method": "lanczos", "megapixels": megapixels, "resolution_steps": 16},
+    }
+    return [nid, 0]
+
+
+def mask_from_file(graph: dict, mask_name: str) -> list:
+    """The user's mask image (white: change), at the picture's size, with a soft edge."""
+    if SIZE_NODE not in graph:
+        raise EditError("inpainting needs the picture at the original's size")
+    load, to_image, scale, blur, to_mask = (str(BASE + 200 + i) for i in range(5))
+    graph[load] = {"class_type": "LoadImageMask", "inputs": {"image": mask_name, "channel": "red"}}
+    graph[to_image] = {"class_type": "MaskToImage", "inputs": {"mask": [load, 0]}}
+    graph[scale] = {
+        "class_type": "ImageScale",
+        "inputs": {"image": [to_image, 0], "upscale_method": "bilinear", "width": [SIZE_NODE, 0],
+                   "height": [SIZE_NODE, 1], "crop": "disabled"},
+    }  # fmt: skip
+    graph[blur] = {"class_type": "ImageBlur", "inputs": {"image": [scale, 0], "blur_radius": 8, "sigma": 4.0}}
+    graph[to_mask] = {"class_type": "ImageToMask", "inputs": {"image": [blur, 0], "channel": "red"}}
+    return [to_mask, 0]
+
+
+def mask_scaled(graph: dict, mask: list, megapixels: float) -> list:
+    """A mask brought to the same size as an image scaled to `megapixels` (outpainting's border)."""
+    to_image, scale, to_mask = (str(BASE + 310 + i) for i in range(3))
+    graph[to_image] = {"class_type": "MaskToImage", "inputs": {"mask": mask}}
+    graph[scale] = {
+        "class_type": "ImageScaleToTotalPixels",
+        "inputs": {"image": [to_image, 0], "upscale_method": "bilinear", "megapixels": megapixels,
+                   "resolution_steps": 16},
+    }  # fmt: skip
+    graph[to_mask] = {"class_type": "ImageToMask", "inputs": {"image": [scale, 0], "channel": "red"}}
+    return [to_mask, 0]
+
+
+def sample_inside(graph: dict, image: list, mask: list) -> None:
+    """Start from the image itself and let the sampler change only what the mask covers."""
+    sampler = node_of(graph, "SamplerCustomAdvanced") or node_of(graph, "KSampler")
+    vae = node_of(graph, "VAELoader")
+    if sampler is None or vae is None:
+        raise EditError("this workflow can't paint inside a mask")
+    encode, masked = str(BASE + 400), str(BASE + 401)
+    graph[encode] = {"class_type": "VAEEncode", "inputs": {"pixels": image, "vae": [vae, 0]}}
+    graph[masked] = {"class_type": "SetLatentNoiseMask", "inputs": {"samples": [encode, 0], "mask": mask}}
+    graph[sampler]["inputs"]["latent_image"] = [masked, 0]
+
+
+def paste(graph: dict, destination: list, source: list, mask: list) -> None:
+    """The saved picture becomes `destination` with `source` pasted where the mask is white."""
+    save = save_node(graph)
+    nid = str(BASE + 500)
+    graph[nid] = {
+        "class_type": "ImageCompositeMasked",
+        "inputs": {"destination": destination, "source": source, "x": 0, "y": 0, "resize_source": False,
+                   "mask": mask},
+    }  # fmt: skip
+    graph[save]["inputs"]["images"] = [nid, 0]
+
+
+def inpaint(graph: dict, original: list, mask_name: str) -> None:
+    """Change only where the mask image is white: sampled there from the original, then pasted into it."""
+    mask = mask_from_file(graph, mask_name)
+    sample_inside(graph, original, mask)
+    paste(graph, original, graph[save_node(graph)]["inputs"]["images"], mask)
+
+
+def pad_canvas(graph: dict, image: list, pads: tuple[int, int, int, int]) -> tuple[list, list]:
+    """Outpainting's canvas, bigger by `pads` (left, top, right, bottom); (canvas, mask of the new border).
+
+    The border starts as a blurred, stretched copy of the image rather than flat grey: a fast model keeps a little of
+    what it starts from, and grey would show.
+    """
+    pad, size, stretched, blurred, canvas = (str(BASE + 300 + i) for i in (0, 2, 3, 4, 5))
+    left, top, right, bottom = pads
+    graph[pad] = {
+        "class_type": "ImagePadForOutpaint",
+        "inputs": {"image": image, "left": left, "top": top, "right": right, "bottom": bottom, "feathering": 48},
+    }
+    graph[size] = {"class_type": "GetImageSize", "inputs": {"image": [pad, 0]}}
+    graph[stretched] = {
+        "class_type": "ImageScale",
+        "inputs": {"image": image, "upscale_method": "bilinear", "width": [size, 0], "height": [size, 1],
+                   "crop": "disabled"},
+    }  # fmt: skip
+    graph[blurred] = {"class_type": "ImageBlur", "inputs": {"image": [stretched, 0], "blur_radius": 31, "sigma": 10.0}}
+    graph[canvas] = {
+        "class_type": "ImageCompositeMasked",
+        "inputs": {"destination": [blurred, 0], "source": image, "x": left, "y": top, "resize_source": False},
+    }
+    return [canvas, 0], [pad, 1]
+
+
+def outpaint(graph: dict, canvas_scaled: list, border: list, megapixels: float) -> None:
+    """Fill only the new border, sampled around the original, and keep the original exactly as it was."""
+    mask = mask_scaled(graph, border, megapixels)
+    sample_inside(graph, canvas_scaled, mask)
+    invert = str(BASE + 501)
+    graph[invert] = {"class_type": "InvertMask", "inputs": {"mask": mask}}
+    paste(graph, graph[save_node(graph)]["inputs"]["images"], canvas_scaled, [invert, 0])
+
+
+# ----------------------------------------------------------------------------- sizes and arguments
+
+
+def image_size(path: Path) -> tuple[int, int]:
+    """Width and height from a PNG, JPEG or WebP file's header."""
+    data = path.read_bytes()[:65536]
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return struct.unpack(">II", data[16:24])
+    if data[:2] == b"\xff\xd8":
+        i = 2
+        while i + 9 < len(data):
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            length = struct.unpack(">H", data[i + 2 : i + 4])[0]
+            if marker in (0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF):
+                h, w = struct.unpack(">HH", data[i + 5 : i + 9])
+                return w, h
+            i += 2 + length
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        kind = data[12:16]
+        if kind == b"VP8X":
+            return int.from_bytes(data[24:27], "little") + 1, int.from_bytes(data[27:30], "little") + 1
+        if kind == b"VP8 ":
+            w, h = struct.unpack("<HH", data[26:30])
+            return w & 0x3FFF, h & 0x3FFF
+        if kind == b"VP8L":
+            bits = int.from_bytes(data[21:25], "little")
+            return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+    raise EditError(f"can't read the size of {path.name}: use a PNG, JPEG or WebP image")
+
+
+def pads_for_ratio(width: int, height: int, ratio: str) -> tuple[int, int, int, int]:
+    """Borders that bring the image to an aspect ratio (a:b), split evenly, in steps of 8 pixels."""
+    m = re.fullmatch(r"(\d{1,2}):(\d{1,2})", ratio)
+    if not m or not int(m.group(1)) or not int(m.group(2)):
+        raise EditError("the shape to extend to is a ratio, e.g. --ar 16:9")
+    a, b = int(m.group(1)), int(m.group(2))
+    if abs(width / height - a / b) < 0.01:
+        raise EditError(f"it's {a}:{b} already: choose another shape, or --left/--right/--top/--bottom pixels")
+    if width / height < a / b:  # wider
+        extra = round(height * a / b) - width
+        left = (extra // 2) // 8 * 8
+        return left, 0, (extra - left + 7) // 8 * 8, 0
+    extra = round(width * b / a) - height
+    top = (extra // 2) // 8 * 8
+    return 0, top, 0, (extra - top + 7) // 8 * 8
+
+
+EXTEND_FLAG = re.compile(r"--(left|top|right|bottom)\s+(\d+)")
+
+
+def parse_extend(text: str, width: int, height: int) -> tuple[tuple[int, int, int, int], str]:
+    """`/extend` arguments: --ar 16:9, or --left/--top/--right/--bottom pixels; the rest describes the new part."""
+    sides = {k: int(v) for k, v in EXTEND_FLAG.findall(text)}
+    text = EXTEND_FLAG.sub(" ", text)
+    ratio = re.search(r"--(?:ar|size)\s+(\S+)", text)
+    text = re.sub(r"--(?:ar|size)\s+\S+", " ", text)
+    if ratio and sides:
+        raise EditError("extend by a shape (--ar 16:9) or by sides (--left 256), not both")
+    if ratio:
+        from lcode.imageopts import SIZES
+
+        pads = pads_for_ratio(width, height, SIZES.get(ratio.group(1), ratio.group(1)))
+    elif sides:
+        pads = tuple((sides.get(k, 0) + 7) // 8 * 8 for k in ("left", "top", "right", "bottom"))
+        if any(p > 2048 for p in pads):
+            raise EditError("a side grows by at most 2048 pixels")
+    else:
+        pads = pads_for_ratio(width, height, "16:9" if width <= height * 16 / 9 - 1 else "1:1")
+    return pads, " ".join(text.split())
+
+
+REFERENCE = re.compile(r'(?:^|(?<=\s))@(#\d+|"[^"]+"|\S+)')
+
+
+def split_references(text: str) -> tuple[str, list[str]]:
+    """The prompt without its @references, and the references (#3, or file paths) in order."""
+    refs = [m.group(1).strip('"') for m in REFERENCE.finditer(text)]
+    return " ".join(REFERENCE.sub(" ", text).split()), refs
+
+
+def is_image(path: Path) -> bool:
+    return path.suffix.lower() in IMAGE_TYPES

lcode/imageopts.py

@@ -13,6 +13,7 @@ from dataclasses import asdict, dataclass, replace
 
 QUALITIES = ("fast", "balanced", "best")
 MAX_COUNT = 8
+MAX_SECONDS = 8  # video: longer clips need more memory than a laptop GPU has, and models drift
 SIZES = {  # names for aspect ratios
     "square": "1:1",
     "portrait": "3:4",
@@ -46,6 +47,8 @@ ALIASES = {
     "no": "negative",
     "negative": "negative",
     "style": "style",
+    "seconds": "seconds",
+    "duration": "seconds",
 }
 FLAG = re.compile(r"(?:^|\s)--?(" + "|".join(sorted(ALIASES, key=len, reverse=True)) + r")\b(?=[\s=]|$)")
 DIMENSIONS = re.compile(r"^(\d{2,4})\s*[x×]\s*(\d{2,4})$")
@@ -64,10 +67,13 @@ class Options:
     quality: str = "balanced"
     negative: str = ""
     style: str = ""
+    seconds: float = 5.0  # video only
 
-    def describe(self) -> str:
+    def describe(self, video: bool = False) -> str:
         seed = "random" if self.seed is None else str(self.seed)
         parts = [f"n={self.n}", f"size={self.size}", f"seed={seed}", f"quality={self.quality}"]
+        if video:
+            parts.append(f"seconds={self.seconds:g}")
         if self.style:
             parts.append(f"style={self.style}")
         if self.negative:
@@ -92,7 +98,7 @@ def set_values(options: Options, values: dict[str, object]) -> Options:
     for raw_key, raw in values.items():
         key = ALIASES.get(str(raw_key).lower().lstrip("-"))
         if key is None:
-            raise OptionError(f"unknown option {raw_key!r}: use n, ar (or size), seed, quality, style or no")
+            raise OptionError(f"unknown option {raw_key!r}: use n, ar (or size), seed, quality, style, no or seconds")
         value = str(raw).strip() if raw is not None else ""
         if key == "n":
             if not value.isdigit() or not 1 <= int(value) <= MAX_COUNT:
@@ -120,6 +126,14 @@ def set_values(options: Options, values: dict[str, object]) -> Options:
                 raise OptionError(f"style is one of {', '.join(STYLES)} (or none)")
         elif key == "negative":
             out.negative = "" if value.lower() in ("none", "off") else value
+        elif key == "seconds":
+            try:
+                seconds = float(value.rstrip("s"))
+            except ValueError:
+                seconds = 0
+            if not 1 <= seconds <= MAX_SECONDS:
+                raise OptionError(f"seconds is how long a video is: 1 to {MAX_SECONDS}")
+            out.seconds = seconds
     return out
 
 
@@ -203,5 +217,10 @@ def replace_seed(options: Options, n: int | None = None) -> Options:
     return replace(options, seed=None, n=n or options.n)
 
 
+def frames(seconds: float, fps: int) -> int:
+    """Frames for a clip: a multiple of 4 plus 1, as video models that compress time 4 to 1 need."""
+    return max(1, round(seconds * fps / 4)) * 4 + 1
+
+
 def styled(prompt: str, style: str) -> str:
     return f"{prompt}, {STYLES[style]}" if style else prompt