diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d29fc6..8e6746b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,9 @@ （两者此前都没有被文档记录）。 - 文档：lint 现在是工作流里的显式阶段，位置在生成字幕之后、渲染之前。 - 文档：删除对私有客户项目的引用，使技能可以公开发布。 +- 文档：README 精简 —— 移除**面向智能体执行**的七条命令序列与「命令参考」表（这些属于 + `SKILL.md` 的职责），改为只向使用者交代**视频项目结构**与产物位置；同时删去「路线图」 + 与文末作者签名。-150 行，中文 364→295 行、英文 390→319 行。 - 许可：风格目录衍生自 Apache-2.0 内容，现已带上完整的来源署名。 ### 备注 diff --git a/README.en.md b/README.en.md index 851ff95..0f5ad1b 100644 --- a/README.en.md +++ b/README.en.md @@ -99,30 +99,10 @@ exception and only reads `.claude/skills/`.) --- -## Quick start +## Video project layout -A video takes **seven commands**, all run inside the **video project directory**: - -```bash -PY= # expand to an absolute path when briefing a sub-agent -SKILL= - -# 0 · scaffold a project (tree + config + theme + both cover templates) -"$PY" "$SKILL/scripts/new_project.py" ~/videos/sky-blue sky-blue --topic "why the sky is blue" -cd ~/videos/sky-blue -# …fill narration.json, fill project.json's order, author one frames/.html per scene… - -"$PY" "$SKILL/scripts/tts_build.py" --project . # 1 · voiceover -"$PY" "$SKILL/scripts/timeline_build.py" --project . # 2 · global timeline -"$PY" "$SKILL/scripts/subs.py" --project . # 3 · subtitles + beats -"$PY" "$SKILL/scripts/lint_frames.py" --project . # 4 · audit frames before rendering -node "$SKILL/scripts/render_video.mjs" . --preview 30 # 5 · 30-second draft first -"$PY" "$SKILL/scripts/qc_check.py" --project . # 6 · QC -node "$SKILL/scripts/render_video.mjs" . # 7 · full render -node "$SKILL/scripts/cover_build.mjs" . # + both covers -``` - -Output lands in `out/`: `slug.mp4`, `cover_169.png`, `cover_34.png`, `slug.srt`, `slug.vtt`, plus +Say one sentence and the agent walks the whole pipeline inside a **video project directory**; +output lands in `out/`: `slug.mp4`, `cover_169.png`, `cover_34.png`, `slug.srt`, `slug.vtt`, plus `qc_report.md` and `qc_sheet.jpg`. A **video project** looks like this: @@ -137,12 +117,6 @@ my-video/ └── out/ # MP4, covers, SRT/VTT, QC report ``` -The order matters: `beats.js` is derived from the TTS output. That is why, after you edit the -narration, everything downstream re-times automatically while no scene code changes. - -> **If you plan to reuse the rendered PNGs, always pass `--keep-frames`.** Preview mode clears the -> frame directory after muxing by design. - --- ## Why not screen recording @@ -203,30 +177,6 @@ flowchart LR --- -## Command reference - -| Command | Purpose | -|---|---| -| `new_project.py --topic "..."` | Scaffold a project | -| `tts_build.py --project .` | Synthesise voiceover (caching, timeouts, backoff retries, silence trim) | -| `timeline_build.py --project .` | Global timeline + stitched `narration-full.mp3` | -| `subs.py --project .` | Three subtitle outputs + one `beats.js` per scene | -| `lint_frames.py --project .` | Audit frames against the eight contract rules | -| `render_video.mjs ` | Render and mux the MP4 | -| `qc_check.py --project .` | Loudness / duration / stream checks + contact sheet | -| `cover_build.mjs ` | Render both covers, 2× by default | - -Common optional flags: `--preview N` renders only the first N seconds, `--keep-frames` keeps the -frame PNGs, `--only id,id` audits just the named scenes, `--scale N` sets the output multiplier. - -A few handy extras: `peek_frame.mjs ` (screenshot one scene in seconds — the one you -reach for while designing), `make_theme.py --topic "medical" --use` (derive a palette from a topic -word), `package_skill.py` (build a portable zip). - -**Full flag reference is in [`SKILL.md`](SKILL.md), or pass `--help` to any script.** - ---- - ## The `B()` beat system `subs.py` emits one `beats.js` per scene, exposing each subtitle block by its **source text**, so @@ -319,7 +269,7 @@ authoring model — that is the domain of the sibling project --- -## Prior work and sibling projects +## Reference project ideas `html-explainer` did not invent its methodology. It has two clear sources of ideas. Both are **independent projects by different authors — not the same author as this one**, and this @@ -350,16 +300,6 @@ you want frame-level reproducibility, use this one. --- -## Roadmap - -- [ ] Per-scene render switch (`--only `) — today this needs the temporary-project workaround -- [ ] Cover layout measurement tool (line count / margins / overlap / hook font size in one pass) -- [ ] More cover aspect ratios -- [ ] English descriptions in the style catalogue -- [ ] Optional music bed with automatic ducking under narration - ---- - ## Contributing Issues and PRs are welcome. The most valuable contribution is a **diagnosed silent failure** added @@ -377,14 +317,3 @@ MIT covers the original code and documentation. Bundled third-party components a style specifications remain under their own terms; GSAP is bundled under GreenSock's [standard "no charge" licence](https://gsap.com/standard-license). Full notices are in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) (Chinese). - ---- - -
- -**Author: Moh** - -Built because "edit one sentence, then re-align the entire video by hand" is not a good way to -spend an afternoon. - -
diff --git a/README.md b/README.md index 546b201..191495e 100644 --- a/README.md +++ b/README.md @@ -95,33 +95,13 @@ Windows 上 `~` 就是 `C:\Users\<你的用户名>`。 --- -## 快速开始 +## 视频项目结构 -一条视频由**七条命令**跑完，都在**视频项目目录**里执行： +说一句需求，智能体会在一个**视频项目目录**里走完整个流水线；产物落在 `out/`： +`slug.mp4`、`cover_169.png`、`cover_34.png`、`slug.srt`、`slug.vtt`，外加 `qc_report.md` +与 `qc_sheet.jpg`。 -```bash -PY=<你的 venv python 路径> # 派给子智能体时要展开成绝对路径 -SKILL=<技能安装目录> - -# 0 · 建项目脚手架（目录树 + 配置 + 主题 + 两份封面模板） -"$PY" "$SKILL/scripts/new_project.py" ~/videos/sky-blue sky-blue --topic "为什么天空是蓝色的" -cd ~/videos/sky-blue -# …填 narration.json、填 project.json 的 order、为每个场景写一个 frames/.html… - -"$PY" "$SKILL/scripts/tts_build.py" --project . # 1 · 配音 -"$PY" "$SKILL/scripts/timeline_build.py" --project . # 2 · 全局时间轴 -"$PY" "$SKILL/scripts/subs.py" --project . # 3 · 字幕 + 节拍 -"$PY" "$SKILL/scripts/lint_frames.py" --project . # 4 · 渲染前体检画面 -node "$SKILL/scripts/render_video.mjs" . --preview 30 # 5 · 先出 30 秒样片 -"$PY" "$SKILL/scripts/qc_check.py" --project . # 6 · QC -node "$SKILL/scripts/render_video.mjs" . # 7 · 全片渲染 -node "$SKILL/scripts/cover_build.mjs" . # + 封面双方案 -``` - -产物都在 `out/`：`slug.mp4`、`cover_169.png`、`cover_34.png`、`slug.srt`、`slug.vtt`， -外加 `qc_report.md` 与 `qc_sheet.jpg`。 - -**视频项目**长这样： +项目目录长这样： ``` my-video/ @@ -133,12 +113,6 @@ my-video/ └── out/ # MP4、封面、SRT/VTT、QC 报告 ``` -顺序不能乱：`beats.js` 由 TTS 产出推导而来。这就是为什么改了解说词之后，下游全部自动重排 -时序，而画面代码一行都不用动。 - -> **只要打算复用渲出来的 PNG，就一定要加 `--keep-frames`。** 预览模式在合成后会按设计 -> 清空帧目录。 - --- ## 为什么不用录屏 @@ -195,29 +169,6 @@ flowchart LR --- -## 命令参考 - -| 命令 | 作用 | -|---|---| -| `new_project.py --topic "主题"` | 建项目脚手架 | -| `tts_build.py --project .` | 合成配音（带缓存、超时、退避重试、裁静音） | -| `timeline_build.py --project .` | 全局时间轴 + 拼接 `narration-full.mp3` | -| `subs.py --project .` | 字幕三出口 + 每场景 `beats.js` | -| `lint_frames.py --project .` | 按八条契约静态体检画面帧 | -| `render_video.mjs ` | 渲染并合成 MP4 | -| `qc_check.py --project .` | 响度 / 时长 / 流体检 + 抽帧速览图 | -| `cover_build.mjs ` | 渲染封面双方案，默认 2 倍图 | - -常用可选参数：`--preview N` 只渲前 N 秒样片、`--keep-frames` 保留帧 PNG、 -`--only id,id` 只体检指定场景、`--scale N` 输出倍率。 - -另有几个顺手的小工具：`peek_frame.mjs `（单场景秒级截图，改画面时最常用）、 -`make_theme.py --topic "医疗" --use`（按主题词推配色）、`package_skill.py`（打成可移植 zip）。 - -**完整参数表见 [`SKILL.md`](SKILL.md)，或对任一脚本加 `--help`。** - ---- - ## `B()` 节拍系统 `subs.py` 为每个场景生成一份 `beats.js`，把每块字幕按**原文**暴露出来，于是画面动画可以直接 @@ -302,7 +253,7 @@ tl.fromTo('.verdict', { scale: 0.8 }, { scale: 1, duration: 0.6 }, --- -## 参考思路与姊妹项目 +## 参考项目思路 `html-explainer` 的方法论不是凭空来的。它有两处明确的思想来源，两个项目都**由不同作者独立 开发，与本项目不是同一作者**；本仓库不打包、运行时不依赖它们的任何代码 —— 吸收的是设计规范 @@ -327,16 +278,6 @@ tl.fromTo('.verdict', { scale: 0.8 }, { scale: 1, duration: 0.6 }, --- -## 路线图 - -- [ ] 单场景渲染开关（`--only `）—— 目前需要临时项目法绕过 -- [ ] 封面排版终态测量器（行数 / 四边边距 / 元素重叠 / 钩子字号一次判完） -- [ ] 更多封面比例 -- [ ] 风格目录补英文说明 -- [ ] 可选背景音乐轨，并对解说自动做闪避（ducking） - ---- - ## 参与贡献 欢迎提 issue 和 PR。最有价值的贡献，是一条**已被定位的静默失败**，加进 @@ -352,13 +293,3 @@ tl.fromTo('.verdict', { scale: 0.8 }, { scale: 1, duration: 0.6 }, MIT 覆盖原创代码与文档。第三方组件与衍生出的风格规范仍适用其各自的条款；GSAP 按 GreenSock 的 [standard "no charge" 许可](https://gsap.com/standard-license) 内置。完整声明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。 - ---- - -
- -**作者：Moh** - -做这个项目，是因为「改一句话然后把整片手工重新对位一遍」实在不是一种好的过下午的方式。 - -