@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/shorts/references/remotion-patterns.md

@@ -0,0 +1,180 @@
+# Remotion Patterns and Best Practices
+
+Key patterns used in claude-shorts, verified against Remotion v4.0.422.
+
+## Bundle-Once-Render-Many
+
+For batch rendering multiple shorts, bundle the project once and reuse the Chrome instance:
+
+```js
+import { bundle } from "@remotion/bundler";
+import { renderMedia, selectComposition, openBrowser } from "@remotion/renderer";
+
+// Bundle once
+const serveUrl = await bundle({ entryPoint: "src/index.ts" });
+
+// Open shared browser
+const browser = await openBrowser("chrome");
+
+try {
+  for (const segment of segments) {
+    // selectComposition resolves calculateMetadata for dynamic duration
+    const composition = await selectComposition({
+      serveUrl,
+      id: "ShortVideo",
+      inputProps: segment.props,
+      puppeteerInstance: browser,
+    });
+
+    await renderMedia({
+      composition,
+      serveUrl,
+      codec: "h264",
+      crf: 18,
+      outputLocation: segment.outputPath,
+      inputProps: segment.props,
+      puppeteerInstance: browser,
+    });
+  }
+} finally {
+  await browser.close();
+}
+```
+
+**Critical**: Always use `selectComposition()` before `renderMedia()`. Never pass inline composition objects. `selectComposition()` evaluates `calculateMetadata` to resolve dynamic duration per segment.
+
+## OffthreadVideo + CSS Reframing
+
+Reframing is done via CSS transforms on OffthreadVideo, not FFmpeg pre-processing:
+
+```tsx
+const scale = outputWidth / crop.w;
+const translateX = -crop.x * scale;
+const translateY = -crop.y * scale;
+
+<div style={{ width: 1080, height: 1920, overflow: "hidden" }}>
+  <OffthreadVideo
+    src={clipPath}
+    style={{
+      width: sourceWidth * scale,
+      height: sourceHeight * scale,
+      transform: `translate(${translateX}px, ${translateY}px)`,
+    }}
+  />
+</div>
+```
+
+This avoids double-encoding. Remotion handles the crop during render.
+
+## Spring Animations
+
+Spring configs for each caption style:
+
+```ts
+// Bold: Snappy pop-in, slight overshoot
+spring({ frame, fps, config: { mass: 1, damping: 12, stiffness: 200 } });
+// ~0.4s settle, overshoots to ~1.05
+
+// Bounce: Very bouncy, visible overshoot
+spring({ frame, fps, config: { mass: 1, damping: 8, stiffness: 180 } });
+// ~0.6s settle, overshoots to ~1.2
+
+// Clean style uses interpolate(), not spring
+interpolate(localFrame, [0, 6], [0, 1], { extrapolateRight: "clamp" });
+```
+
+Spring values guide:
+- `damping < 10`: Visible bounce
+- `damping 10-15`: Slight overshoot, professional feel
+- `damping > 20`: No overshoot, smooth ease
+- `stiffness > 150`: Fast, snappy
+- `stiffness < 100`: Slow, gentle
+
+## @remotion/captions API
+
+```ts
+import { createTikTokStyleCaptions } from "@remotion/captions";
+
+// Input captions format
+type Caption = {
+  text: string;
+  startMs: number;
+  endMs: number;
+  timestampMs: null;   // required field, always null for our use
+  confidence: null;     // required field, always null for our use
+};
+
+// Create pages (groups of words)
+const { pages } = createTikTokStyleCaptions({
+  captions: remotionCaptions,
+  combineTokensWithinMilliseconds: 800, // adjust per style
+});
+
+// Page structure
+type TikTokPage = {
+  text: string;       // Combined text of all tokens
+  startMs: number;    // Start time of first token
+  durationMs: number; // Duration until end of last token
+  tokens: Array<{
+    text: string;
+    fromMs: number;
+    toMs: number;
+  }>;
+};
+```
+
+## calculateMetadata for Dynamic Duration
+
+Each segment has a different duration. Use `calculateMetadata` in the Composition:
+
+```tsx
+<Composition
+  id="ShortVideo"
+  component={ShortVideo}
+  width={1080}
+  height={1920}
+  fps={30}
+  durationInFrames={30 * 30} // default, overridden by calculateMetadata
+  schema={ShortVideoPropsSchema}
+  defaultProps={defaultProps}
+  calculateMetadata={({ props }) => ({
+    durationInFrames: Math.ceil(props.durationInSeconds * 30),
+    fps: 30,
+    width: 1080,
+    height: 1920,
+  })}
+/>
+```
+
+## Zod Schema Validation
+
+Always define inputProps with Zod schemas for type safety:
+
+```ts
+import { z } from "zod";
+
+const ShortVideoPropsSchema = z.object({
+  clipSrc: z.string(),
+  sourceWidth: z.number(),
+  sourceHeight: z.number(),
+  crop: CropSchema,
+  captions: z.array(CaptionSchema),
+  captionStyle: z.enum(["bold", "bounce", "clean"]),
+  hookLine1: z.string().optional().default(""),
+  hookLine2: z.string().optional().default(""),
+  showProgressBar: z.boolean().optional().default(true),
+  durationInSeconds: z.number(),
+});
+```
+
+## File Paths in Render
+
+When rendering headless, `clipSrc` must be an `http://` URL. Remotion's renderer proxy does not support `file://` URLs. The render script starts a local HTTP server on a random port (e.g., `http://127.0.0.1:PORT/clip_01.mp4`) to serve clip files. Do NOT use `staticFile()` for dynamic clip sources — that's for bundled assets only.
+
+## Performance Tips
+
+- Use `OffthreadVideo` (not `Video`) — decodes frames in a separate thread
+- Pre-extract segments before rendering (don't seek through long files)
+- Use `codec: "h264"` with `crf: 18` for good quality-size balance
+- Share browser instance across renders (`openBrowser` + `puppeteerInstance`)
+- Bundle once, render many

package/skills/shorts/references/scoring-rubric.md

@@ -0,0 +1,106 @@
+# Segment Scoring Rubric
+
+When analyzing a transcript for shortform candidates, score each segment on these 5 dimensions. Each dimension is scored 0-100, then weighted to produce a final score.
+
+## Dimensions
+
+### 1. Hook Strength (Weight: 0.30)
+
+The first 3 seconds determine whether a viewer scrolls past or stays. Score based on which hook archetype is present:
+
+| Archetype | Example | Score Range |
+|-----------|---------|-------------|
+| Bold/Contrarian | "Everything you know about X is wrong" | 80-100 |
+| Curiosity Gap | "There's one thing nobody tells you about..." | 75-95 |
+| Value Promise | "Here's the exact framework I used to..." | 70-90 |
+| Pattern Interrupt | "Wait, let me show you something weird" | 70-90 |
+| Payoff Preview | "By the end of this you'll know how to..." | 65-85 |
+| Mid-Action Start | [Starts mid-sentence with energy] | 60-80 |
+| Hidden Knowledge | "The secret that [authority figures] don't share" | 60-80 |
+| Weak/Generic | "So today I want to talk about..." | 10-40 |
+
+**Boosters** (+5-10 each):
+- Contains a specific number ("3 steps", "$50K", "in 30 days")
+- Names a recognizable entity (person, company, tool)
+- Implies personal experience ("I tested", "I spent 6 months")
+
+### 2. Standalone Coherence (Weight: 0.25)
+
+The segment must make complete sense to someone who hasn't seen the rest of the video.
+
+| Criteria | Score |
+|----------|-------|
+| Complete self-contained narrative arc (setup → development → resolution) | 85-100 |
+| Complete idea with minor context gaps (viewer can infer) | 65-84 |
+| Mostly standalone but references earlier content ("as I said before") | 40-64 |
+| Requires prior context to understand ("so going back to that point") | 10-39 |
+| Fragment — starts or ends mid-thought | 0-9 |
+
+**Red flags** (automatic low score):
+- "As I mentioned earlier..."
+- "Going back to what we discussed..."
+- Pronouns without clear referents ("he said that...")
+- Cuts off mid-sentence at the end
+
+### 3. Emotional Intensity (Weight: 0.20)
+
+Strong emotions drive shares and comments.
+
+| Signal | Score Range |
+|--------|-------------|
+| Passionate rant / strong opinion with conviction | 80-100 |
+| Surprise reveal / unexpected twist | 75-95 |
+| Genuine humor / laughter | 70-90 |
+| Personal vulnerability / honest failure story | 70-90 |
+| Enthusiastic explanation of something fascinating | 60-80 |
+| Calm but insightful observation | 40-60 |
+| Monotone recitation of facts | 10-30 |
+
+### 4. Value Density (Weight: 0.15)
+
+How much actionable content is packed per second.
+
+| Content Type | Score Range |
+|--------------|-------------|
+| Step-by-step process / exact method | 80-100 |
+| Framework / mental model with examples | 75-95 |
+| Specific data points / research findings | 70-90 |
+| Counter-intuitive insight with explanation | 65-85 |
+| General advice with some specifics | 40-60 |
+| Vague platitudes ("work harder", "be consistent") | 10-30 |
+
+**Duration adjustment**: Penalize segments where >30% of time is filler, repetition, or tangents.
+
+### 5. Payoff Quality (Weight: 0.10)
+
+How satisfying the ending feels.
+
+| Ending Type | Score Range |
+|-------------|-------------|
+| Punchline / satisfying reveal | 85-100 |
+| Clear call-to-action with specific next step | 75-90 |
+| Complete thought — natural stopping point | 65-80 |
+| Fades into next topic (can be cut cleanly) | 40-60 |
+| Cuts off mid-thought / no resolution | 10-30 |
+
+## Scoring Formula
+
+```
+final_score = (hook * 0.30) + (coherence * 0.25) + (emotion * 0.20) + (value * 0.15) + (payoff * 0.10)
+```
+
+## Candidate Selection Guidelines
+
+1. **Target 8-12 candidates** from a typical 30-60 minute video
+2. **Duration sweet spot**: 15-55 seconds (peak engagement at 25-40s)
+3. **Minimum score threshold**: 60 (below this, skip the segment)
+4. **Diversity**: Don't select 5 segments about the same subtopic
+5. **Spacing**: Prefer segments at least 2 minutes apart in source
+6. **Natural boundaries**: Align start/end with sentence boundaries, not mid-word
+
+## Hook Text Generation
+
+For each selected segment, write a hook overlay:
+- **Line 1**: 4-8 words, the attention-grabbing statement (white, large)
+- **Line 2**: 3-6 words, context or subtitle (cyan, smaller)
+- Lines should NOT duplicate the first spoken words — they complement the audio

package/skills/smart-video-editor/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: smart-video-editor
+description: "把多段原始素材剪成一条成片——先用视觉模型看懂每段画面拍了什么、哪几秒可用，再决定取舍、顺序、时长、调色和 BGM，最后用 ffmpeg 渲染。适用于\"我给你几段视频，帮我剪一条小红书/朋友圈/vlog\"这类需求。当用户提供视频文件并希望剪辑、拼接、配乐、调色、转成竖屏时使用。不做 AI 生成视频。 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "Fagan1024/smart-video-editor"
+---
+
+# Smart Video Editor
+
+## 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.
+
+
+纯剪辑。核心区别在于**先看懂素材再动手**，而不是按文件名顺序机械拼接。
+
+## 三个阶段
+
+### 阶段一：看懂素材
+
+```bash
+python3 {baseDir}/scripts/probe.py <素材目录或文件列表>
+```
+```
+拿到每段的时长、分辨率、朝向、帧率、有无音轨。
+
+然后**对每一段抽帧，逐帧用 `vision_analyze` 看**：
+```
+```bash
+python3 {baseDir}/scripts/extract_frames.py <video> /tmp/sve-frames --interval 1.5 --max 8
+```
+```
+帧文件名形如 `clip1__t3.5.jpg`，`t` 后面就是它在原片中的秒数——视觉判断能直接映射回时间轴。
+
+对每帧问这些（一次问清，不要分多次）：
+
+> 这一帧里是什么内容（主体、场景、动作）？构图如何？是否存在下列问题：明显模糊/失焦、剧烈抖动、过曝或死黑、镜头遮挡、无内容的空镜、正在转场的中间态？给画面可用性打 1-5 分。
+
+**素材多时用 `session_spawn` 并行分析**，每个子任务负责 1-2 段，让它把结论按 `{时间戳: 内容, 可用性, 问题}` 结构化返回。
+```
+
+### 阶段二：做剪辑决策
+
+拿到全部画面信息后，自己判断这几件事——这是这个 skill 真正的价值所在，不要跳过：
+
+**取舍**：可用性低于 3 分的时间段直接不要。一段 10 秒素材里只有 4 秒有内容，就只取那 4 秒。
+
+**顺序**：按叙事逻辑排，不要按文件名。常用结构：
+- 空间叙事：全景开场 → 中景 → 细节特写 → 人物/收尾
+- 时间叙事：按事件发生顺序
+- 情绪叙事：平静起 → 高潮 → 回落收尾
+
+**节奏**：短视频（15-30 秒）单段 1.5-3 秒；慢节奏 vlog 可以 4-6 秒。同类画面连续出现要缩短，避免观感重复。有 BGM 时让切点尽量落在节拍上。
+
+**调性**：根据画面内容选 `look`，不要默认套一个。
+
+**竖屏处理**：横屏素材进竖屏成片时，主体在中间用 `crop`，主体偏移或不能裁的用 `blur_pad`。
+
+把决策写成 EDL（JSON）：
+
+```json
+{
+  "output": "/绝对路径/成片.mp4",
+  "aspect": "9:16",
+  "fps": 30,
+  "look": "film",
+  "fill_mode": "crop",
+  "transition": { "type": "dissolve", "duration": 0.4 },
+  "keep_original_audio": false,
+  "bgm": {
+    "path": "/绝对路径/bgm.mp3",
+    "volume": 0.85,
+    "start": 0,
+    "fade_in": 1.0,
+    "fade_out": 1.5,
+    "original_volume": 0.25
+  },
+  "title": {
+    "ass": "/绝对路径/title.ass",
+    "fonts_dir": "~/.cola/assets/fonts"
+  },
+  "segments": [
+    { "src": "/绝对路径/clip1.mov", "in": 2.4, "out": 5.1 },
+    { "src": "/绝对路径/clip3.mov", "in": 0.5, "out": 3.0, "speed": 1.0 }
+  ]
+}
+```
+字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `aspect` | `9:16` 竖屏 / `16:9` 横屏 / `1:1` / `4:5` / `3:4` |
+| `resolution` | 可选，`[宽,高]`，给了就覆盖 aspect |
+| `look` | `none` `clean` `film` `warm` `cool` `soft` `vivid` `fresh` `bw` |
+| `fill_mode` | `crop` 裁满 / `pad` 黑边 / `blur_pad` 模糊铺底 |
+| `transition.type` | `cut` `fade` `dissolve` `fadeblack` `wipeleft` `slideleft` `smoothleft` |
+| `keep_original_audio` | 是否保留原声；和 BGM 同时开会自动混音 |
+| `bgm.original_volume` | 混音时原声的压低倍数 |
+| `segments[].in/out` | 该片段在源素材中的起止秒 |
+| `segments[].speed` | 可选，`2.0` 快放一倍，`0.5` 慢放 |
+| `title` | 可选，标题字幕。`ass` 指向 make_title.py 生成的文件 |
+
+调性参考：
+
+| look | 适合 |
+|------|------|
+| `clean` | 通用，轻微提对比和锐度，最安全 |
+| `film` | 电影感，中对比曲线 + 轻暗角 + 冷调阴影 |
+| `warm` | 食物、室内、人物、日落 |
+| `cool` | 城市、雪景、雨天、科技感 |
+| `soft` | 日系清淡、柔和小清新 |
+| `vivid` | 风景、明亮活泼、需要抓眼球（注意易过饱和、灰色物体会偏色） |
+| `fresh` | 阴天/漫射光下的户外素材，提通透但不染色，绿植类首选 |
+| `bw` | 黑白 |
+```
+
+### 阶段二半：标题动画（可选）
+
+需要片头字时，用 `make_title.py` 生成 ASS 字幕，再在 EDL 里挂 `title` 字段。
+**绝不用系统默认字体**——默认黑体一眼就是"没设计过"。
+
+#### 选字体
+
+字体库索引在 `~/.cola/assets/fonts/FONTS.md`，**先读它再决定**，表里有每个字体的
+family name、风格、许可和适用场景：
+
+```bash
+cat ~/.cola/assets/fonts/FONTS.md
+```
+```
+选择依据是**画面调性**，不是随便挑：
+
+| 画面类型 | 字体方向 |
+|---------|---------|
+| 运动、骑行、city walk、潮流 | 倾斜粗黑（得意黑），有速度感和张力 |
+| 风景、旅行、治愈、慢生活 | 楷体或宋体（霞鹜文楷、思源宋体），文艺质感 |
+| 产品、UI、数据、干货 | 现代无衬线（思源黑体、Inter），干净克制 |
+| 生活记录、日常、轻松 | 圆体或手写体，亲和力强 |
+| 纯英文/数字标题 | Bebas Neue（粗压缩）、Playfair Display（高衬线） |
+
+**`--font` 传的是字体内部的 family name，不是文件名。** 从 FONTS.md 表里取；
+新装的字体要自己查：
+```
+```bash
+python3 -c "
+from fontTools.ttLib import TTFont
+t=TTFont('<字体路径>', fontNumber=0)
+print({r.toUnicode() for r in t['name'].names if r.nameID==1})
+"
+```
+```
+#### 生成标题
+```
+```bash
+python3 {baseDir}/scripts/make_title.py \
+  --text "标题文字" --font "Smiley Sans" \
+  --out /path/title.ass \
+  --anim fade-up --start 0.4 --duration 2.6 --size 96
+```
+```
+主要参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--text` | 主标题，`\N` 换行 |
+| `--subtitle` | 副标题，比主标题晚 `--sub-delay` 秒出现 |
+| `--font` / `--sub-font` | family name |
+| `--anim` | 入场动画，见下表 |
+| `--start` / `--duration` | 出现时间 / 停留时长 |
+| `--fade-in` / `--fade-out` | 淡入淡出时长 |
+| `--size` / `--sub-size` | 字号（1080 宽基准） |
+| `--color` / `--sub-color` | `#RRGGBB` |
+| `--y` | 垂直位置比例，0.42 略高于中心（视觉重心更稳） |
+| `--outline` / `--shadow` | 描边 / 阴影，保证亮背景上也能读 |
+| `--stagger` | typewriter 每字间隔 |
+
+动画类型：
+
+| anim | 效果 | 适合 |
+|------|------|------|
+| `fade` | 纯淡入淡出 | 最安全，任何场景 |
+| `fade-up` | 从下方升起 + 淡入 | 通用首选，有呼吸感 |
+| `zoom-in` | 88% 放大到 100% | 有力量感，适合运动 |
+| `zoom-out` | 112% 收到 100% | 沉稳收束 |
+| `blur-in` | 模糊到清晰 + 轻微放大 | 最柔和，适合风景/治愈 |
+| `typewriter` | 逐字出现 | 有叙事感，字数少时用 |
+| `slide-left` | 从右滑入 | 有方向性 |
+
+#### 可读性硬要求
+
+视频上放字，背景是动的，必须做对比保护，否则遇到亮画面就糊了：
+
+- 深色背景：白字 + `--shadow 1.5`（默认值够用）
+- 亮背景或明暗交替：加 `--outline 2` 描边
+- 复杂背景：加大描边 `--outline 3`，或把 `--y` 挪到画面较暗的区域
+
+#### 挂到 EDL
+```
+```json
+"title": { "ass": "/path/title.ass", "fonts_dir": "~/.cola/assets/fonts" }
+```
+标题作用于**整条时间线**（不是单个片段），所以 `--start` 是相对成片开头的秒数。
+
+#### 验证
+
+渲染后抽标题动画全过程的帧（出现前、淡入中、稳定、消失后），用 `vision_analyze` 确认
+文字内容和时序。
+
+**但要注意验证的边界**：`vision_analyze` 能可靠判断"有没有字/是什么字/清不清晰"，
+**分不清楷体和黑体**——它常把楷体误判成"系统默认黑体"。所以不要用它判断字体是否生效。
+
+`--font` 写错时 libass 会**静默 fallback 到系统默认字体**，不报错。要客观验证，
+故意用一个不存在的字体名再渲一版当对照组，比 PSNR：
+```
+
+# PSNR 明显低于 inf（15-20dB 量级）= 两版画面不同 = 字体确实生效了
+ffmpeg -y -i 待验证.png -i fallback对照.png -lavfi psnr -f null - 2>&1 \
+  | grep -o "average:[0-9.]*"
+
+### 阶段三：渲染
+
+先干跑校验：
+
+```bash
+python3 {baseDir}/scripts/build.py edl.json --dry-run
+```
+```
+确认时长和滤镜链无误后正式渲染：
+```
+```bash
+python3 {baseDir}/scripts/build.py edl.json
+```
+
+## 交付时要说明的
+
+- 成片绝对路径、时长、分辨率
+- **每段素材为什么这么剪**（用了哪几秒、砍了什么、为什么这个顺序），这是用户判断要不要返工的依据
+- 明确指出被丢弃的素材及原因
+
+## BGM 处理
+
+用户没提供 BGM 时，不要直接出无声版就算完事——按下面顺序处理。
+
+### 1. 先自己找无版权音乐
+
+先看本地有没有缓存：
+
+```bash
+ls ~/.cola/assets/bgm/ 2>/dev/null
+```
+```
+没有则从下表的源找：
+
+| 源 | 说明 |
+|-----|------|
+| Pixabay Music | https://pixabay.com/music/ — 全部免费商用，无需署名，首选 |
+| Free Music Archive | https://freemusicarchive.org — 限定 License 筛 CC0 |
+| Incompetech（Kevin MacLeod） | https://incompetech.com — CC-BY，需署名 |
+| Musopen | https://musopen.org — 公领域古典乐 |
+
+用 `web_search` / `web_fetch` 找直链，下载到 `~/.cola/assets/bgm/` 方便下次复用：
+```
+```bash
+mkdir -p ~/.cola/assets/bgm
+curl -sL "<直链>" -o ~/.cola/assets/bgm/<描述性名字>.mp3
+```
+```
+下载后必须验证是真音频而不是 HTML 错页：
+```
+```
+拿到可用音频就直接用它渲染，交付时说明曲名、来源、许可协议（CC-BY 要提醒用户发布时署名）。
+```
+
+### 2. 找不到就给选曲指引
+
+自动下载失败时，**先渲染一份无声版交付**（让用户先看到剪辑效果），同时基于已分析过的画面内容给出具体选曲建议。不要只说"你自己找个 BGM"，必须包含：
+
+- **风格关键词**（3-5 个，中英文都给，方便直接搜）——如 lo-fi hip hop / 日系钢琴 / ambient folk
+- **BPM 区间**——跟成片切点密度匹配：单段 1.5-2 秒配 100-130 BPM，单段 4-6 秒配 60-90 BPM
+- **情绪描述**——如"平静、稍带怀旧，不要高潮"
+- **时长需求**——至少比成片长 2 秒
+- **去哪找**——上表的具体网站，或小红书/抖音站内音乐库
+
+拿到用户的音乐后，只需在原 EDL 里补上 `bgm` 字段重新渲染一次，不要重新分析素材。
+
+### 3. 绝不做的事
+
+不从 YouTube、网易云、QQ 音乐、Spotify 等平台抓取有版权的商业音乐——发到小红书/抖音会被静音或限流。
+
+## 约束
+
+- 素材路径一律用绝对路径。
+- 渲染前必须 `--dry-run` 校验一次。
+- 输出成片放进对应项目的 workspace，不要散落在临时目录。
+- 抽帧产生的临时文件用完清理掉。
+
+## Source
+
+Rewritten for AICUT from [`Fagan1024/smart-video-editor`](https://github.com/Fagan1024/smart-video-editor)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/smart-video-editor/docs/FONTS.md

@@ -0,0 +1,57 @@
+# 本地字体库索引
+
+位置：`~/.cola/assets/fonts/`
+用途：视频标题动画 / ASS 字幕渲染。
+
+**ASS / ffmpeg 用法**：`Fontname` 必须填下表的 **family name**（不是文件名）：
+
+```bash
+ffmpeg -i in.mp4 -vf "subtitles=title.ass:fontsdir=/Users/yunf/.cola/assets/fonts" out.mp4
+```
+
+下表所有 family name 都已实测在 libass 里正确命中（对照"不存在的字体名"的 fallback 渲染做过 md5 差异校验），不会静默回退到系统字体。
+
+预览图：`PREVIEW.png`（每格渲染「骑行Ag8」）。
+
+---
+
+## 索引表
+
+| 文件名 | family name（ass 里用的） | 风格描述 | 许可 | 适合场景 | 是否含中文 |
+|---|---|---|---|---|---|
+| `SmileySans-Oblique.ttf` | `Smiley Sans Oblique` | 得意黑。倾斜粗黑，字面紧、笔画有切角，张力极强，横向压缩显得凌厉 | SIL OFL 1.1 | 短视频大标题首选、运动/潮流/城市探索、需要冲击力的开场字卡 | ✅ 9440 字形 |
+| `Alibaba-PuHuiTi-Bold.otf` | `Alibaba PuHuiTi B` | 阿里巴巴普惠体 Bold。方正现代黑体，字重饱满但不臃肿，字形规整中性 | 阿里巴巴免费商用授权（可商用，**不得再分发/改名/修改**） | 通用标题主力、口播字幕、需要"干净不出错"的商业向内容 | ✅ 28937 字形（全字符集） |
+| `Alibaba-PuHuiTi-Heavy.otf` | `Alibaba PuHuiTi H` | 普惠体 Heavy。极粗黑，笔画间空隙很小，重量感强 | 同上 | 封面大字、数字/价格强调、需要压满画面的粗标题 | ✅ 8167 字形（常用字全覆盖） |
+| `NotoSansSC-Bold.otf` | `Noto Sans SC` | 思源黑体 SC Bold。开源黑体标杆，中性、易读、无个性偏向 | SIL OFL 1.1 | 正文字幕、说明性文字、多语言混排的安全选择 | ✅ 30890 字形 |
+| `NotoSansSC-Black.otf` | `Noto Sans SC Black` | 思源黑体 SC Black。最粗字重，厚重扎实，比 Bold 明显更压 | SIL OFL 1.1 | 标题黑底白字、需要粗但要求"不花哨"的场景、纯商用可再分发场景替代普惠体 | ✅ 30890 字形 |
+| `NotoSerifSC-Bold.otf` | `Noto Serif SC` | 思源宋体 SC Bold。粗细对比明显的现代宋，横细竖粗，端庄有质感 | SIL OFL 1.1 | 文艺向标题、旅拍/人文纪录片、片头引言、需要"高级感"的场景 | ✅ 30928 字形 |
+| `LXGWWenKai-Regular.ttf` | `LXGW WenKai` | 霞鹜文楷。楷体骨架 + 手写笔意，笔画起收有明显运笔感，柔和不锐利 | SIL OFL 1.1 | 文艺向首选、日记/vlog 旁白、散文式字幕、治愈系内容 | ✅ 46490 字形（覆盖最广） |
+| `LXGWWenKaiMono-Regular.ttf` | `LXGW WenKai Mono` | 霞鹜文楷等宽版。西文/数字等宽，中文同文楷；纵向对齐整齐 | SIL OFL 1.1 | 需要逐字对齐的字幕动画（打字机效果）、代码/数据类字卡、时间轴标注 | ✅ 46510 字形 |
+| `ChillRoundGothic_Bold.otf` | `Chill Round Gothic Bold` | 寒蝉圆黑体 Bold。粗圆体，笔画端头全圆角，可爱但不幼稚 | SIL OFL 1.1 | 生活化/轻松向标题、美食、萌宠、亲子、种草类 | ✅ 27148 字形 |
+| `ZCOOLKuaiLe-Regular.ttf` | `ZCOOL KuaiLe` | 站酷快乐体。粗方块化笔画，几何切割感，字形歪斜跳跃，很"玩" | SIL OFL 1.1 | 综艺花字、搞笑/反转字卡、儿童向、需要活泼感的贴片 | ✅ 7053 字形（常用字覆盖） |
+| `ZCOOLQingKeHuangYou-Regular.ttf` | `ZCOOL QingKe HuangYou` | 站酷庆科黄油体。中细字重，字形瘦长带复古装饰味，笔画收尾有小曲折 | SIL OFL 1.1 | 复古/胶片风标题、咖啡馆/文创、需要"有点旧"氛围的场景 | ✅ 9429 字形 |
+| `MaShanZheng-Regular.ttf` | `Ma Shan Zheng` | 马善政毛笔楷书。真毛笔手写，笔画连带倾斜，行气流动，个性极强 | SIL OFL 1.1 | 书法感标题、节气/国风、题字式片头、单行短句（长文会难读） | ✅ 7015 字形（常用字覆盖） |
+| `BebasNeue-Regular.ttf` | `Bebas Neue` | 高瘦压缩全大写无衬线，字宽极窄，纵向拉伸，无小写字母 | SIL OFL 1.1 | 英文标题、大号数字（日期/里程/时间码）、海报式竖排排版 | ❌ 仅拉丁 461 字形 |
+| `PlayfairDisplay-VF.ttf` | `Playfair Display` | 高对比度衬线（Didone 风），细横粗竖，衬线锋利优雅 | SIL OFL 1.1 | 英文文艺标题、杂志风、时尚/旅行、与思源宋体中西混排 | ❌ 仅拉丁 659 字形 |
+| `Inter-VF.ttf` | `Inter` | 现代 UI 无衬线，x-height 高、字腔开阔，小字号仍清晰；可变字重 100–900 | SIL OFL 1.1 | 英文正文/小字标注、UI 截图配字、数据标签、与思源黑体混排 | ❌ 仅拉丁/西里尔/希腊 2849 字形 |
+
+---
+
+## 快速选型
+
+- **要冲击力** → `Smiley Sans Oblique`（倾斜）/ `Alibaba PuHuiTi H`（正）/ `Noto Sans SC Black`
+- **要文艺** → `Noto Serif SC`（宋）/ `LXGW WenKai`（楷）/ `Ma Shan Zheng`（毛笔）
+- **要轻松** → `Chill Round Gothic Bold`（圆）/ `ZCOOL KuaiLe`（跳）
+- **要复古** → `ZCOOL QingKe HuangYou`
+- **要稳妥不出错** → `Noto Sans SC` / `Alibaba PuHuiTi B`
+- **中西混排推荐组合**：思源宋体 SC + Playfair Display；思源黑体 SC + Inter；普惠体 H + Bebas Neue
+
+## 可变字体说明
+
+`Inter-VF.ttf` 和 `PlayfairDisplay-VF.ttf` 是可变字体（VF）。libass 只会用默认实例（Regular / wght 400）。需要粗体时用 ASS 的 `Bold: -1` 让 libass 做合成加粗，或另行下载静态字重文件。
+
+## 许可注意
+
+- 除普惠体外全部为 **SIL OFL 1.1**：可商用、可嵌入视频、可再分发（保留版权声明，衍生字体不得用保留名称）。
+- **阿里巴巴普惠体**：官方永久免费商用，但授权条款禁止再分发字体文件本身、禁止修改和改名。用在视频渲染输出上没问题；不要把 `.otf` 文件打包进对外分发的软件包。
+- 得意黑（Smiley Sans）：OFL 1.1，商用无需授权。