/vlog-from-clips

name: vlog-from-clips
description: 用户把一堆原始片段（相机、手机、运动相机拍的多段素材，常在一个文件夹里）交给你，要剪成一条 vlog、旅拍、活动或生活记录时用：逐段转写、取帧看画面、记素材日志，以本人说的话为主线挑段，没人说话的好画面做 B-roll，剪到目标时长，再按需加字幕、配乐与封面。只有一条对着镜头的录音用剪口播；配旁白讲一件事用解说混剪。
version: 1.0.0

素材剪 vlog

用户拍了一天、一趟旅行或一场活动，手上是几段到几十段原始片段：有对着镜头说的话，有和同伴的对话，有风景、路上、吃的、动作，也有开机关机、镜头对着地面、拍糊了的。用户要的是一条讲得通的片子：看完知道这一天发生了什么、主角在想什么，节奏不拖，长度合适。素材多半用不完，也不该用完。

最容易剪坏的样子有三种：

• **按文件顺序首尾拼一遍**，每段只砍掉头尾。这是素材合集，不是片子。
• **只读转写不看画面**。没人说话的风景和动作镜头全被丢掉，片子只剩一张嘴；或者把晃、糊、对着地面的那几秒也剪了进来。
• **把别人的话当主线**。同伴、路人、店员说得多，就成了片子的主角。

顺序：

1. 和用户对齐（第 1 节）。 2. 全部导入，按拍摄顺序摆上时间线，存一版（第 2 节）。 3. 每段都转写、取帧，写素材日志（第 3 节，格式在 `references/footage-log.md`）。 4. 认出哪个声音是本人（第 4 节）。 5. 写剪辑表：结构、每段用哪一截、合计多长（第 5 节）。 6. 在时间线上剪（第 6 节）。 7. 字幕、声音与封面（第 7 节）。 8. 验收与交付（第 8 节）。

1. 先和用户对齐

缺什么问什么，已说明的不再问；用户只说了「剪成一条 N 分钟的 vlog」时不追问细节，按下面的默认值做，并在回复里说明用了什么：

• **时长**：用户给了就按它，上下浮动一成以内；没给就按素材里值得留的内容定，不凑整，不为凑长度留弱的段落。
• **平台与画幅**：默认横版，画幅与帧率按多数素材。要竖版时，取景照 `talking-head-cut` 里竖屏取景的做法（用 `skills_read` 读 `talking-head-cut`）。
• **主角**：默认是用户本人，主线是本人说的话。
• **字幕、配乐、封面**：默认带原文字幕；用户给了音乐就用用户的，否则低音量配乐；封面在用户要时做。
• **不能出镜的人和地方**：素材里有路人的正脸、家里的门牌、车牌、屏幕上的私人信息时，在报告里点出来，由用户定，不擅自删也不擅自留。

2. 全部导入，摆成素材总表

• 用户给的是文件夹时，先列出里面的视频与照片，按拍摄先后排：文件名里有拍摄时间（很多相机这样命名）就按它，没有就按文件的修改时间，两者都靠不住时按文件名排并告诉用户。报一句共有几段、总长多少。
• 用 videos_create 新建一部视频：画幅与帧率按第 1 节；横竖混拍时按成片的画幅，另一种画幅的片段之后再定取景。
• 用一次 edits_apply 把全部片段按拍摄顺序首尾相接放上时间线：每段一个 `importAsset` 加一个 `addItem`，用 `ref` 连起来。导入默认链接原文件、不复制，告诉用户剪完之前不要移动或改名那些文件；用户要收进视频时用 `storage` 为 `managed`。照片先不放，第 5 节决定用哪几张。
• 放好之后用 videos_save_version 存一版（名字如「原始素材」）。这条完整的时间线是素材总表：取帧与找镜头都要片段在时间线上；之后剪坏了随时能回到这一版。原文件始终不动。

3. 素材日志：每段都过一遍再动刀

每一段都要既听过又看过，才知道它能不能用、用在哪。

• **转写**：每个片段各转写一次（transcribe 给 `video` 与这段的 `asset`）；可能有不止一个人说话时给 `diarize` 为 true。彼此独立的转写一次都提交，再用 jobs_wait 等；没人声的片段转写很短或是空的，照样记下。人名、地名与术语照 `polish-transcript` 校对，要做字幕的片段在建字幕前校对完。
• **取帧**：每段用 videos_frames 的 `range`（这一段在时间线上的起止秒）加 `count` 等间隔取帧：长段每 3–5 秒一帧，短段至少 3 帧；`maxWidth` 给小一些（如 480），读图省力。一次最多 24 帧，彼此独立的取帧一次发完。一段里有几个镜头时先用 videos_shots 找切换，再按镜头的 `sampleAt` 取。可疑的几秒（晃、糊、过暗）加密再看。
• **读人脸**：帧里的 `faces` 是人脸框。脸大、居中、在多数片段里反复出现的，多半是手持自拍的本人；读 `faces`，不凭看图估。
• **写日志**：一段一行，写进工作目录的 `footage-log.md`（格式与例子在 `references/footage-log.md`）：在哪、拍到什么、画面质量、说了什么（关键原话带素材时间）、谁在说、可以用在哪。
• 片段多时，能派子代理就按段分头写日志，结果写文件，不写在回复里；合起来之后自己从头读一遍。

4. 哪个声音是本人

• 每段转写的说话人编号只在那一段里有效：这一段的「说话人 1」和下一段的「说话人 1」不一定是同一个人。BaoCut 不会跨片段认声音，要你自己对上，并写进日志的「谁在说」。
• 证据，按强弱：说话时画面里正对镜头、脸大而居中的那一位；自我介绍或被叫名字；在大多数片段里都出现、说得最多的声音；内容（「我现在在……」「我们今天……」）。只凭「说得最多」不够。
• 有几段拿不准时，把那几句（片段、素材时间、原话）列给用户，请用户确认是不是本人；不要猜。
• 本人的话是主线。同伴、路人的话只在有意思、和故事有关、观众听得懂时留，说话的人最好在画面里。

5. 剪辑表：先定结构，再动刀

读完日志写一份剪辑表，写进工作目录的 `edit-list.md`（格式同样在 `references/footage-log.md`）：

• **结构**：开头、几个段落（按时间或地点分）、结尾。默认按时间顺序讲。开头可以先放全片最好看或最有意思的一瞬（几秒），再回到起点讲。结尾落在一个收得住的画面或一句话上，不停在半截。
• **每一行**：用哪个片段、素材上的起止秒（素材时钟）、用途（主线、B-roll、开头、过渡、结尾）、一句理由；最后合计时长。时长对不上目标时在表上增删，不在时间线上试。
• **主线怎么取**：本人的话按整句取，起止取第一个词的开头到最后一个词的结尾（转写的词时间换成素材秒），两头各留一点余量。同一段话说了几遍时可以用 speech_retakes 找出几遍，挑完整、自然、节奏好的那遍。口癖与长停顿的收紧照 `talking-head-cut` 第 2、3 节。
• **B-roll 怎么取**：没人说话、画面好的几秒（风景、路上、吃的、动作、表情）讲到它时出现，每段 2–6 秒；盖在主线之上，或接在两段话之间当过渡和呼吸。同一片段的画面不要连用十几秒没有变化。
• **不用的**：开机关机的头尾，晃、糊、过暗、镜头对着地面或口袋的段落，重复的机位，和故事无关的好画面。不用的也在表上写一行，说明为什么不用，方便用户找回来。
• 用户说了「直接剪」或只给了一句话时，表写好就剪，交付时附上；用户说要先看计划，或素材里有拿不准的取舍（某个人能不能出镜、两种讲法差别大）时，先把结构（一段一行）与合计时长给用户确认。

6. 在时间线上剪

• **两个时钟**：转写的词时间、剪辑表的起止和 `addCuts` 用素材自己的秒；`splitItem`、`moveItems`、`removeRange`、videos_frames 的 `at` 与导出的范围用时间线上的秒。素材上的时刻 t 在时间线上 = 那个片段的 startSeconds +（t − sourceInSeconds），两个值在 videos_inspect 的片段里。不凭感觉换算；每一笔改完都重新 videos_inspect 再算下一笔。
• **剪掉每段里不用的部分**：从素材总表那一版开始，对每个要用的片段用 `addCuts` 剪掉剪辑表没留的源区间（素材秒；剪口可以 `restoreCut` 恢复，后面的内容会跟着前移）。所有片段的剪口放进同一次 edits_apply，一步撤销。
• **整段不用的片段**：重新 videos_inspect，按它在时间线上的起止用 `removeRange` 收掉（`trackIds` 列出所有有内容的轨道），从时间线的后面往前做，免得前面一删后面的位置全变。
• **调序**：默认按拍摄顺序，基本不用挪。开头要先放的那一瞬照 `talking-head-cut` 第 4 节：原位置也要保留时在开头另放一份同一段素材，不挪原片段。别的调序按剪辑表做，用 `splitItem` 切开、一次 `moveItems` 挪好。
• **B-roll 最后放**：剪口与顺序定下后，在主线上面加一条视觉轨，把 B-roll 片段放上去，用 `trimItem` 裁到剪辑表的范围；它的原声多半要关掉或压低（`setAudioMix`），主线的话继续从下面出声。
• 各操作的完整写法用 edits_ops 查。剪完存一版（videos_save_version，名字如「初剪」）。

7. 字幕、声音与封面

• **接缝的声音**：不同片段的环境声音量与底噪差别大，接缝处听得出跳。片段相接的地方给很短的淡入淡出（`setAudioMix` 的 `fadeIn`、`fadeOut`，0.1–0.3 秒起），只在需要的地方加。
• **字幕**：每个用上的、有人说话的片段的转写各建一层原文字幕（captions_create 给那份转写的 `documentId`），字幕跟着片段走。要译文或双语时照 `translate-subtitles`。样式与位置用 `skills_read` 读 `baocut-catalog-subtitles`；竖版要挪出平台控件区。
• **修素材**：手持晃得厉害的段落先用 assets_process 的 `stabilize`，几段光线差得多时用 `match-color` 对齐到选定的一段；都只处理用到的那一截（`start`、`end`），结果用 assets_import 导入。没人说话的段落里找空档用 assets_dead_air（`method: motion` 或 `both`）。
• **配乐**：用 `skills_read` 读 `baocut-catalog-music`。用户给了音乐就用用户的；没有时本机能生成就按这期的地点、情绪写风格，成片时长定了再生成。配乐压在人声之下（setDucking，触发选有人说话时），本人说话的段落压得更低，纯画面的段落可以抬起来。
• **封面与标题**：用户要时照 `cover-and-title`，候选帧从日志里画面好、本人表情或动作有张力的那几段里挑。

8. 验收与交付

• **读回**：videos_inspect 看总时长与片段，对照剪辑表逐行核对：该留的在，该剪的剪了，顺序对；总时长和目标差多少。
• **看画面**：用 videos_frames 在每个段落的开头、中间、结尾取几帧，确认没有糊的、对着地面的、黑的画面。帧取的是那个时刻最上层视频片段的素材画面（上层的 B-roll 取得到），字幕、文字与叠加的元素不在里面，取景与裁剪也没套用；要看合成后的效果，用 export 给 `purpose` 为 `preview` 与几个 `ranges` 导出几小段再看。
• **要人听**：接缝顺不顺、配乐压没压过人声、本人认得对不对，只能人耳听。导出几小段给用户听，报告里写明哪些只是量出来的。
• **报告**：分三栏写，量出来的（片段总数与用上的段数、总时长、剪口数）、看过的（看了哪几处、看到什么；没看的写没看）、要人听的。另附剪辑表与素材日志的位置、不用的素材里可能值得找回的几段、第 1 节里点出的隐私问题。

9. 要避免的

• 不要按文件顺序拼一遍就交，不要只读转写不看画面。
• 不要把别人的声音当成本人；拿不准就问。
• 不要为了凑时长留弱的段落，也不要为了凑短把一句话从中间截断。
• 不要把素材时钟和时间线时钟混用；不要拿旧的时间线位置做下一笔。
• 不要动原文件；不要不说一声就把不用的素材从视频里删掉（剪掉的部分要找得回来）。
• 不要把没听过的说成「顺」，把没看过的说成「没问题」。

参考文件

| 文件 | 什么时候读 | | --- | --- | | `references/footage-log.md` | 写素材日志与剪辑表之前 |