@kolbo/mcp 1.112.0 → 1.112.2

package/skill/scripts/micro-drama/burn.py

@@ -0,0 +1,121 @@
+"""Burn captions (and an optional hook) into a finished cut with libass. Audio is copied untouched.
+
+usage:
+  python burn.py social <in.mp4> <words.srt> <out.mp4> [--hook "Line one|Line two"] [--hook-dy 0] [--font NAME] [--fontsdir DIR]
+  python burn.py film   <in.mp4> <words.srt> <out.mp4> [--font NAME] [--fontsdir DIR]
+
+words.srt = one-word-per-cue SRT from Kolbo transcribe_audio (word_by_word_srt_url) of THIS file, corrected
+against the script's words (keep the timings, fix only mishears).
+social: word-pop captions, max 3 words per line, the spoken word in yellow, each word one frame early, sitting
+        just above the bottom 35% platform UI band; hook = two lines in a white box for exactly 0-3 s, at the waist,
+        right above the captions. All text stays inside the centre 82% so the right-side buttons never cover it.
+film:   plain subtitles for the full episode page - max 4 words per row, 2 rows, low in frame, soft shadow.
+Also writes <out>.ass next to the output for inspection.
+"""
+import argparse
+import os
+import subprocess
+
+from media import probe, srt_words
+
+YELLOW, WHITE, BLACK = "&H003DE2FF", "&H00FFFFFF", "&H00000000"
+
+
+def ts(t):
+    t = max(t, 0)
+    return f"{int(t // 3600)}:{int(t % 3600 // 60):02d}:{t % 60:05.2f}"
+
+
+def lines_of(words, max_words, pause=0.6):
+    out, cur = [], []
+    for w in words:
+        if cur and (len(cur) >= max_words or w[1] - cur[-1][2] > pause or cur[-1][0][-1:] in ",.?!"):
+            out.append(cur)
+            cur = []
+        cur.append(w)
+    return out + ([cur] if cur else [])
+
+
+def build(mode, video, srt, hook, hook_dy, font):
+    info = probe(video)
+    W, H, frame = info["w"], info["h"], 1 / info["fps"]
+    margin = int(W * 0.09)
+    cap_y = int(H * 0.65) - int(H * 0.02)            # just above the bottom 35% UI band
+    words = srt_words(srt)
+    head = (f"[Script Info]\nScriptType: v4.00+\nPlayResX: {W}\nPlayResY: {H}\nWrapStyle: 2\n\n[V4+ Styles]\n"
+            "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, "
+            "Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, "
+            "MarginR, MarginV, Encoding\n")
+    ev = "\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n"
+    if mode == "film":
+        size = int(W * 0.063)
+        head += (f"Style: Sub,{font},{size},{WHITE},{WHITE},{BLACK},&H80000000,0,0,0,0,100,100,0,0,1,1.5,2,2,"
+                 f"{margin},{margin},{int(H * 0.08)},1\n")
+        for ln in lines_of(words, 8):
+            text = " ".join(w[0] for w in ln)
+            parts = text.split()
+            if len(parts) > 4:
+                text = " ".join(parts[:len(parts) // 2 + len(parts) % 2]) + "\\N" + " ".join(parts[len(parts) // 2 + len(parts) % 2:])
+            ev += f"Dialogue: 0,{ts(ln[0][1] - frame)},{ts(ln[-1][2] + 0.2)},Sub,,0,0,0,,{text}\n"
+        return head + ev
+    cap = int(W * 0.07)
+    head += (f"Style: Cap,{font},{cap},{WHITE},{WHITE},{BLACK},&H00000000,1,0,0,0,100,100,0,0,1,{cap * 0.12:.1f},0,2,"
+             f"{margin},{margin},{H - cap_y},1\n")
+    head += (f"Style: Hook,{font},10,{BLACK},{BLACK},{BLACK},{BLACK},1,0,0,0,100,100,0,0,1,0,0,5,0,0,0,1\n"
+             f"Style: Box,{font},10,{WHITE},{WHITE},{WHITE},{WHITE},0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1\n")
+    caps = []
+    for ln in lines_of(words, 3):
+        for k, (w, a, b) in enumerate(ln):
+            end = ln[k + 1][1] if k + 1 < len(ln) else b + 0.15
+            text = " ".join(("{\\c" + YELLOW + "}" + x + "{\\c" + WHITE + "}") if j == k else x
+                            for j, (x, _, _) in enumerate(ln))
+            caps.append([a - frame, end - frame, text])
+    for k in range(len(caps) - 1):  # never two caption states on screen at once (libass stacks them)
+        caps[k][1] = max(min(caps[k][1], caps[k + 1][0]), caps[k][0] + frame)
+    for a, b, text in caps:
+        ev += f"Dialogue: 1,{ts(a)},{ts(b)},Cap,,0,0,0,,{text}\n"
+    if hook:
+        lines = hook.split("|")
+        # ponytail: box width estimated at 0.6 x font size per character (bold sans); measure with a font
+        # library if a hook font renders much wider.
+        size = min(W * 0.068, (W * 0.82 - W * 0.07) / (0.6 * max(len(x) for x in lines)))
+        pad, r = size * 0.5, size * 0.45
+        bw = 0.6 * size * max(len(x) for x in lines) + 2 * pad
+        bh = size * 1.2 * len(lines) + 2 * pad
+        bottom = cap_y - cap * 1.3 - hook_dy           # sits right above the caption line
+        x0, y0 = (W - bw) / 2, bottom - bh
+        path = (f"m {r:.0f} 0 l {bw - r:.0f} 0 b {bw - .45 * r:.0f} 0 {bw:.0f} {.45 * r:.0f} {bw:.0f} {r:.0f} "
+                f"l {bw:.0f} {bh - r:.0f} b {bw:.0f} {bh - .45 * r:.0f} {bw - .45 * r:.0f} {bh:.0f} {bw - r:.0f} {bh:.0f} "
+                f"l {r:.0f} {bh:.0f} b {.45 * r:.0f} {bh:.0f} 0 {bh - .45 * r:.0f} 0 {bh - r:.0f} "
+                f"l 0 {r:.0f} b 0 {.45 * r:.0f} {.45 * r:.0f} 0 {r:.0f} 0")
+        ev += f"Dialogue: 2,{ts(0)},{ts(3.0)},Box,,0,0,0,,{{\\an7\\pos({x0:.0f},{y0:.0f})\\p1}}{path}{{\\p0}}\n"
+        ev += (f"Dialogue: 3,{ts(0)},{ts(3.0)},Hook,,0,0,0,,{{\\an5\\pos({W / 2:.0f},{y0 + bh / 2:.0f})\\fs{size:.0f}}}"
+               + "\\N".join(lines) + "\n")
+    return head + ev
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("mode", choices=["social", "film"])
+    p.add_argument("video")
+    p.add_argument("srt")
+    p.add_argument("out")
+    p.add_argument("--hook", default="")
+    p.add_argument("--hook-dy", type=int, default=0, help="move the hook down by N pixels if it covers a face or body")
+    p.add_argument("--font", default="Montserrat ExtraBold")
+    p.add_argument("--fontsdir", default="")
+    a = p.parse_args()
+    ass = os.path.abspath(a.out) + ".ass"
+    open(ass, "w", encoding="utf-8").write(build(a.mode, a.video, a.srt, a.hook, a.hook_dy, a.font))
+    # libass path escaping is fragile on Windows: run from the .ass folder with a bare file name.
+    flt = f"subtitles={os.path.basename(ass)}" + (f":fontsdir={a.fontsdir}" if a.fontsdir else "")
+    tmp = os.path.abspath(a.out) + ".part.mp4"
+    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", os.path.abspath(a.video), "-vf", flt, "-c:v", "libx264",
+                    "-crf", "16", "-preset", "medium", "-pix_fmt", "yuv420p", "-c:a", "copy", "-movflags", "+faststart",
+                    tmp], check=True, cwd=os.path.dirname(ass))
+    os.replace(tmp, os.path.abspath(a.out))
+    print("->", a.out)
+
+
+if __name__ == "__main__":
+    main()

package/skill/scripts/micro-drama/cut.py

@@ -0,0 +1,107 @@
+"""Build the tight cut from final clips with exact frames, L/J-cuts and smooth sound seams. Levels never change.
+
+usage: python cut.py <cut.json>
+cut.json:
+{
+  "out": "final/ep01-tight.mp4",
+  "xfade": 0.3,
+  "segments": [
+    {"file": "final/ep01-part1.mp4", "start": 0.0, "end": 9.4},
+    {"file": "final/ep01-part1.mp4", "start": 11.2, "end": 14.0, "lcut": 0.3},
+    {"file": "final/ep01-part2.mp4", "start": 0.2, "end": 6.1, "zoom": 1.5, "y": 0.2, "flip": false, "jcut": 0}
+  ]
+}
+- start/end: seconds on that file. In/out points within 0.15 s of a shot change are moved 1.5 frames inside the
+  shot, so no frame of the neighbouring shot flashes in.
+- lcut: this shot's PICTURE comes in that many seconds early over the end of the previous line (L-cut).
+- jcut: this shot's SOUND starts that many seconds early under the previous picture (J-cut).
+- zoom/y: punch-in (1.5 = 150%) anchored at y (0 top, 0.5 centre) for a jump inside one shot.
+- flip: horizontal mirror to fix a 180-degree break. Check every one-sided detail (scar, parting, ring, text) first.
+- Seams borrow `xfade` s of the incoming shot's own sound and crossfade it, so room tone never jumps.
+  Contiguous segments of the same file butt-join with no borrow.
+"""
+import bisect
+import json
+import os
+import subprocess
+import sys
+
+from media import frame_pts, probe, shot_changes
+
+
+def snap(s, e, changes, fps):
+    for c in changes:
+        if abs(e - c) < 0.15:
+            e = c - 1.5 / fps
+        if abs(s - c) < 0.15:
+            s = c + 1.5 / fps
+    return s, e
+
+
+def main(spec_path):
+    spec = json.load(open(spec_path, encoding="utf-8"))
+    base = os.path.dirname(os.path.abspath(spec_path))
+    path = lambda x: x if os.path.isabs(x) else os.path.join(base, x)
+    X = spec.get("xfade", 0.3)
+    cache, segs = {}, []
+    for raw in spec["segments"]:
+        f = path(raw["file"])
+        if f not in cache:
+            info = probe(f)
+            cache[f] = (info, shot_changes(f), frame_pts(f))
+        info, changes, pts = cache[f]
+        fps = info["fps"]
+        s, e = snap(raw["start"], raw["end"], changes, fps)
+        contiguous = bool(segs) and segs[-1]["file"] == f and abs(segs[-1]["raw_end"] - raw["start"]) < 1e-6
+        if contiguous:  # one shared cut point, mid-frame, so no word repeats
+            c = min(changes, key=lambda c: abs(c - raw["start"]), default=raw["start"])
+            s = c - 0.5 / fps if abs(c - raw["start"]) < 0.15 else raw["start"]
+            segs[-1]["end"] = s
+        # Snap to real frame times so audio length == frame count (lip sync never drifts).
+        k = bisect.bisect_left(pts, s - 1e-4)
+        s = pts[min(k, len(pts) - 1)]
+        k = bisect.bisect_left(pts, e - 1e-4)
+        e = pts[max(k - 1, 0)] + 1 / fps
+        segs.append({"file": f, "start": s, "end": e, "raw_end": raw["end"], "fps": fps, "w": info["w"], "h": info["h"],
+                     "zoom": raw.get("zoom", 1), "y": raw.get("y", 0.5), "flip": raw.get("flip", False),
+                     "lcut": round(raw.get("lcut", 0) * fps) / fps, "jcut": round(raw.get("jcut", 0) * fps) / fps,
+                     "contiguous": contiguous})
+    ins, fc, vl = [], "", ""
+    for i, sg in enumerate(segs):
+        nxt = segs[i + 1] if i + 1 < len(segs) else {"lcut": 0, "jcut": 0}
+        ins += ["-i", sg["file"]]
+        z = sg["zoom"]
+        crop = (f",crop=iw/{z}:ih/{z}:(iw-iw/{z})/2:(ih-ih/{z})*{sg['y']},scale={sg['w']}:{sg['h']}:flags=lanczos"
+                if z != 1 else "")
+        fc += (f"[{i}:v]trim={sg['start'] - 0.002}:{sg['end'] - nxt['lcut'] - 0.002},setpts=PTS-STARTPTS{crop}"
+               f"{',hflip' if sg['flip'] else ''},setsar=1[v{i}];")
+        a0 = sg["start"] + sg["lcut"] - sg["jcut"] - (X if i and not sg["contiguous"] else 0)
+        if a0 < 0:
+            sys.exit(f"segment {i} needs {X + sg['jcut']:.2f}s of sound before its in-point; start it later")
+        fc += f"[{i}:a]atrim={a0}:{sg['end'] - nxt['jcut']},asetpts=PTS-STARTPTS[a{i}];"
+        vl += f"[v{i}]"
+    fc += f"{vl}concat=n={len(segs)}:v=1:a=0[v];"
+    prev = "a0"
+    for i in range(1, len(segs)):
+        join = "concat=n=2:v=0:a=1" if segs[i]["contiguous"] else f"acrossfade=d={X}:c1=tri:c2=tri"
+        fc += f"[{prev}][a{i}]{join}[x{i}];"
+        prev = f"x{i}"
+    out = path(spec["out"])
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    tmp = out + ".part.mp4"
+    subprocess.run(["ffmpeg", "-v", "error", "-y", *ins, "-filter_complex", fc.rstrip(";"), "-map", "[v]",
+                    "-map", f"[{prev}]", "-c:v", "libx264", "-crf", "16", "-preset", "medium", "-pix_fmt", "yuv420p",
+                    "-c:a", "aac", "-b:a", "256k", "-movflags", "+faststart", tmp], check=True)
+    os.replace(tmp, out)
+    t = 0.0
+    for i, sg in enumerate(segs):
+        nxt = segs[i + 1]["lcut"] if i + 1 < len(segs) else 0
+        print(f"{t:7.2f}  {os.path.basename(sg['file'])} {sg['start']:.3f}-{sg['end'] - nxt:.3f}"
+              + (f" zoom {sg['zoom']}" if sg["zoom"] != 1 else "") + (" flip" if sg["flip"] else "")
+              + (f" L {sg['lcut']:.2f}" if sg["lcut"] else "") + (f" J {sg['jcut']:.2f}" if sg["jcut"] else ""))
+        t += sg["end"] - nxt - sg["start"]
+    print(f"total {t:.2f}s -> {out}")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1])

package/skill/scripts/micro-drama/flash_check.py

@@ -0,0 +1,20 @@
+"""Find one-frame flashes and too-short shots in a cut. Exit code 1 if anything is found.
+usage: python flash_check.py <video> [min_shot_s=1.2]"""
+import sys
+
+import numpy as np
+
+from media import frame_diffs, probe
+
+video = sys.argv[1]
+min_shot = float(sys.argv[2]) if len(sys.argv) > 2 else 1.2
+fps = probe(video)["fps"]
+d = frame_diffs(video, fps)
+cuts = [int(i) for i in np.where(d > 18)[0] if i > 0]
+bad = 0
+for a, b in zip(cuts, cuts[1:]):
+    if (b - a) / fps < min_shot:
+        print(f"short shot {a / fps:.3f}-{b / fps:.3f}s ({b - a} frames)")
+        bad += 1
+print(f"{len(cuts)} cuts checked, {bad} problems")
+sys.exit(1 if bad else 0)

package/skill/scripts/micro-drama/media.py

@@ -0,0 +1,54 @@
+"""Shared ffmpeg helpers for the micro-drama edit scripts. Needs ffmpeg/ffprobe on PATH and numpy."""
+import json
+import subprocess
+
+import numpy as np
+
+
+def probe(video):
+    out = subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                                   "stream=width,height,avg_frame_rate:format=duration", "-of", "json", video])
+    d = json.loads(out)
+    s = d["streams"][0]
+    num, den = s["avg_frame_rate"].split("/")
+    return {"w": s["width"], "h": s["height"], "fps": float(num) / float(den or 1),
+            "duration": float(d["format"]["duration"])}
+
+
+def frame_pts(video):
+    """Real presentation time of every video frame, sorted."""
+    out = subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                                   "packet=pts_time", "-of", "csv=p=0", video], text=True)
+    return sorted(float(x) for x in out.split() if x and x != "N/A")
+
+
+def gray_frames(video, fps):
+    raw = subprocess.check_output(["ffmpeg", "-v", "error", "-i", video, "-vf",
+                                   f"fps={fps},scale=90:160,format=gray", "-f", "rawvideo", "-"])
+    return np.frombuffer(raw, np.uint8).reshape(-1, 160, 90).astype(np.int16)
+
+
+def frame_diffs(video, fps):
+    f = gray_frames(video, fps)
+    return np.concatenate([[0], np.abs(np.diff(f, axis=0)).mean(axis=(1, 2))])
+
+
+def shot_changes(video, threshold=18):
+    """Time of the first frame of every new shot (hard cuts only)."""
+    fps = probe(video)["fps"]
+    d = frame_diffs(video, fps)
+    return [round(i / fps, 4) for i in np.where(d > threshold)[0] if i > 0]
+
+
+def srt_words(path):
+    """[(word, start, end)] from a one-word-per-cue SRT (Kolbo transcribe_audio word_by_word_srt_url)."""
+    def sec(t):
+        h, m, s = t.replace(",", ".").split(":")
+        return int(h) * 3600 + int(m) * 60 + float(s)
+    words = []
+    for block in open(path, encoding="utf-8").read().strip().split("\n\n"):
+        lines = block.strip().splitlines()
+        if len(lines) >= 3 and "-->" in lines[1]:
+            a, b = (x.strip() for x in lines[1].split("-->"))
+            words.append((" ".join(lines[2:]).strip(), sec(a), sec(b)))
+    return words

package/skill/scripts/micro-drama/pace_report.py

@@ -0,0 +1,76 @@
+"""Pace report: find dead air (no speech, little motion) in a joined episode. Candidates only - a human or the
+agent judges each one against the script beat (keep a look that lands, cut a stare that re-establishes nothing).
+
+usage: python pace_report.py <joined.mp4> <words.srt> [out.json]
+words.srt = one-word-per-cue SRT from Kolbo transcribe_audio (word_by_word_srt_url).
+Writes proposed keep-segments [[start, end], ...]; a piece whose removed gap has no real shot change gets
+[start, end, 1.5, 0.2] (1.5x punch-in so the jump reads as a new angle).
+"""
+import json
+import sys
+
+import numpy as np
+
+from media import frame_diffs, probe, shot_changes, srt_words
+
+STEP = 1 / 8      # analysis resolution (s)
+MAX_DEAD = 0.6    # dead air longer than this is a trim candidate
+LEAD_IN = 0.25    # keep before a line
+HOLD = 0.45       # keep after a line (the reaction beat)
+MIN_PIECE = 0.5
+
+
+def main(video, srt, out=None):
+    dur = probe(video)["duration"]
+    n = int(dur / STEP)
+    t = np.arange(n) * STEP
+    m = frame_diffs(video, 1 / STEP)[:n]
+    m = np.pad(m, (0, n - len(m)))
+    shots = shot_changes(video)
+    for c in shots:  # a hard cut is a spike, not action
+        m[max(int(c / STEP) - 1, 0):int(c / STEP) + 2] = 0
+    on = max(4.0, float(np.percentile(m, 70)))
+    keep = np.zeros(n, bool)
+    for _, a, b in srt_words(srt):
+        keep[(t >= a - LEAD_IN) & (t < b + HOLD)] = True
+    keep |= np.convolve(m > on, np.ones(4), "same") > 0
+    keep[t < 0.5] = True          # hook frame
+    keep[t > dur - 1.0] = True    # cliff hold
+    i = 0
+    while i < n:                  # short gaps are breath, keep them
+        if keep[i]:
+            i += 1
+            continue
+        j = i
+        while j < n and not keep[j]:
+            j += 1
+        if (j - i) * STEP <= MAX_DEAD:
+            keep[i:j] = True
+        i = j
+    segs, i = [], 0
+    while i < n:
+        if not keep[i]:
+            i += 1
+            continue
+        j = i
+        while j < n and keep[j]:
+            j += 1
+        s, e = round(float(t[i]), 3), round(min(float(t[j - 1]) + STEP, dur), 3)
+        if e - s >= MIN_PIECE:
+            segs.append([s, e])
+        i = j
+    for k in range(1, len(segs)):
+        a, b = segs[k - 1][1], segs[k][0]
+        if not any(a - 0.1 <= c <= b + 0.1 for c in shots) and len(segs[k - 1]) == 2:
+            segs[k] += [1.5, 0.2]
+    new = sum(s[1] - s[0] for s in segs)
+    print(f"{video}: {dur:.1f}s -> {new:.1f}s ({len(segs) - 1} trim candidates)")
+    for k in range(1, len(segs)):
+        a, b = segs[k - 1][1], segs[k][0]
+        print(f"  trim {a:6.2f}-{b:6.2f} ({b - a:.2f}s){'  + 1.5x punch-in' if len(segs[k]) > 2 else ''}")
+    if out:
+        json.dump(segs, open(out, "w"), indent=1)
+
+
+if __name__ == "__main__":
+    main(*sys.argv[1:4])

package/skill/scripts/micro-drama/shot_map.py

@@ -0,0 +1,38 @@
+"""Shot map: list every shot of a joined episode and save one contact sheet (first / middle / last frame per shot).
+
+usage: python shot_map.py <joined.mp4> <out_dir>
+Writes <out_dir>/shots.json ([{n, start, end}]) and <out_dir>/shot-NN.jpg strips. Look at every strip and note,
+per shot: who is frame-left / frame-right, where each person looks, shot size. That is the shot map the cut uses.
+"""
+import json
+import os
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+from media import probe, shot_changes
+
+
+def main(video, out_dir):
+    os.makedirs(out_dir, exist_ok=True)
+    info = probe(video)
+    edges = [0.0] + shot_changes(video) + [info["duration"]]
+    shots = [{"n": i + 1, "start": round(a, 3), "end": round(b, 3)} for i, (a, b) in enumerate(zip(edges, edges[1:]))]
+
+    def strip(s):
+        a, b = s["start"], s["end"]
+        times = [a + 0.05, (a + b) / 2, max(b - 0.08, a + 0.05)]
+        inputs = sum((["-ss", f"{t:.3f}", "-i", video] for t in times), [])
+        subprocess.run(["ffmpeg", "-v", "error", "-y", *inputs, "-filter_complex",
+                        "".join(f"[{i}:v]scale=270:-2,trim=end_frame=1[s{i}];" for i in range(3)) + "[s0][s1][s2]hstack=3",
+                        "-frames:v", "1", os.path.join(out_dir, f"shot-{s['n']:02d}.jpg")], check=True)
+
+    with ThreadPoolExecutor(os.cpu_count()) as pool:
+        list(pool.map(strip, shots))
+    json.dump(shots, open(os.path.join(out_dir, "shots.json"), "w"), indent=1)
+    for s in shots:
+        print(f"shot {s['n']:2d}  {s['start']:7.2f}-{s['end']:7.2f}  ({s['end'] - s['start']:.2f}s)")
+
+
+if __name__ == "__main__":
+    main(*sys.argv[1:3])

package/src/apps/index.js

@@ -328,7 +328,9 @@ async function modelCatalog(client) {
         ? m.supported_aspect_ratios
         : (Array.isArray(m.supportedAspectRatios) ? m.supportedAspectRatios : []);
       const aspectsByType = m.supported_aspect_ratios_by_type || m.supportedAspectRatiosByType || null;
-      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types, aspects, aspectsByType };
+      // images_per_request: fixed outputs per call (Midjourney = 4, whatever num_images says).
+      const ipr = Number(m.images_per_request || m.imagesPerRequest) || 1;
+      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types, aspects, aspectsByType, ipr };
       all.push(info);
       // Display names collide across variants ("Nano Banana 2" names both the
       // t2i model and its editing sibling) — on collision keep the model with

package/src/index.js

@@ -83,6 +83,7 @@ const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
 const { registerAudioStemTools } = require('./tools/audio_stems');
 const { registerAnalyzeTools } = require('./tools/analyze');
+const { registerVideoInspectionTools } = require('./tools/video_inspection');
 const { registerBlenderTools } = require('./tools/blender');
 const { registerAdobeTools } = require('./tools/adobe');
 const { registerResolveTools } = require('./tools/resolve');
@@ -200,6 +201,7 @@ function createServer(opts = {}) {
   registerTrendTools(server, client);
   registerMorphiousStyleTools(server, client);
   registerAnalyzeTools(server, client, toolOptions);
+  registerVideoInspectionTools(server, client);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);

package/src/toolAnnotations.js

@@ -9,6 +9,7 @@
  */
 
 const READ_ONLY = [
+  'get_video_inspection',
   'get_flow_schema', 'list_flow_sessions', 'get_flow_session', 'validate_flow_session',
   'estimate_flow_run', 'get_flow_run', 'list_flow_runs',
   'list_morphious_styles',
@@ -40,7 +41,9 @@ const READ_ONLY = [
   'create_music_composition_plan',
 ];
 
-const OPEN_WORLD_READ_ONLY = [
+const OPEN_WORLD_READ_ONLY = [
+  // Reads public source media into private ephemeral scratch evidence, no library writes.
+  'prepare_video_inspection', 'inspect_video',
   'blender_list_sessions', 'blender_get_scene', 'blender_search_docs',
   'blender_get_command_status',
   'adobe_list_sessions', 'adobe_get_project', 'adobe_get_timeline', 'adobe_get_command_status',
@@ -100,7 +103,8 @@ const DESTRUCTIVE_WRITE = [
   'chat_send_message', 'generate_character_sheet',
   'acquire_clean_music_track', 'import_music_track_to_library',
   'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
-  'analyze_video',
+  'analyze_video',
+  'analyze_video_evidence', 'transcribe_video_evidence', 'cancel_video_inspection',
 
   // Deletes and whole-value replacement updates are conservatively destructive.
   'delete_voice', 'update_visual_dna', 'delete_visual_dna', 'delete_visual_dna_folder',

package/src/tools/_shared.js

@@ -54,7 +54,8 @@ const LOCAL_FILE_ROUTING =
 // where the model would read it, see no filesystem, and tell the user Kolbo
 // cannot take their file at all. attachFileInputHints() below appends the route
 // that actually works for the current transport, so the refusal never happens.
-const FILE_INPUT_TOOLS = [
+const FILE_INPUT_TOOLS = [
+  'prepare_video_inspection',
   'generate_image', 'generate_image_edit', 'generate_creative_director',
   'generate_video', 'generate_video_from_image', 'generate_video_from_video',
   'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
@@ -901,6 +902,17 @@ function moodboardIds(settings) {
  *   poll_tool      widget-side status tool (default 'get_generation_status')
  *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
+// How many outputs the card should expect. A model with a fixed
+// images_per_request (Midjourney = 4) returns that many per generation
+// regardless of num_images, so 2 prompts are 8 images, not "2 images".
+async function outputCount(p) {
+  const info = p.model ? await modelInfo(p.client, p.model).catch(() => null) : null;
+  const ipr = info && info.ipr > 1 ? info.ipr : 0;
+  if (!ipr) return p.count || 1;
+  const gens = Array.isArray(p.generation_ids) && p.generation_ids.length ? p.generation_ids.length : 1;
+  return ipr * gens;
+}
+
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
   const chip = await modelChipFields(p.client, p.model, p.settings && p.settings.mode);
@@ -919,7 +931,7 @@ async function uiGenerating(p) {
     ...chip,
     ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
     prompt: p.prompt,
-    count: p.count || 1,
+    count: await outputCount(p),
     settings,
     visual_dnas: await resolveVisualDnas(p.client, settings.visual_dna_ids),
     moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
@@ -1023,7 +1035,7 @@ async function uiCompleted(p, textPayload, extraContent) {
     tool: p.tool,
     ...chip,
     prompt: p.prompt,
-    count: p.count || 1,
+    count: await outputCount(p),
     // Omitted entirely when the caller has none. A live generation card merges
     // an incoming status payload over its own state, so an empty-but-present
     // `settings` wiped the resolution / aspect / DNA chips off the finished

package/src/tools/generate.js

@@ -316,7 +316,7 @@ function registerGenerateTools(server, client, options = {}) {
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-2" (versatile, text rendering, multilingual) or "gpt-image-2" (photoreal, infographics). Call list_models type="text_to_img" to see all options and pick per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe(aspectRatioDescribe('1:1')),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
-      num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Note: some models (Midjourney etc.) have a fixed `images_per_request` and ignore this — check list_models.'),
+      num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Models with a fixed `images_per_request` in list_models IGNORE this: Midjourney ALWAYS returns 4 images per prompt (one call = 4 variations, billed as one request). So for "4 options" send ONE Midjourney prompt, never 4 calls or 4 entries in `prompts`; 2 prompts = 8 images.'),
       reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration only — does NOT embed reference pixels. Array of image URLs used to guide the look-and-feel of a brand-new generation. The model interprets the references and regenerates approximations conditioned on them. It will NOT copy pixels from these images into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** To embed a specific logo, icon, watermark, or asset pixel-accurately, use generate_image_edit with the asset in source_images. To EDIT an existing image, also use generate_image_edit.'),
       visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) for character / style / product / scene consistency. **Cap: pass at most `max_visual_dna` IDs from list_models — if the field is null/0 or `supports_visual_dna: false`, the model rejects DNA entirely (silently ignored in some paths).** How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). Practical implication: do NOT also write physical descriptors of the same subject in your own prompt — they will compete with the DNA description text. For pixel-accurate face anchoring of a specific person, prefer passing the DNA\'s reference image directly via source_images on generate_image_edit and OMIT visual_dna_ids. visual_dna_ids is best for style / scene / product DNAs and for soft consistency across a set.'),
       moodboard_id: z.string().optional().describe('Moodboard ID (from list_moodboards / get_moodboard) whose master_prompt and style_guide should be applied to this generation.'),

package/src/tools/video_inspection.js

@@ -0,0 +1,41 @@
+'use strict';
+const { z } = require('zod');
+const project = z.string().optional().describe('Authorized Kolbo project for billing; Act supplies its conversation project.');
+const id = z.string().uuid().describe('Owner-scoped inspection ID returned by prepare_video_inspection.');
+const text = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+
+// Additive tools. Source download and CPU-only measurements are free; provider calls
+// stay explicit and billed. Never put image base64 into the language model's text.
+function registerVideoInspectionTools(server, client) {
+  server.tool('prepare_video_inspection',
+    'Prepare a private source snapshot for adaptive video/audio investigation, including long recordings up to 2 GB. Streams the source once; returns promptly with preparing status. Poll get_video_inspection until ready. Accepts public direct media file URLs, not YouTube pages. Snapshot expires after two hours. No provider analysis or credits. Reuse the returned ID for frames, cuts and audio; refresh only when the URL content changed.',
+    { video_url: z.string().url(), refresh: z.boolean().optional(), project_id: project },
+    async ({ video_url, refresh }) => text(await client.post('/v1/analyze/video-inspections', { video_url, refresh })));
+  server.tool('get_video_inspection', 'Check source preparation, duration, streams, dimensions, source version and limits. Do not poll unchanged status in a tight loop.',
+    { inspection_id: id, project_id: project }, async ({ inspection_id }) => text(await client.get(`/v1/analyze/video-inspections/${inspection_id}`)));
+  server.tool('cancel_video_inspection', 'Stop preparation/extraction and expire your private snapshot. A paid provider request already accepted may still complete and be charged. Source media in the library is unchanged.',
+    { inspection_id: id, project_id: project }, async ({ inspection_id }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/cancel`, {})));
+  server.tool('inspect_video',
+    'Extract bounded evidence from a prepared recording. frames returns timestamped contact-sheet IMAGE blocks (up to12 frames,6 per sheet); frame returns one larger IMAGE. Choose explicit timestamps or evenly sampled range/frame_count. cuts measures candidate changes on a640px/8fps proxy and must be verified against nearby frames. audio/clip extracts a private interval for transcribe_video_evidence or analyze_video_evidence. audio_levels measures volume/silence only. Each cut/audio/clip/levels interval is at most120 seconds. Sparse frames are observations, never proof of continuous review. Repeated identical requests reuse evidence. No provider credits.',
+    { inspection_id: id, kind: z.enum(['frames', 'frame', 'cuts', 'audio', 'clip', 'audio_levels']).optional(),
+      timestamps: z.array(z.number().nonnegative()).min(1).max(12).optional(),
+      start_seconds: z.number().nonnegative().optional(), end_seconds: z.number().positive().optional(),
+      frame_count: z.number().int().min(1).max(12).optional(), project_id: project },
+    async ({ inspection_id, project_id, ...args }) => {
+      const result = await client.post(`/v1/analyze/video-inspections/${inspection_id}/evidence`, args, { timeoutMs: 115000 });
+      const { images = [], ...metadata } = result;
+      return { content: [{ type: 'text', text: JSON.stringify({ ...metadata, images: images.map(({ data, ...entry }) => entry) }) },
+        ...images.map(img => ({ type: 'image', mimeType: img.mime_type, data: img.data }))] };
+    });
+  server.tool('analyze_video_evidence',
+    'Run paid video, music, speech or sound understanding on a previously extracted interval only. Video focus requires clip evidence; audio focus accepts audio or clip. Useful for motion/continuity, instruments/rhythm/mood, speech context and sound design. For word timestamps/SRT use transcribe_video_evidence. Returned analysis timestamps are clip-relative: add source_offset_seconds. Real model usage is billed, and identical successful requests reuse saved analysis without new charges. An uncertain previous paid request is never automatically resubmitted.',
+    { inspection_id: id, evidence_id: z.string().regex(/^[a-f0-9]{24}$/),
+      focus: z.enum(['video', 'speech', 'music', 'sound']).optional(), prompt: z.string().max(2000).optional(),
+      quality: z.enum(['standard', 'hq']).optional(), project_id: project },
+    async ({ inspection_id, ...args }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/analyze`, args, { timeoutMs: 590000 })));
+  server.tool('transcribe_video_evidence',
+    'Transcribe an extracted audio interval using speech recognition with speaker labels, word timings and SRT. First inspect_video kind=audio for an interval up to120 seconds. Auto-detects language. Words include source_start/source_end in original recording seconds; SRT is clip-relative. Billed per rounded minute at current subtitle transcription pricing. Identical evidence/project requests reuse the transcript. For long recordings, transcribe selected windows or cover explicit consecutive windows and preserve their source offsets; never claim untranscribed audio was reviewed.',
+    { inspection_id: id, evidence_id: z.string().regex(/^[a-f0-9]{24}$/), project_id: project },
+    async ({ inspection_id, ...args }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/analyze`, { ...args, focus: 'transcription' }, { timeoutMs: 150000 })));
+}
+module.exports = { registerVideoInspectionTools };