Cena Raiz
原则
- 两个阶段,一个门控。 第一阶段是干净剪辑 + 调色;第二阶段是字幕、图形和图片。(硬规则1强制执行门控。)
- LLM 从原始转写文本 + 按需视觉内容进行推理。 唯一保留的派生工件是打包的短语级转写文本(
takes_packed.md)。其他所有内容在决策时即时推导。 - 音频优先,视觉紧随其后。 剪辑候选来自语音边界和静音间隙。
- 询问 → 确认 → 执行 → 迭代 → 持久化。 在用户用简单英语确认策略之前,绝不触碰剪辑。
- 泛化。 查看素材,询问用户,然后进行编辑——绝不假设视频类型。
- 艺术自由是默认选项。 此处的具体值仅为示例,并非强制性要求。只有硬规则是强制性的。
- 在品味所在之处花费令牌。 机器数据是为程序准备的,不是用来阅读的;验证是数字化的,然后才是可视化的。你的注意力是稀缺资源——将其放在编辑上,而不是解析 JSON 上。(硬规则12和13规定了禁止事项。)
硬规则(生产正确性——不可协商)
- 阶段门控是真实的。 在剪辑获得批准之前,不得进行第二阶段的工作。
- 按片段提取 → 无损
-c copy拼接,绝不允许单通道滤镜图。(在默认的 J-cut 下,一个镜头的画面和声音作为独立范围提取,音频轨求和——这是唯一认可的混音方式,视频路径仍然是按片段 + 无损拼接。) - 每个片段边界处有 30ms 音频淡入淡出(已在 render.py 中编码)。
- 绝不在单词内部剪切——从转写文本中对齐到单词边界。
- 在每次剪切边缘添加填充(30–200ms 窗口;尾部略长于头部)。尽可能在静音处剪切。
- 按源缓存转写文本。 除非源文件更改,否则绝不重新转写。
- 在提取期间按片段进行调色,绝不在拼接之后。
- 执行前确认策略。
- 所有会话输出位于
<videos_dir>/edit/——绝不在 cena-raiz 仓库内部。 - 第二阶段仅限 Remotion——无 ffmpeg/PIL 烧录的文本或图形。
- 第二阶段是数据驱动的。 通过复制轨道模板进行构建;在
public/edit-data.json中描述视频。绝不读取或编辑模板 TSX(src/Main.tsx等)——唯一可编辑的代码文件是src/CustomGraphics.tsx,仅用于定制图形。 - 首先进行数值验证。 在每个渲染的剪辑上运行
verify_cut.py;仅对标记的连接点打开图片。将任何多帧检查批量处理为一个contact_sheet.py/grade.py --candidates拼贴图。 - 绝不在上下文中读取机器数据:
transcripts/*.json(原始)、captions.json、track.json、segments.json、遮罩/轨道二进制文件。读取takes_packed.md和辅助工具的标准输出。
执行媒介——本地流水线 vs Adobe MCP
默认引擎是下面的 ffmpeg/Remotion 流水线。对于连接、诊断、能力发现或通过本地 Adobe MCP 进行受控工作,首先阅读 references/adobe-mcp.md。它与客户端无关:从 Codex 和 Claude Code 都适用相同流程。
如果用户要求通过 premiere-pro MCP 在 Adobe Premiere Pro 中进行编辑(“edite a sequência no Premiere”、“corte via MCP”),也请阅读 references/premiere-mcp.md。方法不变——音频优先、在静音处剪切、阶段门控、按品味调色——但操作工具变了。转写和 edl.json 是相同的并已缓存,因此重用已批准的 EDL 并跳过 cut.mp4/预览。After Effects 的写入仍受仓库的受控 Adobe 阶段约束;仅 MCP 可用性并不授权修改。
目录布局
<videos_dir>/
├── <源文件,未修改>
└── edit/
├── project.md ← 记忆;每次会话追加
├── takes_packed.md ← 短语级转写文本,主要阅读视图
├── edl.json ← 剪辑决策(第一阶段)
├── transcripts/<name>.json ← 缓存的单词级转写文本(WhisperX,本地)
├── clips_graded/ ← 带有调色和淡入淡出的按片段提取
├── cut.mp4 ← 第一阶段输出:干净的已调色剪辑(批准工件)
├── verify/ ← 拼贴图/标记的边界视图
├── captions.srt + chapters.txt ← 长视频交付物
├── final.mp4 ← 交付的渲染结果(第二和第三阶段,已 loudnorm)
└── remotion/ ← Remotion 项目(第二和第三阶段)
├── public/ ← cut.mp4, edit-data.json(编辑数据), captions.json,
│ track.json, segments.json, pexels/ web/ brand/, sfx/, trilha.mp3
└── src/ ← 不可变的模板代码 + CustomGraphics.tsx
设置
首次安装位于 install.md。冷启动时只需验证:
- 转写不需要 API 密钥。 WhisperX 作为依赖项包含:
uv sync是完整的安装过程。它使用 Whisper 进行转写,然后对波形运行强制对齐(wav2vec2),因此单词时间是测量的,而非推断的——93% 的单词落在真实语音区域内,语音结束位置精确到 10ms(根据speech_regions.py测量)。速度接近实时,且随着长度增加而提高(加载模型需固定 ~18s:一个 16s 的片段用了 23s,一个 166s 的源用了 109s)。 _transcription_backend中的/UNALIGNED后缀表示检测到的语言没有 wav2vec2 模型,因此单词时间来自解码器本身——粗糙,且对第二阶段卡拉 OK 字幕不安全。如果发生,请告知用户。- 环境 PATH 中包含
ffmpeg+ffprobe;Python 依赖项(uv sync);第二阶段需要 Node 18+。yt-dlp随 Python 依赖项一起提供,因此 URL 源无需额外安装。 - 第二阶段领域知识需要
remotion-best-practices技能(如果缺失,从 https://github.com/remotion-dev/skills 安装)。 - 第二/第三阶段可使用可选的 API 密钥(示例图片、AI 音轨)。它们在轨道参考中列出,在首次使用该功能时惰性请求,绝不会在安装时请求。第一阶段没有任何内容需要密钥。
辅助工具位于 helpers/,相对于此 SKILL.md 解析(通常为 ~/.claude/skills/cena-raiz/ 或 ~/.codex/skills/cena-raiz/,或指向它的符号链接/连接点)。以 uv run python helpers/<name>.py 运行——单纯的 python 会错过 uv sync 构建的 .venv。
辅助工具
第一阶段:
ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080]——从链接编辑:yt-dlp → MP4(≤1080p)直接放入视频目录;然后就像任何其他源一样。--section仅下载长视频源的一个时间范围(关键帧精确)——廉价地剪切 1 小时视频的第 12–25 分钟。--simulate打印标题/时长/分辨率而不下载(在大量下载前确认;在后台运行)。transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo]——单词级、缓存、本地(WhisperX + 强制对齐)。无上限、无分块。当你知道语言时传递--language——自动检测会花费一次传递,并且可能在短片段上选错。transcribe_batch.py <videos_dir>——目录中的每个源,逐个进行(本地推理已使用每个核心)。按文件缓存,一个源的失败不会损失已完成的内容。pack_transcripts.py --edit-dir <dir>——转写文本 →takes_packed.md(短语级,在 ≥0.5s 静音处断开)。主要的阅读视图:令牌量仅为原始 JSON 的 1/10。speech_regions.py <video>——通过 silencedetect 检测声学语音间隔。剪辑边界的真相来源(Whisper 时间会漂移/拉伸)。回答语音在何处——绝不回答多响。voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5]——语音电平的真相来源。标记每个短语、运行和 EDL 范围低于说话者自身中位数 ≥5 dB,并确定gain_db大小。它能捕获其他工具都无法捕获的问题:一个完美的转写文本、speech_regions报告“有语音”、verify_cut未发现任何问题的低声旁白——而观众仍然听不到。在写入 EDL 之前运行它。detect_color.py <video> [--json]——从文件中解析 NORMAL 与 LOG,而非询问——首先尝试元数据,当元数据静默时(常见于转码删除标签)使用图像统计。返回配置文件、置信度、证据以及要应用的grade。仅当confidence: low时才应回退到用户;识别细节位于references/log-grade.md。render.py <edl.json> -o cut.mp4 --no-subtitles [--voice-master] [--keep-resolution] [--jobs N] [--no-jcut] [--jcut-lead N] [--jcut-tail-trim N]——按片段提取(调色 + 淡入淡出,并行)→ J-cut 重叠组装(默认) 或无损拼接 → 可选语音母带 → loudnorm。将jcut_timeline写入 EDL:实际的输出位置,所有下游内容必须据此索引。短视频帧率是自动的:30fps 用于 30fps+ 的源,否则 24(长视频通过--keep-resolution保持源帧率)。设置edit-data.json的fps以匹配生成的cut.mp4。verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2]——数值自评估:时长、每个连接点的爆音/剪切的单词探测、死区、黑帧、削波,以及范围电平平衡(每个范围的 RMS 与中位数范围比较;LOW-LEVEL低于 −4 dB)。约 350 个令牌的文本,而非 N 张图片。范围平衡行是gain_db修复的收敛测试。grade.py <in> -o <out>——调色预设/原始滤镜。--candidates "a=<filter>;b=<preset>;original=" --frame <t> -o cmp.png在相同帧上渲染 N 种外观,生成一个标记的拼贴图。timeline_view.py <video> <start> <end>——为一个标记点生成胶片条+波形 PNG,非扫描工具。contact_sheet.py <video> --times t1 t2 … -o sheet.png——在一个标记网格中显示 N 帧;用于目测已知的几个时刻。watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24]——当你不知道看哪里时,“这段素材里有什么?”:场景检测 + 感知去重 → 在edit/verify/watch_<stem>/中生成标记的联系表,每个表一张阅读。用于未知素材的视觉清单,以及用于在 verify_cut 的数字之外调查cut.mp4。--times固定来自转写文本的提示帧(来自takes_packed.md的指示性时刻,如“olha isso”、“como você pode ver”)具有低视觉变化,对场景检测不可见——固定它们以决定第二阶段中 B-roll/标注/缩放的位置。
第二/三阶段辅助工具(字幕、面部跟踪、图像搜索、音乐)在门控后加载的轨道参考中列出。
接口:
preview_server.py --root <edit> [--port 4820]——提供标准预览界面(参见“预览界面”章节)。应用代码位于assets/preview/并且是不可变的。
预览界面(标准——在每次编辑启动时启动)
每个编辑会话在用户的预览面板中获得相同的交互界面:一个视频编辑时间线(带有胶片条的视频轨 + 带有波形的音频轨)、一个实时播放头可实时拖动渲染结果、每个镜头的修剪手柄和镜头移除,以及从第二阶段开始的字幕和插入轨。布局根据源宽高比自动调整:垂直源将高播放器放在右侧,传输控件 + 时间线在左侧;水平源将播放器堆叠在时间线上方。深色玻璃风格,Cena Raiz 品牌。绝不对每个会话构建 UI——通过 state.json 供给标准界面。仅当用户要求 UI 更改时才允许编辑 assets/preview/;它是共享的,因此改进会对每个项目生效。
启动(在会话开始时执行此操作,即使在第一次渲染之前——UI 会显示等待状态):
-
写入
<edit>/state.json:{"project": "Nome — C0000", "phase": 1, "video": "cut.mp4", "edl": "edl.json", "captions": "remotion/public/captions.json", "editData": "remotion/public/edit-data.json", "finalVideo": "final.mp4", "fps": 24, "message": "Fase 1 — cortando", "sourceDurations": {"C0000": 1038.5}, "awaitingStyle": false, "style": {"edit": "split", "captions": "karaoke", "elements": {"tracking": false, "zoomAuto": true, "zoomCuts": true, "musicAI": false}}}(
captions/editData/finalVideo仅当它们存在时;Fase-2 选项卡播放finalVideo——带有字幕/插入的渲染结果——而 Fase 1 播放干净的剪辑;sourceDurations让 UI 限制镜头的扩展;awaitingStyle/style驱动下面的“样式”选项卡。) -
选择运行时适配器;绝不调用其他主机的工具。
- Claude Code: 确保
.claude/launch.json具有配置(根据会话调整--root)。服务器仅通过标志接受端口,因此传递框架分配的$PORT并设置autoPort:{"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}。运行名为cena-raiz-preview的preview_start,然后在同一轮次中设置Monitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="预览中保存的选择和标记", persistent=true)。 - Codex 桌面版 / CLI: 在环境能保持其运行时,作为后台本地进程启动
uv run python helpers/preview_server.py --root '<edit>' --port 4820。一旦响应,使用control-in-app-browser技能在应用内浏览器自动打开http://127.0.0.1:4820,并将该标签页保留在预览上。不要假设preview_start、Monitor或.claude/launch.json存在。如果浏览器能力或持久本地进程不可用,请向用户提供命令和本地 URL。显示预览后,告诉用户保存并重……
- Claude Code: 确保