从长视频里切短视频

刷到这条短视频的人没看过长视频，也不知道前面讲了什么。头三秒没抓住他，他就划走了；中间出现「刚才说的那个」，他就不知道在说什么。所以一段短视频要自己站得住：开头就是钩子，只讲一件事，停在结论上。

挑的单位是话题：一件事从提出到讲完。一个观点和它的理由，一个问题和它的回答，一个故事和它的落点。一支短视频就是一个话题完整的一段，不多也不少。

最容易挑坏的两种样子：

• 按长视频的章节切。一章十分钟，开头铺垫三句才说到点子上，结尾停在「接下来我们看」，里面还夹着两个话题。那是长视频的一段，不是一条短视频。
• 只找金句。一句很响的话，前后各凑几秒到要的时长：话题刚开头或还没落地就断了，观众听到一个结论却不知道为什么，或者只听到一半。

交付的是可编辑的子视频，不是 mp4：每一段用 videos_derive 建成父视频旁边的一个独立视频，用户在编辑器里继续调入出点、画面和字幕，要文件时再导出。

1. 先有转写

没有转写（kind 为 speech 的文档）时先转写，告诉用户转写在进行。挑片段只需要原文的词时间；润色和翻译只在用户要时才做。视频已经有章节时，章节有助于定位话题，但章节的边界不是短视频的边界。

2. 读文稿，找话题

读带时间的文稿：export 导出字幕（kind subtitles、format srt）或带时间码的文稿（kind transcript、format md、timestamps true），给 purpose preview（只是你自己读，不是交给用户的），jobs_inspect 等到 completed，读 outputs 里的文件。这些时间是剪辑后时间线上的时间，和 videos_derive 的 start、end、取帧用的是同一个时钟。

句界怎么取：找句子的起止不用 dump 整份 speech 文档。documents_read 读转写时，返回的 translationBasis.sentences 每一句带 start、end（秒），但那是素材时钟；videos_derive 的 start、end 是时间线时钟。父视频从 0 秒开始、原速、没有剪口地播放这条素材时，两者相同，可以直接用句子的 start、end 定区间。先确认这一点：用 videos_inspect（或 facts）看视频项的 sourceIn 是否为 0、速度是否为 1、有没有剪口。任一条不满足，就用上面导出的 SRT 或文稿里的时间线时间，或者把素材时间换算成时间线时间再传，不要把素材时间直接当时间线时间用。

用户点了话题（「切一支讲 X 的」）时，先用 space_search_v2（query 写 X 的意思，videoIds 只给这部视频，kinds 给 ["speech"]）找讲到它的几处，再按上面读那几段前后的文稿定区间；命中的时间在当前时间线上（clock 为 sequence）时可以直接当时间线时间用；needsResolve 的先用 space_resolve_search_hit 按当前版本重新定位；weak 的先读原文。没有语义索引时（effectiveMode 为 lexical）换几个关键词再找，或读全文。

已经切过的：space_list 给 videoId 列出这部视频派生的短视频，读它们的名字与区间，不重复切同一段；用户要再切一支同一话题的时先问。

先画话题地图

通读整份文稿（用户给了范围就读那一段），按话题切开：换了一个问题、一个观点、一个故事，就是新话题的开始。每个话题记下大致的起止、一句话说它讲什么、落点（结论、答案或包袱）在哪一句。一章里常有几个话题，一个话题也可能跨过章节边界。

挑最好的话题

够格的话题三条都满足，缺一条就不要：

• 有看点：至少是这四种之一：反常识的说法、情绪的高点、密集的干货、带转折的小故事。
• 单独成立：不看长视频也听得懂，没有「刚才说的那个」「第二点」这类要看前面才懂的指代。
• 有头有尾：话题里有一句能直接开场的话（见下面「开头那句就是钩子」），也讲到了落点。

文稿只是线索：对够格的话题，用 videos_frames 在那几秒取几帧看画面（有没有可看的、说话人在不在画面里），再结合上下文判断是认真说的还是玩笑。帧是素材画面，不含字幕与叠加的元素。然后按看点强弱、成立得稳不稳排序，最强的在前。

几支

• 用户给了数（参数页预填的话写明了支数，例如「要 N 支」）：取最强的 N 个话题。够格的不足 N 个时只建够格的，不拿弱话题凑，并告诉用户为什么少了。
• 自动（预填的话让你按话题定几支，例如「几支由你按话题定」，或用户没说）：够格的话题有几个就建几支，不凑数，也不因为话题多就降低门槛。超过 10 个时先建最强的 10 支，其余在回复里列成候选（入点、出点、一句话讲什么），用户要再建。
• 两支不共用同一段话：两个候选重叠时只留更强的那个。

每支多长

• 自动（预填的话让你按话题定长短，例如「每支多长按话题定」，或用户没说）：长度就是这个话题的长度。起点是话题里第一句能直接开场的话，终点是落点那句说完。不为凑时长带上铺垫或下一个话题的开头，也不为压时长砍掉中间的理由或例子。话题中间夹着一大段离题的话、拖得太长时，取话题里能单独成立、也有落点的那一半，或换一个更紧的话题。
• 用户给了范围（可能是 15–30、30–60、60–90 秒，1–3 分钟或自定义）：在范围里找能讲完的话题；话题比范围长时，取它里面一个能单独成立、有落点的小点。装不下也拆不出的话题宁可不要，不切成半截；为了停在句尾超出范围几秒可以，在 reason 里写明。
• 不设平台上限：超过 3 分钟只提一句，YouTube 不按 Shorts 收，其余照做。自动定的长度超过 3 分钟时，先看是不是包了两个话题，能拆就拆成两支。

边界

• 一个短视频只讲一件事：一段里有两个话题时，拆成两支，或只留一个。
• 开头那句就是钩子：话题开头常有铺垫（「那我们聊聊……」「其实这个问题……」），把起点挪到话题里第一句能直接抓人的话：一个反直觉的结论、一个具体的数字、一个问题。挪过之后后面的话仍要听得懂；听不懂就是挪过了头，或者这个话题没有好开头，换一个。
• 结尾停在落点上：停在结论或包袱说完的那一句，不停在「接下来我们看……」这种半句话上；结尾是「关注、订阅」一类的话时，把终点提前到上一句。
• 开头 3 秒要有人说话：没有时把起点挪到第一句话；不在前面加标题卡。
• 入点与出点落在句子边界：入点取开头那句第一个词与它前一个词之间停顿的中点；出点取最后一个词与下一个词之间停顿的中点。不切进词里。边界拿不准时，略放宽一点：用户在编辑器里收比补回来容易。
• 停顿短于一帧（约 40 毫秒）时，「取停顿中点」不成立：中点落不到一个整帧上，取整会吃进下一个词或吞掉上一个词。运行时现在会把边界收进停顿里（终点不吃下一个词的起点，起点不吞上一个词的结尾），返回的 range 是实际采用的值，可能和你传的差几帧。创建后核对返回的 range 与你要的差值：差得多、或开头结尾的词因此被截，就换一个边界重新创建，不要放着不管。
• 访谈：优先一个人不被打断的整段。允许从回答的第一句完整句开始。开头依赖上文的句子（「另一种说法是」「这就像刚才说的」）不要当开头，往后挪到能自己成立的那一句。采访者夹一两句短插话可以接受，但要在理由里写明在哪几秒、说了什么。
• 台标、边框、水印是 go/no-go 检查：取了帧之后看角落与边缘有没有台标、赞助条、烧进去的字幕、边框。要用的裁框会把它们切掉一半或留下半个字时，按第 4 步取景里让开台标的规则让开（裁框整个躲开台标，上下的边框裁掉），让不开就换片段，并告诉用户做了什么选择；不要留着半个台标交付。
• 已经切过的不再找：用户提到（预填的话里有「已经切过的不再找」）或你怀疑切过时，space_list（videoId 填父视频）看已派生的子视频（origin.source 为 derived）和它们的区间，新的候选避开这些区间。
• 视频剪辑过时，文稿里的时间已经是剪辑后的；用户想按剪辑前的原素材切时，先和用户确认用哪个版本。

对比一下（只是示意）：

不好：12:00–14:30，从「好，那我们接下来聊聊成本这块」开始，到「这个我们待会儿再展开」结束。

好：12:41–13:22，从「我们算过，一条视频的成本其实只有三块钱」开始，到「所以贵的从来不是生成，是返工」结束。

后一段是一个完整的话题：头一句就是数字，中间是理由，停在结论上，没有指代前文的话。

3. 先创建还是先给用户看

• 用户的话里有「找好就直接创建成视频，不用先问我」这类意思（参数页预填的话默认带这一句）：找好直接进第 4 步，不在会话里一段段确认。
• 没有这句，或用户说「先给我看」：先列候选等用户挑。每段写入点与出点、讲的是哪个话题（一句话）、开头那句原话、亮点、为什么能单独成立、发现的问题（例如画面上有烧进去的字幕、分屏或并排的双机位、角落的台标或赞助条，竖屏裁切时会被切掉一半；访谈里另一人说话时画面里没有说话人）。取了帧的说看了哪几处；没看过画面的就说没看过。按把握从大到小排，用户挑定后再创建；用户说「你定」时自己定，并说明理由。

不需要在会话里反复问边界：子视频保留着整份时间线与文稿，用户在编辑器里点划掉的句子就能把它放回来。标题和理由用用户说话的语言写。

4. 创建子视频

对每一段调用 videos_derive：

• video 是父视频，start、end 是剪辑后时间线上的秒，name 用片段标题。
• 画幅：用户要 9:16 时 width 1080、height 1920；1:1 时 1080×1080；保留原画幅（或没提）时不传 width、height 和 fit。不要为了「高清」把小尺寸放大。
• 取景：传了画幅就给 fit: "cover"（铺满、裁掉多余）。用户说「居中」：不传 crop 和 crops，居中建好；说「我自己定」：同样居中建好，并告诉用户可以在画布上直接拖动、缩放画面自己摆（一拖就变成自由摆放，之后换画幅不再跟着铺满）。用户没说或说「自动」（默认）：走下面按镜头取景的流程。给的裁框只是取景：子视频里存成取景点，源画面不裁，之后改回原画幅还能看到完整画面。取景是按镜头切换的静态裁框，不是跟随人物的运动镜头：用户要「画面一直跟着说话的人移动」时如实说做不到。带取景点的片段在画布上只能围着取景点放大、缩小（focalPoint.zoom），不能拖动：要换某段对准的位置，你用 setStyle 改那一段的 focalPoint，或请用户在画布上把它改成自由摆放后自己摆（之后换画幅不再自动对准）。
• 取景「自动」怎么做（提示词写的是：看说话的人在画面哪里，把裁框放到他身上；找不到人就居中）：先按镜头切开，每个镜头各自按人脸检测的结果定裁框，不靠看图估位置。
  1. 先分镜头，再取帧：先用 videos_shots 的 range（起:止，这一段的时间线秒）取这一段的 shots（每个镜头有 start、end 和三个 sampleAt）与 cuts。它只检测画面切换，不认人。再用 videos_frames 的 at 传所有镜头的 sampleAt，每次 8 个镜头（24 帧，是单次上限）。每帧的 faces 是检测到的人脸框，x、y、w、h 按帧的宽高归一化到 0–1，对应素材画面，正好是 crop 的坐标。
  2. 先分机位：每个镜头看三帧里的多数。面积（w × h）小于 0.001 的脸是误检，不算；面积不小于最大那张脸 1/4 的是主脸。只有一张主脸的是单人近景；两张以上主脸、左右跨度（最左脸的 x 到最右脸的 x + w）超过竖屏裁框宽 cw（第 5 步的公式）的是多人全景；跨度不超过 cw 的是多人近景；没有脸的另记。不要拿固定的面积阈值分近景与全景：同一部片子里全景的脸可以和别的片子的近景一样大。
  3. 认出主讲人：整段所有镜头合在一起，只看单人近景，把脸按中心横坐标（x + w/2）归成人，相差不到 0.1 的算同一个人。出现的帧数最多的是主讲人；帧数相近时取平均面积大的那个。另一个人的近景就是采访者（或对方）的镜头。
  4. 先看边缘再定裁框：打开几张帧图，看台标、水印、字幕条、赞助条在哪儿，估出它们的边缘（0–1，和 crop 同一套坐标）；再看上下有没有烧进画面的边框（色条、黑边）。
  5. 逐镜头定裁框：用这个镜头自己的三帧，不拿别的镜头的位置代替。裁出的宽度比例 cw = (画布宽 ÷ 画布高) × (原画高 × (1 − top − bottom) ÷ 原画宽)；left = 中心 − cw/2，限制在 0 到 1 − cw 之间，right = 1 − cw − left。实例：16:9 的原画出 9:16、上下不裁，cw = 0.316；脸中心在 0.30 时给 left 0.142、right 0.542。上下有烧进去的边框时，top、bottom 给边框的高度比例把它裁掉（多给一点，不留细边），没有就给 0。
     • 主讲人近景：中心取这个镜头里主讲人脸中心横坐标（x + w/2）的中位数。
     • 采访者近景：中心取采访者的脸，让正在说话的人在画面里，这正是按镜头取景的意义。
     • 多人近景：用能装下所有人的最小裁框，中心取这一群人的中点。
     • 多人全景：按第 7 步分屏。不分屏的（5 人以上、合起来短于 3 秒、提示词说不要分屏）中心取正在说话的人，看不出谁在说时取离画面中心最近的人，并在 notes 里写明。
     • 远景里脸很小时，上下各至多裁 15%（top、bottom 都不超过 0.15）让脸大一些，不超过；有烧进去的边框时，边框高度也算在这 15% 里，边框更高就以边框为准，并在 notes 里说明。
     • 相邻的镜头裁框相差不到 0.02（left 的差，且 top、bottom 相同）时合并成 crops 的一项，from 取前一个镜头的起点，to 取后一个镜头的终点。
  6. 让开台标：逐镜头检查，门槛和以前一样。台标在左边时，left 至少是台标右缘 + 0.01；在右边时，left + cw 至多是台标左缘 − 0.01（right 至少是 1 − 台标左缘 + 0.01）。挪了之后这个镜头的脸被裁出画面、或者两边都让不开时，这个镜头换裁框也不行，就换片段；不要交付压着半个台标的裁框。
  7. 多人全景分屏（画幅变了时；提示词说「不要分屏」时跳过这一步）：一个竖屏框装不下所有人，就每人一格。
     • 相邻的多人全景镜头（中间没有别的镜头）合成一段算时长；合起来短于 3 秒不分屏。版式只在镜头切换处变，不在一个镜头中间变。
     • 2–3 人 layout: "rows"（上下排开），4 人 "grid"（田字格），5 人以上不分屏。crops 的这一项写 {from, to, layout, panels}，panels 是每个人要看见的源区域（四边比例，同 crop）：以这个人的脸为准，左右各留一张脸宽，上面留半张脸高，下面到胸口（脸下面再约 2.5 张脸高），出了画面的边取 0。次序随意：Runtime 按左右排进格子，最左的人在最上面，同一个人在每一段分屏里都在同一格。
     • 同一支里的分屏段用同样的人数；某个全景镜头少了一个人（被挡、出画）时这一段不分屏。区域要让开台标，规则同第 6 步。
     • 单机位（整段只有多人全景、所有人一直同框）：整支分屏，一个 crops 项盖住整段，不按说话人来回切。
  8. 多机位：全景镜头和采访者镜头现在有对应的取景，不再因为它们本身换片段。只剩两条：片段不要以对方的反应镜头开头；没有人的镜头（以及不分屏时的多人全景）合起来超过这一段约 40% 时，优先换一段，并说明原因；换不了就照做，并在 notes 里写明。
  9. 切换点从 videos_shots 来：crops 的 from、to 直接用 shots 的 start、end，是逐帧准确的，不再在估出的切换点前后各 1 秒试探。只有看到某个镜头的三帧明显是两种机位（说明漏了一个切换）时，把 threshold 降到 0.2，对那一小段重跑 videos_shots；或在怀疑的时间点前后用 at 补取几帧。创建时：crops 传全部合并后的项（一人 {from, to, left, top, right, bottom}，分屏 {from, to, layout, panels}；最多 64 项、互不重叠，都是父视频时间线的秒），同时把第一个一人镜头的裁框作为普通的 crop 传上，当作没覆盖到的帧的兜底。
  10. 没有脸：所有帧的 faces 都是空的，居中（不传 crop 和 crops），并如实说没找到人脸。结果的 detector 为 null 时是检测器不可用，不是没人：这时退回看帧图片，逐镜头估主讲人在画面哪一侧，照第 5、6 步的算法给 crops 和 crop，并说明这次是看图估的；看图估不分屏。
• hook、reason、notes：每一支都传。hook 是保留段的第一句原话，原样照抄，不改写（至多 300 字）；reason 一句话说为什么挑它，写给用户看（至多 500 字）；notes 是提示牌字符串数组，写取景、机位、台标检查里发现并需要用户知道的事，没有就不传。
  • notes 每条至多 80 字、至多 8 条，超了整次创建会被拒。一件事一条，拆开写，不把几件事塞进一条。
  • 说到时间时写成「子视频第 X 秒（原片 Y 秒）」，两个时钟都给。一个镜头组一条，只写用户需要知道的，例如「子视频第 9–24 秒（原片 24:54–25:09）两人全景，上下分屏」「子视频第 40–43 秒（原片 25:25–25:28）是采访者，裁到采访者」「上下紫色边框已裁掉」。开头是对方反应镜头时也写上，写成「子视频第 0–3 秒（原片 24:45–24:48）是对方的反应镜头」。
  • 结果页的卡片会显示这三项，回复里不必再重复。创建后核对写进去的是不是你要的：返回结果里回显的 hook、reason、notes 就是派生来源文档里的那份（认回已有的子视频时是原来那份，这次传的不会改写它）；也可以用 documents_read 读返回的 derivationDocumentId。
• chapters: false：30 秒的子视频不该带着父视频的整份章节。
• captions 按用户的字幕要求：要字幕给 true（默认），不要给 false。用户只要原文或只要译文时，字幕层的选择按他的话，做不到的（例如没有译文）如实说。
• 译文：videos_derive 默认把父视频的译文与译文字幕层一并带到子视频；旧格式的译文会自动升级后再带。返回里出现 translations-skipped 警告时，告诉用户哪种语言没带上。
• 核对返回值：range 是实际采用的边界，对一下和你要的差多少（见上面的短停顿）；captions[].cueCount 只数落在区间内的 cue，不是整份字幕的条数，用它判断字幕有没有建出来、数量是否合理。
• 每一支创建后，会话里会自动出一张视频卡，不需要再贴路径。同一区间与设置重复调用会认回已有的子视频（reused 为 true），不会多建。

子视频是什么：整份复制父视频的时间线与文稿，区间之外的部分被剪掉，用户在编辑器里点划掉的句子就能把它放回来；原视频不动。所以不要把哪一支移入回收站，也不要为了「改边界」重建一支，让用户在编辑器里拖。

去口癖、收紧停顿会改动整个视频，不在这里做；用户要时先说明影响，按剪口播的做法在子视频上处理。

要如实转述的 warnings

创建结果里的 warnings 逐条告诉用户，用大白话：

• multiple-assets：父视频不止一份主素材，这一版只按主素材剪，别的素材跟着移动，请用户在编辑器里检查。
• items-not-restorable：整段落在剪掉区域里的其他轨片段不会随「恢复」回来。
• range-not-exact：区间之外有一部分没能剪掉（主素材盖不到），入出点会比要求的略宽。
• captions-skipped：字幕层没建成，说明原因，告诉用户可以在字幕面板里再建。
• crops-adjusted：有一段取景范围被裁短或丢掉了（超出子视频范围，或截完一帧不剩），截掉的那几帧按相邻镜头或兜底的裁框取景；告诉用户是哪几秒：可以在画布上选中那一段放大，要挪位置先改成自由摆放，或请你改那一段的 focalPoint。
• split-short：有分屏段短于 3 秒：先核对合段有没有算错；告诉用户是哪几秒，觉得闪可以在属性面板的「版式」里换回一人。
• panel-upscaled：有几格放得太大（成片一个像素对原片超过 2.5 个），画面会发虚；告诉用户是哪一段，可以在「版式」里调小放大或换回一人。
• panel-region-cropped：有一格装不下你给的区域，这个人被裁掉了一部分；同样告诉用户是哪一段、在「版式」里调。
• panels-ignored：分屏段没生效，按几个人的并集当一人取景了（画幅没变、不是铺满或片段不是全屏）；说明是哪一段。
• animation-split：画面被按取景切成了几段，循环动画或音量包络在每段的交界处会重新开始；告诉用户在哪几秒，有影响时请他在编辑器里检查。
• translations-skipped：父视频的这份译文没能带进子视频（旧格式换不过来），子视频里没有这门语言；告诉用户是哪种语言，可以在子视频上重新翻译。

拒绝的错误（父视频有代码画面、区间为空等）如实说，不绕开。

5. 成片文件

默认交付是子视频，不是 mp4。用户明确要文件时，再对子视频调用 export：kind video、format mp4，jobs_inspect 等到 completed，把 outputs 里的 path 告诉用户。时间线上的字幕默认烧进成片（burnCaptions），不要字幕时给 false。用户想直接导出、不建子视频时，也可以沿用在父视频上按 ranges 导出的老办法，每段一个 {start, end}。

6. 要避免的

• 不要按章节切，不要让一段里有两个话题。
• 不要只围着一句金句凑时长，话题没讲完就断；不要为了凑够支数或时长降低门槛、带上铺垫。
• 不要从铺垫开始，不要停在半句话或「关注订阅」上。
• 不要留着「刚才说的」「第二点」这类指代。
• 不要切进词里；不要在前面加标题卡。
• 没说「先给我看」的，不要一段段停下来问边界；说了的，不要替用户定，除非他说「你定」。
• 不要把没看过的画面说成没问题；不要吞掉 warnings。
• 不要承诺画面一直跟着人移动，按镜头分别取景才是做得到的，用户可以在画布上选中任意一个镜头的那段放大，要挪位置先改成自由摆放；不要整段只用一个裁框（单机位整支分屏除外）；不要在一个镜头中间换版式，不要把合起来短于 3 秒的全景分屏；不要拿别的镜头的脸位置定这个镜头的裁框；不要凭几帧估切换的秒数，用 videos_shots 返回的。
• 不要把素材时钟的句子时间当时间线时间直接传；不要放着返回的 range 与要的差很多而不核对。
• 不要让片段以对方的反应镜头或依赖上文的句子开头；不要交付被切了半个台标或留着烧进去的边框的裁框。
• 不要把几件事塞进一条 note，不要只写一个时钟的秒数。
• 不要导出了 mp4 却说成交付，除非用户要的就是文件；不要把子视频移入回收站。
• 不要把检查用的东西留在用户的文件里：看画面用 videos_frames，不用 ffmpeg 往 exports/ 里截图；为读文稿、试听或看效果而导出的都给 purpose preview，不按 ranges 把片段导出成 mp4 来检查。

7. 交付

收尾时逐支列出，写给用户看：

• 标题、在父视频里的入点与出点、时长、画幅与分辨率。
• 几支或每支多长是你按话题定的：说一句为什么是这几支（例如另外两个话题要靠前文才懂、没有落点），超过 10 个够格话题时列出没建的候选。
• 开头那句原话与为什么挑它已经通过 hook / reason 传给了结果卡片，回复里不再逐支重复；用户在没有结果页的地方（网页端、命令行）看时才逐支写一句。
• 做了什么、没做什么：画幅与取景（原画幅 / 自动按镜头分别取景，其中几段分屏 / 用户自定；任意一个镜头的那段都可以在画布上放大，要挪位置先改成自由摆放；分屏的段在属性面板的「版式」里调放大、互换上下或换回一人）、字幕（有 / 没建）各一句。
• 创建时的 warnings，没有就写没有。
• 发现的画面问题（烧进去的字幕、台标或赞助条、分屏或相邻画面、插话时说话人不在画面里）：有就写；看过而没有写「没看到」；没看画面就写没看。
• 最后一句：子视频在编辑器里可以继续调，想把划掉的话放回来点那句就行；要 mp4 再说。