@speclip/pi-talking-head 0.1.2 → 0.1.3

package/README.md

@@ -71,7 +71,57 @@ talking_head_get {
 
 只有调用这个工具时才会把这些证据放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
 
-### 3. 写入人工确认后的时间线
+### 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 {
@@ -81,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` 原样传入：
 
@@ -125,8 +165,10 @@ review { path: "out/launch-final.mp4" }
 | --- | --- |
 | `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 |
 
 ## 当前边界
 
-当前版本不负责语音转录、声学情绪识别、素材搜索、字幕、画面理解或渲染。它提供整句文本与时间轴层面的编辑证据；需要依赖真实语气、呼吸或表演意图的决定，必须由 Agent 结合原音频和画面复核。B-roll 的搜索与视觉匹配最终仍写入同一份 `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 }),
@@ -142,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",
@@ -152,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.2",
+  "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 review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; 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

@@ -12,8 +12,16 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
 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. 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`.
-7. 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`.
+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

@@ -19,6 +19,10 @@
 
 - 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.

package/src/broll.ts

@@ -0,0 +1,406 @@
+import { opendir, readFile, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
+import type {
+	BrollAssetCandidate,
+	BrollAssetMatch,
+	BrollNeed,
+	BrollPlacementInput,
+	BrollSelectionReceipt,
+	BrollWindowSelection,
+	FileRef,
+} from "./contracts.ts";
+import { resolveExistingWorkspaceDirectory, resolveExistingWorkspaceFile, snapshotFile, workspaceRoot } from "./workspace.ts";
+
+const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi"]);
+
+export interface RankBrollAssetsInput {
+	need: BrollNeed;
+	assetPaths: string[];
+	maxCandidates?: number;
+	candidateOffset?: number;
+	completeInventory?: boolean;
+}
+
+export interface MatchWorkspaceBrollAssetsInput {
+	assetDirectory: string;
+	recursive?: boolean;
+	maxFiles?: number;
+	maxEntries?: number;
+	maxDepth?: number;
+	maxCandidates?: number;
+	candidateOffset?: number;
+	need: BrollNeed;
+	signal?: AbortSignal;
+}
+
+export type WorkspaceBrollAssetMatch = BrollAssetMatch & {
+	assetDirectory: string;
+	scannedFileCount: number;
+	scannedEntryCount: number;
+	truncated: boolean;
+};
+
+export interface SelectBrollWindowInput {
+	need: BrollNeed;
+	assetPath: string;
+	manifestPath: string;
+	selectedStartMs: number;
+	evidenceTimestampsMs: number[];
+	fit: "cover" | "contain";
+	signal?: AbortSignal;
+}
+
+interface ContactSheetManifest {
+	schemaVersion: number;
+	source?: { path?: string; bytes?: number; sha256?: string };
+	range?: { startSeconds?: number; endSeconds?: number };
+	artifacts?: Array<{ timestampsSeconds?: number[]; sourceSha256?: string }>;
+}
+
+function normalized(value: string): string {
+	return value.normalize("NFKC").toLowerCase().replace(/[\p{P}\p{S}\s]+/gu, "");
+}
+
+function normalizedTerms(terms: string[]): string[] {
+	const unique = new Set<string>();
+	for (const term of terms) {
+		const value = normalized(term);
+		if (value) unique.add(value);
+	}
+	if (unique.size === 0) throw new Error("B-roll searchTerms must contain at least one meaningful term");
+	return [...unique];
+}
+
+function candidateFor(assetPath: string, terms: string[]): BrollAssetCandidate {
+	const fileName = basename(assetPath);
+	const normalizedName = normalized(fileName.replace(/\.[^.]+$/u, ""));
+	const normalizedDirectory = normalized(dirname(assetPath));
+	const matchedTerms: string[] = [];
+	let score = 0;
+	for (const term of terms) {
+		if (normalizedName.includes(term)) {
+			matchedTerms.push(term);
+			score += 4;
+		} else if (normalizedDirectory.includes(term)) {
+			matchedTerms.push(term);
+			score += 2;
+		}
+	}
+	const highThreshold = Math.min(2, terms.length);
+	return {
+		assetPath,
+		fileName,
+		matchedTerms,
+		score,
+		confidence: matchedTerms.length >= highThreshold ? "high" : matchedTerms.length > 0 ? "medium" : "low",
+	};
+}
+
+function validateNeed(need: BrollNeed): void {
+	if (!Number.isFinite(need.outputStartMs) || !Number.isFinite(need.outputEndMs)
+		|| need.outputStartMs < 0 || need.outputEndMs <= need.outputStartMs) {
+		throw new Error("B-roll need must contain a valid output range");
+	}
+}
+
+export function rankBrollAssets(input: RankBrollAssetsInput): BrollAssetMatch {
+	validateNeed(input.need);
+	if (input.assetPaths.length === 0) throw new Error("No candidate B-roll video assets were found");
+	const terms = normalizedTerms(input.need.searchTerms);
+	const maxCandidates = input.maxCandidates ?? 5;
+	if (!Number.isInteger(maxCandidates) || maxCandidates < 1 || maxCandidates > 20) {
+		throw new Error("maxCandidates must be within 1-20");
+	}
+	const ranked = [...new Set(input.assetPaths)].map((assetPath) => candidateFor(assetPath, terms)).sort((left, right) => (
+		right.score - left.score || (left.assetPath < right.assetPath ? -1 : left.assetPath > right.assetPath ? 1 : 0)
+	));
+	const candidateOffset = input.candidateOffset ?? 0;
+	if (!Number.isInteger(candidateOffset) || candidateOffset < 0 || candidateOffset >= ranked.length) {
+		throw new Error(`candidateOffset must be within 0-${ranked.length - 1}`);
+	}
+	const top = ranked[0];
+	const second = ranked[1];
+	const direct = (input.completeInventory ?? true) && candidateOffset === 0
+		&& top?.confidence === "high" && (second === undefined || top.score > second.score);
+	if (direct) {
+		return {
+			requiredDurationMs: input.need.outputEndMs - input.need.outputStartMs,
+			totalCandidates: ranked.length,
+			candidateOffset: 0,
+			nextCandidateOffset: null,
+			selectionMode: "filename-direct",
+			shortlist: [top],
+			nextStep: {
+				action: "inspect-selected-asset",
+				reason: "One filename is the unique high-confidence match; inspect only this asset to choose the source window.",
+			},
+		};
+	}
+	const hasLexicalMatch = ranked.some((candidate) => candidate.confidence !== "low");
+	const shortlist = ranked.slice(candidateOffset, candidateOffset + maxCandidates);
+	const nextCandidateOffset = (input.completeInventory ?? true) && candidateOffset + shortlist.length < ranked.length
+		? candidateOffset + shortlist.length
+		: null;
+	const shared = {
+		requiredDurationMs: input.need.outputEndMs - input.need.outputStartMs,
+		totalCandidates: ranked.length,
+		candidateOffset,
+		nextCandidateOffset,
+		shortlist,
+	};
+	if (hasLexicalMatch) return {
+		...shared,
+		selectionMode: "filename-shortlist",
+		nextStep: {
+			action: "inspect-shortlist",
+			reason: "Filename evidence is ambiguous; visually inspect only the bounded shortlist.",
+		},
+	};
+	return {
+		...shared,
+		selectionMode: "visual-fallback",
+		nextStep: {
+			action: "visual-fallback",
+			reason: "Filenames provide no useful evidence; use low-cost visual screening on the bounded shortlist.",
+		},
+	};
+}
+
+interface ScanState {
+	paths: string[];
+	visitedEntries: number;
+	truncated: boolean;
+}
+
+interface ScanLimits {
+	recursive: boolean;
+	maxFiles: number;
+	maxEntries: number;
+	maxDepth: number;
+	signal?: AbortSignal;
+}
+
+function codePointCompare(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+async function collectVideoPaths(directory: string, depth: number, limits: ScanLimits, state: ScanState): Promise<void> {
+	limits.signal?.throwIfAborted();
+	const entries = [];
+	const handle = await opendir(directory);
+	for await (const entry of handle) {
+		limits.signal?.throwIfAborted();
+		if (state.visitedEntries >= limits.maxEntries) {
+			state.truncated = true;
+			break;
+		}
+		state.visitedEntries += 1;
+		entries.push(entry);
+	}
+	entries.sort((left, right) => codePointCompare(left.name, right.name));
+	for (const entry of entries) {
+		limits.signal?.throwIfAborted();
+		if (state.paths.length > limits.maxFiles) {
+			state.truncated = true;
+			return;
+		}
+		if (entry.isSymbolicLink()) continue;
+		const absolute = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (limits.recursive) {
+				if (depth >= limits.maxDepth) state.truncated = true;
+				else await collectVideoPaths(absolute, depth + 1, limits, state);
+			}
+			continue;
+		}
+		if (entry.isFile() && VIDEO_EXTENSIONS.has(extname(entry.name).toLowerCase())) state.paths.push(absolute);
+	}
+}
+
+export async function matchWorkspaceBrollAssets(
+	cwd: string,
+	input: MatchWorkspaceBrollAssetsInput,
+): Promise<WorkspaceBrollAssetMatch> {
+	const maxFiles = input.maxFiles ?? 1_000;
+	if (!Number.isInteger(maxFiles) || maxFiles < 1 || maxFiles > 5_000) {
+		throw new Error("maxFiles must be within 1-5000");
+	}
+	const maxEntries = input.maxEntries ?? 20_000;
+	if (!Number.isInteger(maxEntries) || maxEntries < 1 || maxEntries > 100_000) {
+		throw new Error("maxEntries must be within 1-100000");
+	}
+	const maxDepth = input.maxDepth ?? 12;
+	if (!Number.isInteger(maxDepth) || maxDepth < 0 || maxDepth > 50) {
+		throw new Error("maxDepth must be within 0-50");
+	}
+	const directory = await resolveExistingWorkspaceDirectory(cwd, input.assetDirectory);
+	const state: ScanState = { paths: [], visitedEntries: 0, truncated: false };
+	await collectVideoPaths(directory, 0, {
+		recursive: input.recursive ?? true,
+		maxFiles,
+		maxEntries,
+		maxDepth,
+		...(input.signal === undefined ? {} : { signal: input.signal }),
+	}, state);
+	const truncated = state.truncated || state.paths.length > maxFiles;
+	if (truncated && (input.candidateOffset ?? 0) !== 0) {
+		throw new Error("candidateOffset cannot be reused after a truncated scan; narrow the asset directory and rescan");
+	}
+	const included = state.paths.slice(0, maxFiles);
+	const root = await workspaceRoot(cwd);
+	const toWorkspacePath = (path: string) => relative(root, path).split(sep).join("/");
+	const assetPaths = included.map(toWorkspacePath);
+	return {
+		assetDirectory: toWorkspacePath(directory),
+		scannedFileCount: included.length,
+		scannedEntryCount: state.visitedEntries,
+		truncated,
+		...rankBrollAssets({
+			need: input.need,
+			assetPaths,
+			...(input.maxCandidates === undefined ? {} : { maxCandidates: input.maxCandidates }),
+			...(input.candidateOffset === undefined ? {} : { candidateOffset: input.candidateOffset }),
+			completeInventory: !truncated,
+		}),
+	};
+}
+
+function parseContactSheetManifest(payload: string, manifestPath: string): ContactSheetManifest {
+	try {
+		return JSON.parse(payload) as ContactSheetManifest;
+	} catch (error) {
+		throw new Error(`Invalid contact-sheet manifest ${manifestPath}: ${(error as Error).message}`);
+	}
+}
+
+interface SelectionWindow {
+	assetStartMs: number;
+	outputStartMs: number;
+	outputEndMs: number;
+}
+
+function validateManifestSelection(
+	asset: FileRef,
+	manifest: FileRef,
+	payload: ContactSheetManifest,
+	window: SelectionWindow,
+	receipt: BrollSelectionReceipt,
+): void {
+	if (payload.schemaVersion !== 2 || !payload.source || !payload.range || !Array.isArray(payload.artifacts)) {
+		throw new Error("Contact-sheet manifest must use pi-media schemaVersion 2");
+	}
+	if (receipt.assetSha256 !== asset.sha256 || receipt.assetBytes !== asset.bytes) {
+		throw new Error("B-roll selection receipt does not match the current asset");
+	}
+	if (receipt.manifestPath !== manifest.path || receipt.manifestSha256 !== manifest.sha256) {
+		throw new Error("B-roll selection receipt does not match the current contact-sheet manifest");
+	}
+	if (payload.source.path !== asset.path || payload.source.sha256 !== asset.sha256 || payload.source.bytes !== asset.bytes) {
+		throw new Error("Contact-sheet manifest source does not match the selected B-roll asset");
+	}
+	const requiredDurationMs = window.outputEndMs - window.outputStartMs;
+	const selectedEndMs = window.assetStartMs + requiredDurationMs;
+	if (receipt.selectedEndMs !== selectedEndMs) {
+		throw new Error("B-roll selection receipt duration does not match the output placement");
+	}
+	const rangeStartMs = Number(payload.range.startSeconds) * 1_000;
+	const rangeEndMs = Number(payload.range.endSeconds) * 1_000;
+	if (!Number.isFinite(rangeStartMs) || !Number.isFinite(rangeEndMs)
+		|| window.assetStartMs < rangeStartMs || selectedEndMs > rangeEndMs) {
+		throw new Error("Selected B-roll source window is outside the analyzed contact-sheet range");
+	}
+	const availableTimestamps = new Set<number>();
+	for (const artifact of payload.artifacts) {
+		if (artifact.sourceSha256 !== asset.sha256 || !Array.isArray(artifact.timestampsSeconds)) {
+			throw new Error("Contact-sheet artifact provenance does not match the selected B-roll asset");
+		}
+		for (const timestamp of artifact.timestampsSeconds) {
+			if (Number.isFinite(timestamp)) availableTimestamps.add(Math.round(timestamp * 1_000));
+		}
+	}
+	if (!availableTimestamps.has(window.assetStartMs)) {
+		throw new Error("Selected B-roll source window must start on a manifest timestamp");
+	}
+	const evidenceTimestampsMs = [...new Set(receipt.evidenceTimestampsMs)];
+	const minimumEvidence = requiredDurationMs >= 1_000 ? 2 : 1;
+	if (evidenceTimestampsMs.length < minimumEvidence || !evidenceTimestampsMs.includes(window.assetStartMs)
+		|| evidenceTimestampsMs.some((timestamp) => (
+			!Number.isFinite(timestamp)
+			|| !availableTimestamps.has(timestamp)
+			|| timestamp < window.assetStartMs
+			|| timestamp > selectedEndMs
+		))) {
+		throw new Error(`B-roll selection requires ${minimumEvidence} or more manifest-backed evidence timestamps, including its source start`);
+	}
+	const tailThresholdMs = selectedEndMs - Math.max(500, requiredDurationMs * 0.25);
+	if (Math.max(...evidenceTimestampsMs) < tailThresholdMs) {
+		throw new Error("B-roll selection evidence must cover the end of the source window");
+	}
+}
+
+async function readVerifiedManifest(
+	cwd: string,
+	manifestPath: string,
+	signal?: AbortSignal,
+): Promise<{ manifest: FileRef; payload: ContactSheetManifest }> {
+	signal?.throwIfAborted();
+	const manifestAbsolute = await resolveExistingWorkspaceFile(cwd, manifestPath);
+	if ((await stat(manifestAbsolute)).size > 5 * 1024 * 1024) throw new Error("Contact-sheet manifest exceeds the 5MB limit");
+	const manifest = await snapshotFile(cwd, manifestPath, signal);
+	const payload = parseContactSheetManifest(
+		await readFile(manifestAbsolute, signal === undefined ? "utf8" : { encoding: "utf8", signal }),
+		manifest.path,
+	);
+	return { manifest, payload };
+}
+
+export async function verifyBrollPlacementSelection(
+	cwd: string,
+	placement: BrollPlacementInput,
+	signal?: AbortSignal,
+): Promise<FileRef> {
+	if (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0) {
+		throw new Error(`B-roll assetStartMs is required and must be valid: ${placement.id}`);
+	}
+	if (!placement.selectionReceipt) {
+		throw new Error(`B-roll selectionReceipt is required: ${placement.id}`);
+	}
+	const asset = await snapshotFile(cwd, placement.assetPath, signal);
+	const { manifest, payload } = await readVerifiedManifest(cwd, placement.selectionReceipt.manifestPath, signal);
+	validateManifestSelection(asset, manifest, payload, placement, placement.selectionReceipt);
+	return asset;
+}
+
+export async function selectBrollWindow(cwd: string, input: SelectBrollWindowInput): Promise<BrollWindowSelection> {
+	validateNeed(input.need);
+	input.signal?.throwIfAborted();
+	if (!Number.isFinite(input.selectedStartMs) || input.selectedStartMs < 0) {
+		throw new Error("selectedStartMs must be a finite non-negative timestamp");
+	}
+	const requiredDurationMs = input.need.outputEndMs - input.need.outputStartMs;
+	const selectedEndMs = input.selectedStartMs + requiredDurationMs;
+	const evidenceTimestampsMs = [...new Set(input.evidenceTimestampsMs)];
+	const asset = await snapshotFile(cwd, input.assetPath, input.signal);
+	const { manifest, payload } = await readVerifiedManifest(cwd, input.manifestPath, input.signal);
+	const placement: BrollPlacementInput = {
+			id: input.need.id,
+			assetPath: asset.path,
+			outputStartMs: input.need.outputStartMs,
+			outputEndMs: input.need.outputEndMs,
+			assetStartMs: input.selectedStartMs,
+			fit: input.fit,
+			audio: "keep-primary",
+			query: input.need.searchTerms.join(" "),
+			reason: input.need.reason,
+			selectionReceipt: {
+				assetBytes: asset.bytes,
+				assetSha256: asset.sha256,
+				manifestPath: manifest.path,
+				manifestSha256: manifest.sha256,
+				selectedEndMs,
+				evidenceTimestampsMs,
+			},
+	};
+	validateManifestSelection(asset, manifest, payload, placement, placement.selectionReceipt);
+	return { placement };
+}

package/src/contracts.ts

@@ -95,13 +95,75 @@ export interface BrollPlacement {
 	outputStartMs: number;
 	outputEndMs: number;
 	assetStartMs?: number;
+	selectionReceipt?: BrollSelectionReceipt;
 	fit: "cover" | "contain";
 	audio: "keep-primary";
 	query?: string;
 	reason?: string;
 }
 
-export type BrollPlacementInput = Omit<BrollPlacement, "assetBytes" | "assetSha256">;
+export interface BrollSelectionReceipt {
+	assetBytes: number;
+	assetSha256: string;
+	manifestPath: string;
+	manifestSha256: string;
+	selectedEndMs: number;
+	evidenceTimestampsMs: number[];
+}
+
+export type BrollPlacementInput = Omit<
+	BrollPlacement,
+	"assetBytes" | "assetSha256" | "assetStartMs" | "selectionReceipt"
+> & {
+	assetStartMs: number;
+	selectionReceipt: BrollSelectionReceipt;
+};
+
+export type BrollPurpose = "demonstrate" | "explain" | "evidence" | "establish" | "transition" | "mask-cut";
+
+export interface BrollNeed {
+	id: string;
+	outputStartMs: number;
+	outputEndMs: number;
+	speechText: string;
+	purpose: BrollPurpose;
+	searchTerms: string[];
+	reason: string;
+}
+
+export interface BrollAssetCandidate {
+	assetPath: string;
+	fileName: string;
+	matchedTerms: string[];
+	score: number;
+	confidence: "high" | "medium" | "low";
+}
+
+interface BrollAssetMatchBase {
+	requiredDurationMs: number;
+	totalCandidates: number;
+	candidateOffset: number;
+	nextCandidateOffset: number | null;
+	shortlist: BrollAssetCandidate[];
+}
+
+export type BrollAssetMatch =
+	| BrollAssetMatchBase & {
+		selectionMode: "filename-direct";
+		nextStep: { action: "inspect-selected-asset"; reason: string };
+	}
+	| BrollAssetMatchBase & {
+		selectionMode: "filename-shortlist";
+		nextStep: { action: "inspect-shortlist"; reason: string };
+	}
+	| BrollAssetMatchBase & {
+		selectionMode: "visual-fallback";
+		nextStep: { action: "visual-fallback"; reason: string };
+	};
+
+export interface BrollWindowSelection {
+	placement: BrollPlacementInput;
+}
 
 export interface TranscriptAnalysis {
 	schemaVersion: 2;

package/src/project.ts

@@ -16,6 +16,7 @@ import type {
 	TranscriptWord,
 	WordTranscript,
 } from "./contracts.ts";
+import { verifyBrollPlacementSelection } from "./broll.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
 import { resolveExistingWorkspaceFile, resolveWorkspacePath, snapshotFile, workspaceRelativePath } from "./workspace.ts";
 
@@ -77,6 +78,7 @@ async function validateTimeline(
 	cwd: string,
 	aroll: ArollSegment[],
 	broll: BrollPlacementInput[],
+	signal?: AbortSignal,
 ): Promise<{ outputDurationMs: number; broll: BrollPlacement[] }> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
@@ -91,6 +93,7 @@ async function validateTimeline(
 	uniqueIds(broll, "B-roll placement");
 	const normalizedBroll: BrollPlacement[] = [];
 	for (const placement of broll) {
+		signal?.throwIfAborted();
 		if (!Number.isFinite(placement.outputStartMs) || !Number.isFinite(placement.outputEndMs)
 			|| placement.outputStartMs < 0 || placement.outputEndMs <= placement.outputStartMs) {
 			throw new Error(`Invalid B-roll output range: ${placement.id}`);
@@ -98,11 +101,12 @@ async function validateTimeline(
 		if (placement.outputEndMs > outputDurationMs) {
 			throw new Error(`B-roll placement ${placement.id} exceeds output duration ${outputDurationMs}ms`);
 		}
-		if (placement.assetStartMs !== undefined && (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0)) {
-			throw new Error(`Invalid B-roll asset start: ${placement.id}`);
+		if (!Number.isFinite(placement.assetStartMs) || placement.assetStartMs < 0) {
+			throw new Error(`B-roll assetStartMs is required and must be valid: ${placement.id}`);
 		}
+		if (!placement.selectionReceipt) throw new Error(`B-roll selectionReceipt is required: ${placement.id}`);
 		if (placement.audio !== "keep-primary") throw new Error("B-roll audio must keep the primary A-roll audio");
-		const asset = await snapshotFile(cwd, placement.assetPath);
+		const asset = await verifyBrollPlacementSelection(cwd, placement, signal);
 		normalizedBroll.push({
 			...structuredClone(placement),
 			assetPath: asset.path,
@@ -233,7 +237,7 @@ async function acquireLock(directory: string): Promise<() => Promise<void>> {
 	return async () => { await unlink(lockPath).catch(() => undefined); };
 }
 
-export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Promise<TalkingHeadSnapshot> {
+export async function applyTimeline(cwd: string, input: ApplyTimelineInput, signal?: AbortSignal): Promise<TalkingHeadSnapshot> {
 	const directory = await projectDirectory(cwd, input.projectId);
 	const release = await acquireLock(directory);
 	try {
@@ -244,7 +248,7 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Pro
 		await assertProjectSourcesUnchanged(cwd, project);
 		await assertSnapshotAssetsUnchanged(cwd, current);
 		assertWordSafeSegments(input.aroll, await getAnalysis(cwd, project));
-		const validated = await validateTimeline(cwd, input.aroll, input.broll);
+		const validated = await validateTimeline(cwd, input.aroll, input.broll, signal);
 		const revision = project.currentRevision + 1;
 		const now = new Date().toISOString();
 		const snapshot: TalkingHeadSnapshot = {

package/src/workspace.ts

@@ -39,6 +39,17 @@ export async function resolveExistingWorkspaceFile(cwd: string, inputPath: strin
 	return canonical;
 }
 
+export async function resolveExistingWorkspaceDirectory(cwd: string, inputPath: string): Promise<string> {
+	const root = await workspaceRoot(cwd);
+	const lexical = resolve(root, inputPath);
+	if (!isWithin(root, lexical)) throw new Error(`Path is outside the workspace: ${inputPath}`);
+	if ((await lstat(lexical)).isSymbolicLink()) throw new Error(`Unsafe workspace-directory symlink: ${inputPath}`);
+	const canonical = await realpath(lexical);
+	if (!isWithin(root, canonical)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	if (!(await stat(canonical)).isDirectory()) throw new Error(`Path is not a directory: ${inputPath}`);
+	return canonical;
+}
+
 export async function resolveWorkspacePath(cwd: string, inputPath: string): Promise<string> {
 	const root = await workspaceRoot(cwd);
 	const lexical = resolve(root, inputPath);
@@ -55,17 +66,20 @@ export async function workspaceRelativePath(cwd: string, absolutePath: string):
 	return relative(root, absolutePath).split(sep).join("/");
 }
 
-async function sha256File(path: string): Promise<string> {
+async function sha256File(path: string, signal?: AbortSignal): Promise<string> {
+	signal?.throwIfAborted();
 	const hash = createHash("sha256");
-	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	for await (const chunk of createReadStream(path, signal === undefined ? {} : { signal })) hash.update(chunk);
+	signal?.throwIfAborted();
 	return hash.digest("hex");
 }
 
-export async function snapshotFile(cwd: string, inputPath: string): Promise<FileRef> {
+export async function snapshotFile(cwd: string, inputPath: string, signal?: AbortSignal): Promise<FileRef> {
+	signal?.throwIfAborted();
 	const absolute = await resolveExistingWorkspaceFile(cwd, inputPath);
 	return {
 		path: await workspaceRelativePath(cwd, absolute),
 		bytes: (await stat(absolute)).size,
-		sha256: await sha256File(absolute),
+		sha256: await sha256File(absolute, signal),
 	};
 }