@speclip/pi-talking-head 0.1.4 → 0.1.5

package/README.md

@@ -107,14 +107,15 @@ talking_head_broll_plan {
 }
 ```
 
-规划结果同时返回 `continuityPlanReceipt`，把当前项目 revision、A-roll、规划后的 B-roll 区间和跳点审阅结果绑定在一起。后续 `talking_head_apply` 会重新计算并核对它，不能跳过规划或把已经衔接的区间手动缩短。
+规划结果同时返回 `plan.coverage` 和 `continuityPlanReceipt`。`plan.coverage` 会列出 B-roll/A-roll 时长、B-roll 占比和最长连续 B-roll；凭证则把当前项目 revision、A-roll、规划后的 B-roll 区间和跳点审阅结果绑定在一起。后续 `talking_head_apply` 会重新计算并核对，不能跳过规划或把已经衔接的区间手动缩短。
 
 规划结果处理两类问题：
 
 - **B-roll 闪屏**：两个 B-roll 之间只露出不超过 500ms 的 A-roll 时，`plan.needs` 会把前一个需求延长到后一个需求的起点。后续分别选段后，两段 B-roll 会直接交接，不再闪回 A-roll。
 - **气口剪辑跳转**：A-roll 相邻片段的源时间不连续时，会生成 `jumpCuts`。工具检查建议遮盖区间是否已被 B-roll 连续覆盖；未覆盖项标为 `needs-broll`，Agent 应结合口播语义补充 `purpose: "mask-cut"` 的需求，再重新规划。
+- **A-roll 出镜预算**：B-roll 总覆盖最多占成片 50%，单次连续覆盖最多 8000ms。规划和最终应用都会独立校验；超限时应删除或缩短低价值需求，而不是继续遮盖 A-roll。
 
-规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。是否遮盖仍需结合实际画面判断。
+规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。`needs-broll` 表示“值得检查”，不表示“必须遮盖”；是否添加仍需结合实际画面判断。
 
 ### 4. 文件名优先筛选 B-roll
 
@@ -203,7 +204,7 @@ review { path: "out/launch-final.mp4" }
 | --- | --- |
 | `talking_head_create` | 从视频和词级转录建立 revision 1，分析句子、语气词、重复和停顿并生成默认 EDL |
 | `talking_head_get` | 读取指定 revision，分页返回整句与编辑候选，可选导出 pi-media EDL |
-| `talking_head_broll_plan` | 衔接相邻 B-roll、识别 A-roll 跳点并报告尚未遮盖的剪辑区间 |
+| `talking_head_broll_plan` | 按 A-roll 优先预算规划 B-roll、衔接相邻片段并报告待审阅跳点 |
 | `talking_head_broll_match` | 只用文件名和目录名匹配本地 B-roll，返回受限 shortlist 与视觉升级建议 |
 | `talking_head_broll_select` | 用 pi-media 联络表 manifest 验证具体源时间段并生成 placement |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |

package/extensions/talking-head/index.ts

@@ -200,7 +200,7 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_broll_plan",
 		label: "Plan B-roll visual continuity",
-		description: "Plan B-roll windows before asset matching. Bridges brief A-roll flashes between neighboring B-roll needs and reports A-roll source jump cuts that still need a mask-cut B-roll.",
+		description: "Plan A-roll-first B-roll windows before asset matching. Keeps total B-roll at or below 50% and each continuous run at or below 8 seconds, bridges brief A-roll flashes, and reports source jump cuts for visual review.",
 		parameters: Type.Object({
 			projectId: stableId,
 			revision: Type.Optional(Type.Integer({ minimum: 1 })),
@@ -308,7 +308,7 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_apply",
 		label: "Apply talking-head timeline",
-		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. B-roll requires the matching continuity plan receipt; brief A-roll flashes, unplanned ranges, and overlapping B-roll are rejected. Returns a generic pi-media timeline operation ready for edit_apply.",
+		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. B-roll requires the matching continuity plan receipt; coverage above 50%, continuous runs above 8 seconds, brief A-roll flashes, unplanned ranges, and overlaps are rejected. Returns a generic pi-media timeline operation ready for edit_apply.",
 		parameters: Type.Object({
 			projectId: stableId,
 			expectedRevision: Type.Integer({ minimum: 1 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-talking-head",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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; stabilize A-roll, plan B-roll continuity to bridge brief A-roll flashes and mask objectionable jump cuts, 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: $@
+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, keep A-roll visible for at least half of the output, limit each continuous B-roll run to 8 seconds, bridge brief A-roll flashes, mask only visually objectionable jump cuts, 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,8 @@ 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. 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_plan` with the final proposed A-roll and all semantic B-roll needs before matching assets. Keep its `continuityPlanReceipt` unchanged. Use the returned `plan.needs`: it extends the previous B-roll across A-roll gaps of 500ms or less so neighboring B-roll clips hand off directly. Review every reported A-roll jump cut. Add a `purpose: mask-cut` need over each visually objectionable uncovered cut, using the suggested output range, then rerun the plan. Do not create meaningless B-roll solely because a cut exists; picture review remains the editorial gate.
+6. Stabilize A-roll before B-roll. A-roll is the primary picture, not leftover filler: keep it visible for at least half of the final duration and reintroduce it within every 8 seconds of continuous 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_plan` with the final proposed A-roll and all semantic B-roll needs before matching assets. Keep its `continuityPlanReceipt` unchanged. Use the returned `plan.needs` and inspect `plan.coverage`: the planner rejects total B-roll above 50% or any continuous run above 8000ms. It extends the previous B-roll across A-roll gaps of 500ms or less so neighboring B-roll clips hand off directly. Review every reported A-roll jump cut, but add `purpose: mask-cut` only when picture review shows a visually objectionable cut and the spoken context supports B-roll. Never cover every reported jump cut by default. If the budget is exceeded, remove or shorten lower-value needs instead of hiding more A-roll, then rerun the plan.
 8. 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.
@@ -21,7 +21,7 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
    - If the scan is truncated, do not paginate it: narrow the asset directory and rescan so the candidate inventory is stable.
 9. 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 planned output window, preferably with 500ms handles on both sides.
 10. Call `talking_head_broll_select` with each planned need, selected asset, manifest path, exact source start, and the manifest timestamps actually reviewed. Use its complete returned `placement`, including `selectionReceipt`; do not shorten bridged output ranges or hand-author selection fields.
-11. Call `talking_head_apply` using the same planned A-roll, every validated B-roll placement, and the unchanged `continuityPlanReceipt`. The tool rejects unplanned ranges, B-roll overlaps, and A-roll flashes of 500ms or less. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
+11. Call `talking_head_apply` using the same planned A-roll, every validated B-roll placement, and the unchanged `continuityPlanReceipt`. The tool independently rejects B-roll above the 50%/8000ms A-roll-first budget, unplanned ranges, overlaps, and A-roll flashes of 500ms or less. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
 12. 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/src/continuity.ts

@@ -5,10 +5,14 @@ import type {
 	BrollContinuityBridge,
 	BrollContinuityPlan,
 	BrollContinuityPlanReceipt,
+	BrollCoverageSummary,
 	BrollNeed,
 } from "./contracts.ts";
 import { timelineDuration } from "./transcript.ts";
 
+export const MAX_BROLL_COVERAGE_RATIO = 0.5;
+export const MAX_CONTINUOUS_BROLL_MS = 8_000;
+
 export interface PlanBrollContinuityInput {
 	aroll: ArollSegment[];
 	needs: BrollNeed[];
@@ -105,6 +109,77 @@ export function findOverlappingBrollWindows(windows: BrollOutputWindow[]): Overl
 	return overlaps;
 }
 
+export function summarizeBrollCoverage(
+	windows: BrollOutputWindow[],
+	outputDurationMs: number,
+): BrollCoverageSummary {
+	if (!Number.isFinite(outputDurationMs) || outputDurationMs <= 0) {
+		throw new Error("outputDurationMs must be a positive finite number");
+	}
+	for (const window of windows) {
+		if (!Number.isFinite(window.outputStartMs) || !Number.isFinite(window.outputEndMs)
+			|| window.outputStartMs < 0 || window.outputEndMs <= window.outputStartMs
+			|| window.outputEndMs > outputDurationMs) {
+			throw new Error(`Invalid B-roll coverage window: ${window.id}`);
+		}
+	}
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	let brollDurationMs = 0;
+	let longestContinuousBrollMs = 0;
+	let runStartMs: number | undefined;
+	let runEndMs: number | undefined;
+	for (const window of sorted) {
+		if (runStartMs === undefined || runEndMs === undefined) {
+			runStartMs = window.outputStartMs;
+			runEndMs = window.outputEndMs;
+			continue;
+		}
+		if (window.outputStartMs <= runEndMs) {
+			runEndMs = Math.max(runEndMs, window.outputEndMs);
+			continue;
+		}
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+		runStartMs = window.outputStartMs;
+		runEndMs = window.outputEndMs;
+	}
+	if (runStartMs !== undefined && runEndMs !== undefined) {
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+	}
+	return {
+		brollDurationMs,
+		arollDurationMs: outputDurationMs - brollDurationMs,
+		brollCoverageRatio: Math.round((brollDurationMs / outputDurationMs) * 10_000) / 10_000,
+		longestContinuousBrollMs,
+		limits: {
+			maxBrollCoverageRatio: MAX_BROLL_COVERAGE_RATIO,
+			maxContinuousBrollMs: MAX_CONTINUOUS_BROLL_MS,
+		},
+	};
+}
+
+export function assertBrollCoverageBudget(
+	windows: BrollOutputWindow[],
+	outputDurationMs: number,
+): BrollCoverageSummary {
+	const coverage = summarizeBrollCoverage(windows, outputDurationMs);
+	if (coverage.brollDurationMs > outputDurationMs * MAX_BROLL_COVERAGE_RATIO) {
+		const percent = ((coverage.brollDurationMs / outputDurationMs) * 100).toFixed(1);
+		throw new Error(`B-roll coverage ${percent}% exceeds the 50% A-roll-first limit; remove or shorten lower-priority B-roll needs`);
+	}
+	if (coverage.longestContinuousBrollMs > MAX_CONTINUOUS_BROLL_MS) {
+		throw new Error(`continuous B-roll run ${coverage.longestContinuousBrollMs}ms exceeds the 8000ms limit; split it with a meaningful A-roll appearance`);
+	}
+	return coverage;
+}
+
 function validateSegments(aroll: ArollSegment[]): void {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	const ids = new Set<string>();
@@ -239,6 +314,7 @@ export function planBrollContinuity(input: PlanBrollContinuityInput): BrollConti
 		throw new Error("cutCoverBeforeMs and cutCoverAfterMs cannot both be zero");
 	}
 	const bridged = bridgeShortGaps(input.needs, shortGapMs);
+	const coverage = assertBrollCoverageBudget(bridged.needs, outputDurationMs);
 	return {
 		outputDurationMs,
 		shortGapMs,
@@ -246,6 +322,7 @@ export function planBrollContinuity(input: PlanBrollContinuityInput): BrollConti
 		cutCoverAfterMs,
 		needs: bridged.needs,
 		bridges: bridged.bridges,
+		coverage,
 		jumpCuts: analyzeArollJumpCuts(
 			input.aroll,
 			bridged.needs,

package/src/contracts.ts

@@ -185,6 +185,17 @@ export interface ArollJumpCut {
 	status: "covered" | "needs-broll";
 }
 
+export interface BrollCoverageSummary {
+	brollDurationMs: number;
+	arollDurationMs: number;
+	brollCoverageRatio: number;
+	longestContinuousBrollMs: number;
+	limits: {
+		maxBrollCoverageRatio: number;
+		maxContinuousBrollMs: number;
+	};
+}
+
 export interface BrollContinuityPlan {
 	outputDurationMs: number;
 	shortGapMs: number;
@@ -193,6 +204,7 @@ export interface BrollContinuityPlan {
 	needs: BrollNeed[];
 	bridges: BrollContinuityBridge[];
 	jumpCuts: ArollJumpCut[];
+	coverage: BrollCoverageSummary;
 }
 
 export interface BrollContinuityPlanReceipt {
@@ -254,6 +266,7 @@ export interface TalkingHeadSnapshot {
 	broll: BrollPlacement[];
 	continuityPlanReceipt?: BrollContinuityPlanReceipt;
 	jumpCuts?: ArollJumpCut[];
+	brollCoverage?: BrollCoverageSummary;
 	outputDurationMs: number;
 }
 

package/src/project.ts

@@ -20,6 +20,7 @@ import type {
 import { verifyBrollPlacementSelection } from "./broll.ts";
 import {
 	analyzeArollJumpCuts,
+	assertBrollCoverageBudget,
 	findOverlappingBrollWindows,
 	findShortArollFlashGaps,
 	verifyBrollContinuityPlanReceipt,
@@ -90,7 +91,12 @@ async function validateTimeline(
 	revision: number,
 	continuityPlanReceipt: BrollContinuityPlanReceipt | undefined,
 	signal?: AbortSignal,
-): Promise<{ outputDurationMs: number; broll: BrollPlacement[]; jumpCuts: ReturnType<typeof analyzeArollJumpCuts> }> {
+): Promise<{
+	outputDurationMs: number;
+	broll: BrollPlacement[];
+	brollCoverage: ReturnType<typeof assertBrollCoverageBudget>;
+	jumpCuts: ReturnType<typeof analyzeArollJumpCuts>;
+}> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
 	for (const segment of aroll) {
@@ -124,6 +130,7 @@ async function validateTimeline(
 	if (flashGap) {
 		throw new Error(`B-roll placements ${flashGap.fromBrollId} and ${flashGap.toBrollId} leave a brief ${flashGap.durationMs}ms A-roll flash; run talking_head_broll_plan and reselect the bridged window`);
 	}
+	const brollCoverage = assertBrollCoverageBudget(broll, outputDurationMs);
 	if (broll.length > 0 && !continuityPlanReceipt) {
 		throw new Error("B-roll continuityPlanReceipt is required; run talking_head_broll_plan first");
 	}
@@ -144,6 +151,7 @@ async function validateTimeline(
 	return {
 		outputDurationMs,
 		broll: normalizedBroll,
+		brollCoverage,
 		jumpCuts: continuityPlanReceipt
 			? structuredClone(continuityPlanReceipt.jumpCuts)
 			: analyzeArollJumpCuts(aroll, broll, outputDurationMs, 250, 500),
@@ -214,6 +222,7 @@ export async function createTalkingHeadProject(cwd: string, input: CreateTalking
 		policy,
 		aroll: analysis.segments,
 		broll: [],
+		brollCoverage: assertBrollCoverageBudget([], analysis.outputDurationMs),
 		jumpCuts: analyzeArollJumpCuts(analysis.segments, [], analysis.outputDurationMs, 250, 500),
 		outputDurationMs: analysis.outputDurationMs,
 	};
@@ -302,6 +311,7 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput, sign
 			policy: current.policy,
 			aroll: structuredClone(input.aroll),
 			broll: validated.broll,
+			brollCoverage: validated.brollCoverage,
 			jumpCuts: validated.jumpCuts,
 			...(input.continuityPlanReceipt === undefined
 				? {}