@speclip/pi-talking-head 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @speclip/pi-talking-head
 
-给 [Pi](https://github.com/earendil-works/pi) 用的口播剪辑决策包。它读取 `pi-speech` 风格的词级时间戳，识别词间停顿，生成保守的 A-roll 剪辑方案，并可加入 B-roll 规划。
+给 [Pi](https://github.com/earendil-works/pi) 用的口播剪辑决策包。它读取 `pi-speech` 风格的词级时间戳，结合整句上下文识别词间停顿、语气词和相邻重复，生成保守的 A-roll 剪辑方案，并可加入 B-roll 规划。
 
 它不直接调用 FFmpeg。最终输出是 `pi-media@0.3.1` 的通用 timeline EDL，由 `pi-media` 负责素材校验、不可变 revision、渲染和验收。
 
@@ -42,27 +42,86 @@ talking_head_create {
 }
 ```
 
-默认只自动移除至少 500ms 的词间停顿。每个保留片段前留 50ms、后留 80ms，避免切掉辅音、尾音和自然气口。停顿还会分为：
+默认只自动移除至少 500ms、且没有语气词或表达边界保护信号的词间停顿。每个保留片段前留 50ms、后留 80ms，避免切掉辅音、尾音和自然气口。停顿还会分为：
 
 - `safe`：至少 400ms，通常可以切。
 - `review`：150–399ms，必须结合语义和画面判断。
 - `unsafe`：少于 150ms，默认不切。
 
-工具返回 revision 1、停顿摘要和可直接交给 `pi-media.edit_apply` 的 `mediaOperation`。
+若停顿紧邻候选语气词，或位于问号、感叹号等表达边界之后，即使超过阈值也会降级为 `review`，不会进入默认自动剪辑。工具返回 revision 1、内容与停顿摘要，以及可直接交给 `pi-media.edit_apply` 的 `mediaOperation`。
 
-### 2. 分页检查候选气口
+### 2. 分页检查整句和编辑候选
 
 ```js
 talking_head_get {
   projectId: "launch-video",
+  sentenceOffset: 0,
+  sentenceLimit: 20,
   pauseOffset: 0,
-  pauseLimit: 50
+  pauseLimit: 50,
+  fillerOffset: 0,
+  fillerLimit: 50,
+  repetitionOffset: 0,
+  repetitionLimit: 50,
+  includeTranscriptText: true
 }
 ```
 
-只有调用这个工具时才会把候选停顿放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
+工具会分页返回整句上下文、停顿、语气词和相邻重复；需要判断整段结构时可显式取得完整转录文本。`啊`、`额`、`嗯` 等只会成为 `review` 候选，Agent 必须判断它是口癖、语义成分还是刻意表达，不能自动删除。文本标点只能提供低置信度且可以并存的表达线索，不等同于声学情绪识别。
 
-### 3. 写入人工确认后的时间线
+只有调用这个工具时才会把这些证据放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
+
+### 3. 文件名优先筛选 B-roll
+
+先为已经稳定的 A-roll 片段建立一个结构化需求，再扫描指定素材目录：
+
+```js
+talking_head_broll_match {
+  projectId: "launch-video",
+  assetDirectory: "assets/broll",
+  recursive: true,
+  maxFiles: 1000,
+  maxEntries: 20000,
+  maxDepth: 12,
+  maxCandidates: 5,
+  candidateOffset: 0,
+  need: {
+    id: "mouse-demo",
+    outputStartMs: 5200,
+    outputEndMs: 8200,
+    speechText: "电脑除了键盘，还需要鼠标",
+    purpose: "demonstrate",
+    searchTerms: ["鼠标", "操作"],
+    reason: "展示口播提到的具体对象和动作"
+  }
+}
+```
+
+该工具只读取目录项和文件名，不解码、不探测、不哈希视频。它最多返回限定数量的候选，并给出三种结果：
+
+- `filename-direct`：一个文件名唯一且明确命中，只检查这一条素材。
+- `filename-shortlist`：多个名字可能匹配，只检查返回的 shortlist。
+- `visual-fallback`：文件名没有有效语义，再对限定 shortlist 使用低成本联络表。
+
+扫描同时受 `maxFiles`、`maxEntries` 和 `maxDepth` 约束并支持取消。完整扫描时，若当前 shortlist 都不合格，可使用非空的 `nextCandidateOffset` 读取下一批。结果一旦截断，工具不会声称唯一命中，也不会返回可复用的分页游标；此时应缩小素材目录后重扫，避免文件系统枚举顺序造成候选漂移。
+
+确定素材后才调用 `media_probe` 和 `media_contact_sheet`。长素材先低密度定位大致范围，再只对候选范围高密度抽帧；必须使用 `contact_sheet_manifest.json` 的真实时间戳，不能从 PNG 猜时间。找到连续可用且覆盖完整成片窗口的片段后，验证并生成 placement：
+
+```js
+talking_head_broll_select {
+  projectId: "launch-video",
+  need: { /* 与 match 时相同 */ },
+  assetPath: "assets/broll/mouse-demo.mp4",
+  manifestPath: "analysis/mouse-demo/contact_sheet_manifest.json",
+  selectedStartMs: 12400,
+  evidenceTimestampsMs: [12400, 13900, 15400],
+  fit: "cover"
+}
+```
+
+该工具会验证素材 SHA-256、manifest 分析范围、起始帧和覆盖片段尾部的证据时间戳，返回可直接交给 `talking_head_apply` 的完整 placement。placement 内含选择凭证；不要手写或删除其中字段。
+
+### 4. 写入人工确认后的时间线
 
 ```js
 talking_head_apply {
@@ -72,23 +131,13 @@ talking_head_apply {
     { id: "hook", sourceStartMs: 50, sourceEndMs: 4120 },
     { id: "answer", sourceStartMs: 4860, sourceEndMs: 13200 }
   ],
-  broll: [{
-    id: "product-demo",
-    assetPath: "assets/product-demo.mp4",
-    outputStartMs: 5200,
-    outputEndMs: 7900,
-    assetStartMs: 0,
-    fit: "cover",
-    audio: "keep-primary",
-    query: "产品界面操作特写",
-    reason: "具体展示口播中提到的三步操作"
-  }]
+  broll: [selection.placement]
 }
 ```
 
-B-roll 使用成片时间轴定位，永远保留主口播音轨。工具会固定素材字节数和 SHA-256，素材被替换后拒绝导出 EDL。
+B-roll 使用成片时间轴定位，`assetStartMs` 来自联络表 manifest，并永远保留主口播音轨。`talking_head_apply` 会重新校验选择凭证、素材与 manifest 的 SHA-256；时间点被手改或素材被替换都会拒绝写入新修订。
 
-### 4. 交给 pi-media 渲染
+### 5. 交给 pi-media 渲染
 
 先用同一个源文件创建 `pi-media` 项目，再把上一步的 `mediaOperation` 原样传入：
 
@@ -114,10 +163,12 @@ review { path: "out/launch-final.mp4" }
 
 | 工具 | 作用 |
 | --- | --- |
-| `talking_head_create` | 从视频和词级转录建立 revision 1，分析停顿并生成默认 EDL |
-| `talking_head_get` | 读取指定 revision，分页返回停顿候选，可选导出 pi-media EDL |
+| `talking_head_create` | 从视频和词级转录建立 revision 1，分析句子、语气词、重复和停顿并生成默认 EDL |
+| `talking_head_get` | 读取指定 revision，分页返回整句与编辑候选，可选导出 pi-media EDL |
+| `talking_head_broll_match` | 只用文件名和目录名匹配本地 B-roll，返回受限 shortlist 与视觉升级建议 |
+| `talking_head_broll_select` | 用 pi-media 联络表 manifest 验证具体源时间段并生成 placement |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |
 
 ## 当前边界
 
-0.1.0 不负责语音转录、素材搜索、字幕、画面理解或渲染。它只提供稳定的口播时间线决策层。B-roll 的搜索与视觉匹配可以后续新增为独立 Skill 或 Extension，最终仍写入同一份 `broll` 数据并由 `pi-media` 渲染。
+当前版本不负责语音转录、声学情绪识别、联网素材搜索、字幕、画面理解或渲染。它提供整句文本、时间轴和本地素材名称层面的编辑证据；需要依赖真实语气、呼吸、表演意图或画面内容的决定，必须由 Agent 结合原音频、联络表和画面复核。最终 B-roll 仍写入同一份 `broll` 数据并由 `pi-media` 渲染。

package/extensions/talking-head/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { matchWorkspaceBrollAssets, selectBrollWindow } from "../../src/broll.ts";
 import { toMediaTimelineOperation } from "../../src/edl.ts";
 import {
 	applyTimeline,
@@ -33,11 +34,36 @@ const brollPlacement = Type.Object({
 	assetPath: Type.String({ description: "Workspace-relative B-roll video path." }),
 	outputStartMs: Type.Number({ minimum: 0 }),
 	outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
-	assetStartMs: Type.Optional(Type.Number({ minimum: 0 })),
+	assetStartMs: Type.Number({ minimum: 0, description: "Required manifest-backed source timestamp selected from the B-roll asset." }),
 	fit: Type.Union([Type.Literal("cover"), Type.Literal("contain")]),
 	audio: Type.Literal("keep-primary", { description: "B-roll never replaces the talking-head audio." }),
 	query: Type.Optional(Type.String({ maxLength: 500 })),
 	reason: Type.Optional(Type.String({ maxLength: 1_000 })),
+	selectionReceipt: Type.Object({
+		assetBytes: Type.Integer({ minimum: 0 }),
+		assetSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+		manifestPath: Type.String({ minLength: 1 }),
+		manifestSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+		selectedEndMs: Type.Number({ minimum: 0 }),
+		evidenceTimestampsMs: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }),
+	}, { additionalProperties: false }),
+}, { additionalProperties: false });
+
+const brollNeed = Type.Object({
+	id: stableId,
+	outputStartMs: Type.Number({ minimum: 0 }),
+	outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
+	speechText: Type.String({ minLength: 1, maxLength: 2_000 }),
+	purpose: Type.Union([
+		Type.Literal("demonstrate"),
+		Type.Literal("explain"),
+		Type.Literal("evidence"),
+		Type.Literal("establish"),
+		Type.Literal("transition"),
+		Type.Literal("mask-cut"),
+	]),
+	searchTerms: Type.Array(Type.String({ minLength: 1, maxLength: 100 }), { minItems: 1, maxItems: 20 }),
+	reason: Type.String({ minLength: 1, maxLength: 1_000 }),
 }, { additionalProperties: false });
 
 export default function talkingHead(pi: ExtensionAPI): void {
@@ -53,7 +79,7 @@ export default function talkingHead(pi: ExtensionAPI): void {
 			headPaddingMs: Type.Optional(Type.Number({ minimum: 30, maximum: 200 })),
 			tailPaddingMs: Type.Optional(Type.Number({ minimum: 30, maximum: 200 })),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const policy = {
 				...(params.cutThresholdMs === undefined ? {} : { cutThresholdMs: params.cutThresholdMs }),
 				...(params.headPaddingMs === undefined ? {} : { headPaddingMs: params.headPaddingMs }),
@@ -75,29 +101,64 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_get",
 		label: "Inspect talking-head edit",
-		description: "Read one immutable talking-head revision and a bounded page of pause candidates. Optionally include the generic pi-media timeline operation for that revision.",
+		description: "Read one immutable talking-head revision plus bounded sentence, pause, filler-word, and repetition evidence for Agent editorial judgment. Optionally include the generic pi-media timeline operation.",
 		parameters: Type.Object({
 			projectId: stableId,
 			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			sentenceOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			sentenceLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 			pauseOffset: Type.Optional(Type.Integer({ minimum: 0 })),
 			pauseLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			fillerOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			fillerLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			repetitionOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			repetitionLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			includeTranscriptText: Type.Optional(Type.Boolean({ description: "Include the complete transcript text for passage-level Agent review." })),
 			includeMediaOperation: Type.Optional(Type.Boolean()),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const { project, snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
 			const analysis = await getAnalysis(ctx.cwd, project);
-			const offset = params.pauseOffset ?? 0;
-			const limit = params.pauseLimit ?? 50;
+			const sentenceOffset = params.sentenceOffset ?? 0;
+			const sentenceLimit = params.sentenceLimit ?? 20;
+			const pauseOffset = params.pauseOffset ?? 0;
+			const pauseLimit = params.pauseLimit ?? 50;
+			const fillerOffset = params.fillerOffset ?? 0;
+			const fillerLimit = params.fillerLimit ?? 50;
+			const repetitionOffset = params.repetitionOffset ?? 0;
+			const repetitionLimit = params.repetitionLimit ?? 50;
+			const sentences = analysis.sentences ?? [];
+			const fillers = analysis.fillers ?? [];
+			const repetitions = analysis.repetitions ?? [];
 			const details: Record<string, unknown> = {
 				project,
 				snapshot,
+				sentences: {
+					offset: sentenceOffset,
+					limit: sentenceLimit,
+					total: sentences.length,
+					items: sentences.slice(sentenceOffset, sentenceOffset + sentenceLimit),
+				},
 				pauses: {
-					offset,
-					limit,
+					offset: pauseOffset,
+					limit: pauseLimit,
 					total: analysis.candidates.length,
-					items: analysis.candidates.slice(offset, offset + limit),
+					items: analysis.candidates.slice(pauseOffset, pauseOffset + pauseLimit),
+				},
+				fillers: {
+					offset: fillerOffset,
+					limit: fillerLimit,
+					total: fillers.length,
+					items: fillers.slice(fillerOffset, fillerOffset + fillerLimit),
+				},
+				repetitions: {
+					offset: repetitionOffset,
+					limit: repetitionLimit,
+					total: repetitions.length,
+					items: repetitions.slice(repetitionOffset, repetitionOffset + repetitionLimit),
 				},
 			};
+			if (params.includeTranscriptText) details.transcriptText = analysis.text;
 			if (params.includeMediaOperation) {
 				await assertProjectSourcesUnchanged(ctx.cwd, project);
 				await assertSnapshotAssetsUnchanged(ctx.cwd, snapshot);
@@ -107,6 +168,77 @@ export default function talkingHead(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "talking_head_broll_match",
+		label: "Match local B-roll assets",
+		description: "Filename-first B-roll matching for one approved output window. Scans only directory metadata, returns a bounded shortlist, and tells the Agent whether to inspect one selected asset, inspect an ambiguous shortlist, or fall back to low-cost visual screening. It never decodes, probes, or hashes video contents.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			assetDirectory: Type.String({ minLength: 1, description: "Workspace-relative directory containing candidate B-roll videos." }),
+			recursive: Type.Optional(Type.Boolean()),
+			maxFiles: Type.Optional(Type.Integer({ minimum: 1, maximum: 5_000 })),
+			maxEntries: Type.Optional(Type.Integer({ minimum: 1, maximum: 100_000 })),
+			maxDepth: Type.Optional(Type.Integer({ minimum: 0, maximum: 50 })),
+			maxCandidates: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+			candidateOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			need: brollNeed,
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			if (params.need.outputEndMs > snapshot.outputDurationMs) {
+				throw new Error(`B-roll need ${params.need.id} exceeds output duration ${snapshot.outputDurationMs}ms`);
+			}
+			const match = await matchWorkspaceBrollAssets(ctx.cwd, {
+				assetDirectory: params.assetDirectory,
+				...(params.recursive === undefined ? {} : { recursive: params.recursive }),
+				...(params.maxFiles === undefined ? {} : { maxFiles: params.maxFiles }),
+				...(params.maxEntries === undefined ? {} : { maxEntries: params.maxEntries }),
+				...(params.maxDepth === undefined ? {} : { maxDepth: params.maxDepth }),
+				...(params.maxCandidates === undefined ? {} : { maxCandidates: params.maxCandidates }),
+				...(params.candidateOffset === undefined ? {} : { candidateOffset: params.candidateOffset }),
+				need: params.need,
+				...(signal === undefined ? {} : { signal }),
+			});
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				match,
+				...(match.truncated ? { warning: `The bounded scan stopped after ${match.scannedEntryCount} entries and ${match.scannedFileCount} video filenames; filename-direct is disabled until the asset directory is narrowed or fully scanned.` } : {}),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "talking_head_broll_select",
+		label: "Select B-roll source window",
+		description: "Validate one exact B-roll source window against a pi-media contact_sheet_manifest.json. Verifies the selected asset hash, analyzed range, and manifest-backed evidence timestamps, then returns a placement ready for talking_head_apply.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			need: brollNeed,
+			assetPath: Type.String({ minLength: 1 }),
+			manifestPath: Type.String({ minLength: 1 }),
+			selectedStartMs: Type.Number({ minimum: 0 }),
+			evidenceTimestampsMs: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }),
+			fit: Type.Union([Type.Literal("cover"), Type.Literal("contain")]),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			if (params.need.outputEndMs > snapshot.outputDurationMs) {
+				throw new Error(`B-roll need ${params.need.id} exceeds output duration ${snapshot.outputDurationMs}ms`);
+			}
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				selection: await selectBrollWindow(ctx.cwd, {
+					...params,
+					...(signal === undefined ? {} : { signal }),
+				}),
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "talking_head_apply",
 		label: "Apply talking-head timeline",
@@ -117,9 +249,9 @@ export default function talkingHead(pi: ExtensionAPI): void {
 			aroll: Type.Array(arrollSegment, { minItems: 1, maxItems: 1_000 }),
 			broll: Type.Array(brollPlacement, { maxItems: 500 }),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const current = await getTalkingHeadProject(ctx.cwd, params.projectId);
-			const snapshot = await applyTimeline(ctx.cwd, params);
+			const snapshot = await applyTimeline(ctx.cwd, params, signal);
 			return result({
 				projectId: params.projectId,
 				snapshot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-talking-head",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Pause-aware talking-head editing and B-roll planning for Pi, exported as generic pi-media EDLs",
   "type": "module",
   "license": "MIT",

package/prompts/edit-talking-head.md

@@ -2,6 +2,6 @@
 description: Tighten a talking-head video without destroying natural speech rhythm
 ---
 
-Use the `talking-head-edit` skill to analyze word-level pauses, propose a conservative cut strategy, optionally place justified B-roll, and export a generic pi-media EDL for this request: $@
+Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; stabilize A-roll, match B-roll by filename before escalating through paged contact-sheet batches, validate the selected manifest-backed source window, and export a generic pi-media EDL for this request: $@
 
 Show the proposed rhythm before writing a new revision. Never overwrite the source or an existing render.

package/skills/talking-head-edit/SKILL.md

@@ -9,10 +9,19 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
 
 1. Obtain a `pi-speech`-compatible transcript JSON containing word-level `beginMs` and `endMs`. Do not infer frame-accurate cuts from sentence text alone.
 2. Call `talking_head_create` with the source video and transcript. Keep the default 500ms cut threshold, 50ms head padding, and 80ms tail padding unless the user requests a different rhythm.
-3. Inspect pause candidates with bounded `talking_head_get` pages. Treat `safe` as a candidate, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
-4. Before changing the revision, summarize the proposed rhythm: what will be removed, which short pauses will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
-5. Call `talking_head_apply` using exact word-boundary A-roll ranges. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
-6. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
+3. Inspect bounded `talking_head_get` pages. Review the full sentence context, filler candidates, and repetition candidates together with pauses. Treat `safe` and every recommendation as evidence, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
+4. Never delete a filler token automatically. Decide whether `啊`, `额`, `嗯`, or a repeated token is a false start, a discourse marker, or intentional emphasis from its sentence context. A text-only delivery cue is low-confidence evidence; review audio and picture before relying on emotion or performance intent.
+5. Before changing the revision, summarize the proposed rhythm: what words and gaps will be removed, which pauses or fillers will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
+6. Stabilize A-roll before B-roll. For every B-roll window, record the output range, complete spoken text, one purpose (`demonstrate`, `explain`, `evidence`, `establish`, `transition`, or `mask-cut`), 1-20 concise search terms, and a concrete reason.
+7. Call `talking_head_broll_match` before generating contact sheets. Follow its bounded result:
+   - `filename-direct`: probe and visually inspect only the selected asset to choose its source window. Do not call `media_contact_sheet` for unselected assets.
+   - `filename-shortlist`: inspect only the returned shortlist and stop as soon as one asset satisfies the need. If none does and `nextCandidateOffset` is non-null, request that next page; do not repeat the first batch.
+   - `visual-fallback`: use low-cost contact sheets on the bounded shortlist because filenames supplied no useful evidence. Exhaust that batch before requesting a non-null `nextCandidateOffset`.
+   - If the scan is truncated, do not paginate it: narrow the asset directory and rescan so the candidate inventory is stable.
+8. After selecting one asset, call `media_probe`, then use `media_contact_sheet` only as densely as timing requires: one high-density pass for a short ambiguous clip, medium for a normal clip, or low over a long clip followed by high density over the narrowed range. Read `contact_sheet_manifest.json` timestamps instead of guessing times from the PNG. Verify a continuous source window at least as long as the output window, preferably with 500ms handles on both sides.
+9. Call `talking_head_broll_select` with the selected asset, manifest path, exact source start, and the manifest timestamps actually reviewed. Use its complete returned `placement`, including `selectionReceipt`; do not hand-author or omit selection fields.
+10. Call `talking_head_apply` using exact word-boundary A-roll ranges and the validated B-roll placement. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
+11. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
 
 Never overwrite source media or outputs. If a revision conflict occurs, re-read both projects and reconcile intent. If the source, transcript, or B-roll hash changed, stop and ask whether to create a new project rather than silently adopting new bytes.
 

package/skills/talking-head-edit/references/cut-craft.md

@@ -8,10 +8,21 @@
 - Prefer one clean removal over many micro-cuts. Dense sub-150ms cuts create robotic cadence and visible jump cuts.
 - `pi-media` adds a 30ms audio fade at every primary-segment edge to suppress clicks. This does not repair a semantically bad cut.
 
+## Editing spoken content
+
+- Read the complete sentence before removing a filler or repeated word. `啊`, `嗯`, `那个`, and `就是` can carry hesitation, emphasis, transition, or actual meaning.
+- Treat transcript punctuation as a low-confidence delivery hint, not acoustic emotion detection. Confirm expressive decisions against the source audio and picture.
+- Prefer removing a complete false start at word boundaries over deleting an isolated sound that leaves an unnatural join.
+- If a necessary content cut creates a hard join, preserve room tone and use a short transition or justified B-roll rather than compressing every gap.
+
 ## Using B-roll
 
 - Place B-roll on the output timeline after A-roll cuts have stabilized.
 - Use it to show the object, action, place, comparison, or evidence currently being discussed—not as random decoration.
+- Treat a filename match as asset-level evidence, never as proof that a particular source window is usable. Inspect continuous motion before selecting `assetStartMs`.
+- Start with filename and directory metadata. Generate contact sheets only for the selected asset, a bounded ambiguous shortlist, or a bounded fallback batch whose names carry no meaning.
+- For a long selected asset, locate a broad range cheaply and then generate a denser contact sheet only for that range. Use manifest timestamps, not visual timestamp transcription.
+- Ensure the selected source window covers the complete spoken beat. Prefer extra source handles so a later timing adjustment does not require rescanning.
 - Cover visible jump cuts when appropriate, but do not hide continuity errors that change meaning.
 - Keep the primary voice track. B-roll audio replacement is outside the current contract.
 - Record the search query and editorial reason so a later agent can replace the asset without guessing intent.