@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/video-scrub/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: video-scrub
+description: "video-scrub: the method the original skill taught, run as an AICUT film — pages that draw any moment t, cut on tracks. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: Apache-2.0
+source: "eternityspring/reelbench-skills"
+---
+
+# video-scrub
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+## video-scrub
+
+把一条视频重建成干净文件：**画面和声音带过去，元数据一个字节都不带。**
+
+`{baseDir}` = 本文件所在目录。脚本 `{baseDir}/scripts/video-scrub.mjs`，零依赖，`node` 直接跑。
+
+### 原理：白名单，不是黑名单
+
+清元数据有两种思路，差别是死活：
+
+| | 怎么做 | 问题 |
+| --- | --- | --- |
+| 黑名单 | 列出要删的字段逐个删（exiftool 那种） | **删不完你不知道的东西**——厂商私有的 udta、GoPro 的遥测轨、码流里的 SEI，漏一个就漏了 |
+| **白名单** | 不说删什么，只说**带什么过去**：画面一条流、声音一条流，别的一律不要 | —— |
+
+走白名单，源片的元数据**没有任何通道**能进来。它不是「被删掉了」，是从来没被搬运。
+
+但 ffmpeg 默认会背叛这个结构两次，必须摁住:
+
+1. **它默认把源片的容器 tag 搬到输出** → `-map_metadata -1`
+2. **它默认自动挑流**，会把 GoPro 的 `gpmd` 遥测轨一起带走 → `-map 0:v:0 -map 0:a:0?`
+
+第 2 条是 GoPro / DJI 这类源片的唯一防线：**它们的 GPS 不在 tag 里，在一条独立的定时元数据轨上。**
+清 tag 清不掉，只有「只挑两条流」挡得住。
+
+### 真正的难点：看不见的那几层
+
+摁住上面两条，tag 层就干净了，`ffprobe` 一片安静。**但文件里还躺着三处身份串**：
+
+| 藏在哪 | 内容 | ffprobe 看得见 |
+| --- | --- | --- |
+| H.264 的 **SEI** | x264 完整参数串 `cabac=1 ref=3 … crf=23.0` | ✗ |
+| AAC 码流的 **DSE** | `Lavc62.28.102` | ✗ |
+| avc1 的 **compressorname** | `Lavc libx264` | ✗ |
+
+五个藏身处和各自的堵法见 `{baseDir}/references/residue-map.md`——**每一条都有实测记录，
+包括几个「看着该管用其实没用」的坑**（`-flags:v +bitexact` 和 `-x264-params info=0` 都拦不住 SEI）。
+
+### 两种模式
+
+| 模式 | 画面 | 音频 | 速度 | 多杀掉什么 |
+| --- | --- | --- | --- | --- |
+| **`copy`**（默认） | **逐字节照搬** | 重编 | 53 秒的片子 1.3 秒 | —— |
+| `encode` | 重编码 | 重编 | 慢得多 | 码流域水印、脆弱隐写 |
+
+音频**两种模式都重编**——AAC 的版本号写在 DSE 里，那是码流内部，`-c:a copy` 抹不掉它。
+重编一遍很便宜，换来音轨干净。画面则在 copy 模式下**真的一个比特都没动**（`cmp` 验证过，
+除了被摘掉的 SEI）。
+
+**关于水印**：`encode` 比 `copy` 多杀的是码流域水印和脆弱隐写，这两类在实际素材里少见。
+真正要命的**鲁棒像素水印**（SynthID、影视取证水印）设计目标就是扛住重编码，**两种模式都杀不掉**。
+所以选模式按画质和速度选，别指望重编码能洗掉水印。
+
+### 四个 profile
+
+擦白之后往回写的那一层：
+
+| profile | 写什么 |
+| --- | --- |
+| **`obs`**（默认） | OBS Studio 的长相。OBS 本来就是用 ffmpeg 封装的，所以这档不是伪造，是保持同类工具的正常外观 |
+| `quicktime` | macOS QuickTime 录屏：`Core Media Video` / `Core Media Audio` |
+| `screencapture` | ScreenCaptureKit 录屏 |
+| `bare` | 什么都不写。**隐私强度最高**——不留任何可被证伪的声明 |
+
+有一件事做不到，写在这里省得再试：容器的 `encoder` 字段由 muxer 自己占着，
+`-metadata encoder=Lavf60.16.100` **盖不过去**，置空也清不掉（实测）。只有
+`-fflags +bitexact` 能让它整个消失。所以 `obs` 档不伪造版本号，它就让 ffmpeg 写自己的真版本号。
+
+---
+
+### Step 0 — 先看源片带了什么
+
+```bash
+node {baseDir}/scripts/video-scrub.mjs inspect <video>
+```
+```
+一屏列全：容器 tag、每条流的 tag 与 side data、章节，**以及码流里那几处 `ffprobe` 看不见的身份串**。
+末尾会告诉你验收时要拿几根针去扫，以及 SEI 这刀动不动。
+
+**先看这一屏再动手。** 尤其注意两件事：
+
+- 有没有 `data` / `timecode` 流——有就说明源片可能带遥测轨（GoPro、DJI）
+- 是不是 **HDR**——是的话 SEI 一律不删（下面说为什么）
+```
+
+### Step 1 — 清
+
+```bash
+node {baseDir}/scripts/video-scrub.mjs scrub <video> -o out.mp4
+```
+```
+默认 `--mode copy --profile obs`。常用参数：
+```
+```bash
+--mode encode          # 完整重编码
+--profile bare         # 什么都不写，隐私强度最高
+--crf 18               # 只在 encode 模式有意义
+--date 2026-01-01T00:00:00Z   # 指定创建时间，不给就用当前时间
+```
+
+### Step 2 — 验收 ⛔ 不能跳
+
+```bash
+node {baseDir}/scripts/video-scrub.mjs verify <源> <输出>
+```
+```
+或者一条龙（**日常就用这个**）：
+```
+```bash
+node {baseDir}/scripts/video-scrub.mjs run <video> -o out.mp4
+```
+```
+验收的核心是一句话：**前面全是「我调了正确的参数」，属于声称；这一步是「我扫了，真没了」，属于证明。**
+
+做法是把源片所有元数据字符串抓出来当「针」——tag 的键和值、handler 名、章节标题——
+在输出文件里做**字节级扫描**，扎到一根就红。
+
+两条实现上的讲究：
+
+- **针要 ≥5 字节**。更短的串会在压缩数据里随机撞出假阳性，跳过的针会在提示里列出来。
+- **通用串不当针**。`VideoHandler` 满世界都是，信息量为零；`Lavf58.45.100` 钉死了一个版本，
+  是指纹。分界线是「能不能把范围缩小到某个人、某台设备、某次导出」。
+```
+
+### 12 道门
+
+| 门 | 拦什么 |
+| --- | --- |
+| 字节级残留 | 源片的元数据串扎中了输出 |
+| tag 层残留 | 输出的 tag 值来自源片 |
+| 位置信息 | 任何 GPS / location 字段 |
+| 设备与软件标识 | make / model / software / artist / comment 之类 |
+| 源片时间戳 | 输出的 creation_time 等于源片的 |
+| 旋转矩阵 | encode 模式下旋转没烘进画面（copy 模式跳过——删了画面就是歪的） |
+| 流构成 | 混进了 data / timecode / 附件流 |
+| 章节 | 章节跟过来了 |
+| 码流身份串 | SEI / DSE / compressorname 里还有编码器名字 |
+| profile 相符 | 剩下的 tag 和声明的 profile 对不上 |
+| 时长 | 输出被偷偷截断 |
+| 可解码 | 产出了打不开的坏文件 |
+
+### HDR 与内嵌字幕：SEI 这刀什么时候不许动
+
+ffmpeg 只给得起 **NAL 级**的粒度——`filter_units` 按 NAL 类型删，
+`h264_metadata` 也没有「只删某个 SEI payload」的选项。所以 `remove_types=6` 是
+**全部 SEI 一起删**。而 SEI 里除了 x264 那串垃圾，还住着：
+
+- **HDR 静态元数据**（mastering display / content light level）——删了会掉色，tone mapping 崩
+- **CEA-608/708 内嵌字幕**——删了字幕没了
+
+所以脚本的策略是：**只在真查到身份串时才动刀，HDR 源片一律不动**（会明说没动，
+以及为什么）。这个判断由 `seiPlan()` 做，不需要你操心，但你该知道它在那儿。
+
+### 边界（不做的事）
+
+不去除水印（鲁棒像素水印重编码也杀不掉，别指望）、不改画面内容（不裁剪不缩放不旋转）、
+不伪造设备型号和 GPS（profile 只写工具类信息，不编造拍摄设备和位置）、
+不做批量目录扫描（一次一条片子）、不处理非 mp4/mov 之外的容器。
+
+### 自测
+
+```bash
+node {baseDir}/scripts/selftest.mjs
+```
+```
+117 项断言，不碰 ffmpeg、不碰真文件。**12 道门每道都有击穿用例**——证明它真的会拦。
+改完脚本先跑这个。
+```
+
+## Source
+
+Rewritten for AICUT from [`eternityspring/reelbench-skills`](https://github.com/eternityspring/reelbench-skills)
+(Apache-2.0), skills/video-scrub/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 3 skills; this is the one its entry stands for.

package/skills/video-scrub/references/profiles.md

@@ -0,0 +1,89 @@
+# profile：擦白之后写回去的那一层
+
+清完之后文件是「无名」的——没有 tag，没有 handler 名，没有时间。
+profile 决定往回写什么。
+
+**隐私强度排序：`bare` > 其余三档。** 理由很简单：`bare` 不写任何可被证伪的声明。
+其余三档写的是工具类信息（什么软件封装的、什么 handler），**不编造拍摄设备、不编造位置**。
+
+---
+
+## 录屏的元数据长什么样
+
+先说一个事实，它决定了这几档为什么都这么简单：
+
+**录屏的元数据特征九成是「没有」。**
+
+GPS 是拍摄设备的定位服务写进去的——iPhone 相机写 `com.apple.quicktime.location.ISO6709`，
+安卓相机写 `location`。录屏抓的是显示缓冲区，QuickTime、ScreenCaptureKit、OBS、
+Windows Game Bar、iOS 控制中心录屏，**压根没有定位这条管线，也没有相应权限**。
+
+所以一条录屏文件里不会有：GPS、相机型号、镜头光圈快门、旋转矩阵、拍摄参数。
+剩下的只有封装工具的痕迹。
+
+---
+
+## 四档
+
+### `obs`（默认）—— OBS Studio 录制
+
+```
+encoder      = Lavf<ffmpeg 的真版本号>
+handler_name = VideoHandler / SoundHandler
+creation_time = <当前时间或 --date>
+```
+
+**这档不是伪造。** OBS 本来就是用 ffmpeg 封装输出的，所以它产出的文件带 `Lavf` 版本号、
+带标准 handler 名。我们的输出也是 ffmpeg 封的，长相同类。
+
+版本号**不伪造**——做不到（见 `residue-map.md` 第 1 条），也没必要。
+这一档靠**不加** `-fflags +bitexact` 来保住 ffmpeg 自己写的版本号。
+
+### `quicktime` —— macOS QuickTime 录屏
+
+```
+handler_name = Core Media Video / Core Media Audio
+creation_time = <当前时间或 --date>
+（无 encoder 字段）
+```
+
+`Core Media *` 是 Apple 的 AVFoundation 写的 handler 名，QuickTime 录屏、
+iOS 录屏产出的文件都长这样。
+
+### `screencapture` —— macOS ScreenCaptureKit
+
+和 `quicktime` 同款。分成两档是因为语义不同（一个是 App 录的，一个是系统 API 录的），
+元数据层面当前不做区分。
+
+### `bare` —— 什么都不写
+
+```
+handler_name = "（单空格）"
+（无 encoder、无 creation_time）
+```
+
+**隐私强度最高的一档。** 不留任何可被证伪的声明，也不留时间。
+
+handler 用单空格是有原因的：置空会退回 ffmpeg 的默认值 `VideoHandler`，等于没清。
+见 `residue-map.md` 第 5 条。
+
+---
+
+## 选哪一档
+
+| 场景 | 建议 |
+| --- | --- |
+| 发布前清掉自己的隐私信息 | `obs`（默认），够了 |
+| 交付给客户、不想带自己的工具痕迹 | `bare` |
+| 素材库归档，想要一致的元数据 | 任意一档，固定住就行 |
+| 不确定 | `bare`——不写就不会错 |
+
+---
+
+## profile 不做的事
+
+- **不写设备型号。** 不会往输出里填 `iPhone 15 Pro` 或任何相机型号。
+- **不写 GPS。** 位置那道门判的是「必须不存在」，不是「伪造一个合理的坐标」。
+- **不写作者、版权、账号。** 这些字段只会被清，不会被填。
+
+profile 只碰三样东西：封装工具的痕迹、handler 名、创建时间。

package/skills/video-scrub/references/residue-map.md

@@ -0,0 +1,204 @@
+# 五个藏身处
+
+清视频元数据不是一行 `-map_metadata -1` 的事。工具会把身份写进**五个地方**，
+其中三处 `ffprobe` 根本看不见——所以「我清干净了」这个判断本身可能是假的。
+
+以下全部在 ffmpeg 8.1.2 / macOS 上实测，包括几个**看着该管用其实没用**的坑。
+
+---
+
+## 1. 容器 tag 的 `encoder`
+
+最显眼的一处，`ffprobe -show_format` 就能看见。
+
+```
+encoder = Lavf58.45.100
+```
+
+**堵法：** `-fflags +bitexact`
+
+**注意：** 这个字段由 muxer 自己占着，改不动也清不掉：
+
+| 试过 | 结果 |
+| --- | --- |
+| `-metadata encoder=Lavf60.16.100` | ✗ 盖不过去，输出仍是 ffmpeg 的真版本号 |
+| `-metadata encoder=`（置空） | ✗ 清不掉 |
+| `-fflags +bitexact` | ✓ 整个字段消失 |
+
+**推论：** 想让输出「看起来像某个特定版本的工具产出」是做不到的。
+所以 `obs` 档不伪造版本号——它不加 bitexact，让 ffmpeg 写自己的真版本号。
+
+**另一条实测：** `-fflags +bitexact` 会清掉自动生成的 `creation_time`，
+但**不影响显式写的那个**。`-fflags +bitexact -metadata creation_time=...` 两者可以并存。
+
+---
+
+## 2. `avc1` 的 compressorname
+
+藏在 `moov` 的 sample description 里，是 `VisualSampleEntry` 的一个 32 字节 Pascal 串。
+
+```
+...\x01\x0cLavc libx264\x00\x00...
+```
+
+`ffprobe -show_format` 看不见它，`ffprobe -show_entries stream_tags` 能看见一个对应的
+`encoder` 流 tag。
+
+**堵法：** `-metadata:s:v:0 encoder=`
+
+mov muxer 从**流的 `encoder` tag** 取这个字段，置空即清。
+注意和第 1 条的区别：容器级的 `encoder` 置空没用，流级的置空有用。
+
+---
+
+## 3. AAC 码流里的 DSE
+
+ffmpeg 的 AAC 编码器把自己的版本号写进 **Data Stream Element**，在音频码流内部。
+
+```
+Lavc62.28.102
+```
+
+一条 53 秒的片子里出现 8 处。`ffprobe` 完全看不见。
+
+**堵法：** `-flags:a +bitexact`
+
+**关键推论：** 这是**码流内部**的东西，`-c:a copy` 抹不掉它。
+所以即使走 copy 模式，**音频也必须重编一遍**。代价很小（53 秒的片子约 1 秒），
+换来音轨干净。
+
+---
+
+## 4. H.264 的 SEI —— 最刁的一处
+
+x264 把**完整编码参数**写成 SEI 塞在码流里：
+
+```
+x264 - core 165 r3222 b35605a - H.264/MPEG-4 AVC codec - Copyleft 2003-2025 -
+http://www.videolan.org/x264.html - options: cabac=1 ref=3 deblock=1:0:0
+analyse=0x3:0x113 me=hex subme=7 psy=1 psy_rd=1.00:0.00 mixed_ref=1 me_range=16
+... crf=23.0 qcomp=0.60 qpmin=0 qpmax=69 ...
+```
+
+这串东西信息量极大——编码器版本、全部参数、CRF 值。**任何 `ffprobe` 命令都看不见它。**
+
+### 试错记录
+
+| 试过 | 结果 |
+| --- | --- |
+| `-flags:v +bitexact` | ✗ 拦不住，SEI 照写 |
+| `-x264-params info=0` | ✗ 被 ffmpeg 的封装吃掉了，无效 |
+| **`-bsf:v filter_units=remove_types=6`** | ✓ 干净利落 |
+
+**堵法：** `-bsf:v filter_units=remove_types=6`（6 = SEI 的 NAL 类型）
+
+**重要：它在 `-c:v copy` 下照样工作。** 这是 copy 模式能成立的关键——
+不重编画面也能摘掉 SEI。实测抽出前后的 H.264 码流 `cmp`，除了被摘掉的 SEI 之外逐字节一致。
+
+### 但这把刀太钝 ⚠
+
+ffmpeg 只给得起 **NAL 级**的粒度：
+
+- `filter_units` 只能按 NAL 类型删，删不了单个 SEI payload
+- `h264_metadata` 也没有对应选项（它能 `insert` SEI，不能选择性 `remove`）
+
+所以 `remove_types=6` 是**全部 SEI 一起删**。SEI 里还住着：
+
+- **HDR 静态元数据**——mastering display colour volume / content light level。
+  删了 HDR 片子会掉色，tone mapping 直接崩。
+- **CEA-608/708 内嵌字幕**——删了字幕没了。
+- `pic_timing` / `buffering_period`——个别播放器会挑剔。
+
+**所以策略是有条件动刀**（`seiPlan()`）：
+
+1. 源片是 HDR → **一律不删**，哪怕有身份串，也只出告警
+2. 码流里没查到身份串 → 不必动刀
+3. 其余情况 → 删
+
+HDR 的判定看 `color_transfer`（`smpte2084` / `arib-std-b67`）、`color_primaries`（`bt2020`）
+和像素格式（`10le` / `12le` / `p010`）。
+
+---
+
+## 5. `handler_name`
+
+```
+VideoHandler / SoundHandler
+```
+
+**堵法：** 显式写值。
+
+**坑：** `-metadata:s:v:0 handler_name=`（置空）**会退回 ffmpeg 的默认值** `VideoHandler`，
+等于没清。要真空白得写一个**单空格**：
+
+```
+-metadata:s:v:0 handler_name=" "
+```
+
+实测：单空格 → 输出的 handler_name 为空，文件里 `VideoHandler` 出现 0 次。
+
+---
+
+## 不在这五处、但同样要命的：独立的元数据轨
+
+**GoPro 和 DJI 的 GPS 不在任何 tag 里**，在一条独立的定时元数据轨上
+（GoPro 是 `gpmd` handler，整条 GPMF 遥测流：轨迹、速度、陀螺仪）。
+
+你把 tag 清光了，`ffprobe -show_format` 看着干干净净，**一整条行动轨迹还躺在文件里**。
+
+**堵法：** 白名单选流。
+
+```
+-map 0:v:0 -map "0:a:0?"
+```
+
+只显式挑视频和音频，其余一概不带过去——data 轨、timecode 轨、附件、字幕轨全掉。
+配合 `-map_chapters -1` 把章节也挡住。
+
+这就是「流构成」单独占一道门的原因：**不是形式主义，是这类源片唯一的防线。**
+
+---
+
+## 完整配方
+
+```bash
+ffmpeg -v error -y -i <src> \
+  -map 0:v:0 -map "0:a:0?" \
+  -map_metadata -1 -map_chapters -1 \
+  -c:v copy \                                  # 或 -c:v libx264 -crf 18
+  -c:a aac -b:a 192k \                         # 音频必须重编，见第 3 条
+  -bsf:v "filter_units=remove_types=6" \        # 第 4 条，有条件
+  -fflags +bitexact \                           # 第 1 条，bare/quicktime 档
+  -flags:a +bitexact \                          # 第 3 条
+  -metadata:s:v:0 encoder= \                    # 第 2 条
+  -metadata:s:a:0 encoder= \
+  -metadata:s:v:0 handler_name="<profile 的值>" \ # 第 5 条
+  -metadata:s:a:0 handler_name="<profile 的值>" \
+  -movflags +faststart \
+  <out>
+```
+
+---
+
+## 字节级扫描的两条讲究
+
+验收时把源片的元数据字符串当「针」在输出里扫，有两个实现细节不能省：
+
+**针要 ≥5 字节。** 更短的串会在压缩数据里随机撞出假阳性——踩过：一次扫描报告
+`Lavc` 和 `x264` 有残留，查偏移才发现是压缩数据里的巧合。跳过的针要在报告里列出来，
+不能默默忽略。
+
+**通用串不当针。** 分界线是**能不能把范围缩小到某个人、某台设备、某次导出**：
+
+| 串 | 当针？ | 为什么 |
+| --- | --- | --- |
+| `wesley@example.com` | ✓ | 指向一个人 |
+| `vid:v1e00fgi0000...` | ✓ | 平台的视频 ID |
+| `iPhone 15 Pro` | ✓ | 指向设备型号 |
+| `Lavf58.45.100` | ✓ | 钉死了一个版本 |
+| `VideoHandler` | ✗ | 满世界都是，信息量为零 |
+| `isom` | ✗ | 结构性 tag，输出里必然还有，当针会自己扎自己 |
+
+**还有一类要豁免：profile 自己写回去的值。** 如果源片也是 ffmpeg 封的、版本号还恰好相同，
+输出的 `encoder` 会和源片一模一样——但它是 muxer 现写的，不是漏过来的。
+这个豁免不开口子：有 `-map_metadata -1` 在，源片的 `encoder` 字段**结构上就到不了**输出。

package/skills/video-short-maker/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: video-short-maker
+description: "Create short clips from local video files using ffmpeg, with optional local Whisper subtitles. Use when Codex is asked to turn a long local video into a short, trim boring pauses, remove dead air, cut silence, create a 30-60 second clip, export a vertical 9:16 MP4, generate captions/subtitles, burn subtitles into a video, or generate a simple edit report. Base editing is ffmpeg-based; subtitles use local whisper.cpp and do not require an API key. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "Kappaemme-git/codex-video-short-maker-skill"
+---
+
+# Video Short Maker
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+## Overview
+
+Use this skill to turn a local video into a shorter MP4 by detecting silence and keeping the strongest non-silent parts. The base workflow depends only on `ffmpeg` and `ffprobe`. Captions are optional and use local `whisper.cpp`.
+
+## Workflow
+
+1. Identify the input video path and output goal.
+   - Default target duration: `45s`.
+   - Default format: landscape/same aspect ratio.
+   - Default quality: `high` for crisp text in screen recordings.
+   - Use vertical 9:16 only when the user asks for TikTok/Reels/Shorts/vertical.
+   - Use captions only when the user asks for subtitles/captions.
+
+2. Run the bundled script:
+
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --duration 45
+```
+```
+For vertical output:
+```
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --duration 45 --vertical
+```
+```
+For a custom output path:
+```
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --duration 45 --output ./short.mp4
+```
+```
+For smaller files:
+```
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --duration 45 --quality small
+```
+```
+For local captions:
+```
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --duration 45 --vertical --captions
+```
+```
+3. Report the result succinctly:
+   - output file path
+   - duration target
+   - number of segments kept
+   - report path
+   - whether vertical crop was applied
+   - quality preset
+   - subtitle and captioned video paths when captions were used
+```
+
+## Quality Presets
+
+- `high`: CRF 18, slower encode, sharper text, larger file. Default.
+- `balanced`: CRF 20, faster encode, good quality/size balance.
+- `small`: CRF 24, smaller file, visibly more compression.
+
+## Captions
+
+Captions are optional and local. They do not require an API key.
+
+When the user asks for subtitles/captions:
+
+1. Check whether `whisper-cli` or `whisper-cpp` exists.
+2. If missing, run or suggest:
+
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/setup_captions.py
+```
+```
+3. Run `make_short.py` with `--captions`.
+
+Caption outputs:
+
+- `*.srt`: generated subtitle file
+- `*.captioned.mp4`: final video with burned-in subtitles
+
+Burned-in captions are rendered with Python/Pillow so they work even when the local ffmpeg build does not include the `subtitles` filter.
+
+Default caption model: `tiny.en`.
+
+For Italian or non-English speech, use the multilingual model and language:
+```
+```bash
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/setup_captions.py --model base
+python3 /Users/francescomistero/.codex/skills/video-short-maker/scripts/make_short.py INPUT_VIDEO --captions --caption-model ~/.cache/video-short-maker/models/ggml-base.bin --caption-language it
+```
+
+## Editing Behavior
+
+The script:
+
+- detects silent ranges with ffmpeg `silencedetect`
+- converts them into non-silent candidate segments
+- supports `--cut-style light|normal|aggressive`
+- keeps `0.5s` of silence on both sides of each cut by default in `normal`, so speech feels less abrupt
+- drops very short fragments
+- keeps earlier non-silent segments until the target duration is reached
+- concatenates selected segments
+- optionally crops/scales to 9:16
+- exports H.264 MP4 with AAC audio
+- optionally extracts audio, transcribes with local Whisper, writes SRT, and burns captions
+- writes an edit report JSON next to the output
+
+This is not content-aware yet. It removes dead air and compresses the video, but it does not understand the spoken content.
+
+## Output Guidance
+
+Keep responses short. Do not paste full ffmpeg logs unless the command fails.
+
+Use this format:
+
+```markdown
+Created short:
+`/path/to/output.short.mp4`
+
+- Target: 45s
+- Kept segments: 6
+- Vertical: yes/no
+- Quality: high/balanced/small
+- Report: `/path/to/output.report.json`
+- Subtitles: `/path/to/output.srt` if used
+- Captioned video: `/path/to/output.captioned.mp4` if used
+```
+If the result is rough, say so plainly and suggest the next useful option:
+
+- use `--cut-style aggressive` if it barely cut anything
+- use `--cut-style light` if cuts feel too jumpy
+- increase `--keep-silence` to make cuts feel softer
+- increase `--duration` if context is missing
+- use `--vertical` for Shorts/Reels/TikTok
+- use `--quality balanced` or `--quality small` if the file is too large
+- use `--captions` when subtitles are needed
+```
+
+## Source
+
+Rewritten for AICUT from [`Kappaemme-git/codex-video-short-maker-skill`](https://github.com/Kappaemme-git/codex-video-short-maker-skill)
+(MIT), video-short-maker/SKILL.md. The method is that skill's own; the way it runs is AICUT's.