@speclip/pi-talking-head 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Speclip contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @speclip/pi-talking-head
+
+给 [Pi](https://github.com/earendil-works/pi) 用的口播剪辑决策包。它读取 `pi-speech` 风格的词级时间戳，识别词间停顿，生成保守的 A-roll 剪辑方案，并可加入 B-roll 规划。
+
+它不直接调用 FFmpeg。最终输出是 `pi-media@0.3.1` 的通用 timeline EDL，由 `pi-media` 负责素材校验、不可变 revision、渲染和验收。
+
+## 为什么这样拆
+
+- `pi-talking-head`：决定哪里该剪、气口留多少、B-roll 为什么出现。
+- `pi-media`：执行任意来源的通用 EDL，保证路径安全、素材哈希、渲染和凭证。
+- `pi-speech`：提供词级 `beginMs` / `endMs` 转录。
+
+以后增加删赘词、重复 take 选择、语义段落、B-roll 搜索或字幕，只需扩展口播决策层，不需要重写渲染器。
+
+## 环境要求
+
+- Node.js 22.19+
+- Pi 0.84.1–0.84.x
+- `@speclip/pi-media` 0.3.1+（渲染时需要）
+- 一份带词级时间戳的 JSON 转录；格式兼容 `@speclip/pi-speech`
+
+## 安装和验证
+
+```bash
+npm install
+npm run check
+pi install ./
+```
+
+## 工作流
+
+### 1. 创建口播项目
+
+```js
+talking_head_create {
+  projectId: "launch-video",
+  sourcePath: "raw/launch.mp4",
+  transcriptPath: "transcripts/launch.json",
+  cutThresholdMs: 500,
+  headPaddingMs: 50,
+  tailPaddingMs: 80
+}
+```
+
+默认只自动移除至少 500ms 的词间停顿。每个保留片段前留 50ms、后留 80ms，避免切掉辅音、尾音和自然气口。停顿还会分为：
+
+- `safe`：至少 400ms，通常可以切。
+- `review`：150–399ms，必须结合语义和画面判断。
+- `unsafe`：少于 150ms，默认不切。
+
+工具返回 revision 1、停顿摘要和可直接交给 `pi-media.edit_apply` 的 `mediaOperation`。
+
+### 2. 分页检查候选气口
+
+```js
+talking_head_get {
+  projectId: "launch-video",
+  pauseOffset: 0,
+  pauseLimit: 50
+}
+```
+
+只有调用这个工具时才会把候选停顿放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
+
+### 3. 写入人工确认后的时间线
+
+```js
+talking_head_apply {
+  projectId: "launch-video",
+  expectedRevision: 1,
+  arroll: [
+    { 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: "具体展示口播中提到的三步操作"
+  }]
+}
+```
+
+B-roll 使用成片时间轴定位，永远保留主口播音轨。工具会固定素材字节数和 SHA-256，素材被替换后拒绝导出 EDL。
+
+### 4. 交给 pi-media 渲染
+
+先用同一个源文件创建 `pi-media` 项目，再把上一步的 `mediaOperation` 原样传入：
+
+```js
+project_create { projectId: "launch-video-render", sourcePath: "raw/launch.mp4" }
+
+edit_apply {
+  projectId: "launch-video-render",
+  expectedRevision: 1,
+  operations: [mediaOperation]
+}
+
+render {
+  projectId: "launch-video-render",
+  revision: 2,
+  outputPath: "out/launch-final.mp4"
+}
+
+review { path: "out/launch-final.mp4" }
+```
+
+## 工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `talking_head_create` | 从视频和词级转录建立 revision 1，分析停顿并生成默认 EDL |
+| `talking_head_get` | 读取指定 revision，分页返回停顿候选，可选导出 pi-media EDL |
+| `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |
+
+## 当前边界
+
+0.1.0 不负责语音转录、素材搜索、字幕、画面理解或渲染。它只提供稳定的口播时间线决策层。B-roll 的搜索与视觉匹配可以后续新增为独立 Skill 或 Extension，最终仍写入同一份 `broll` 数据并由 `pi-media` 渲染。

package/extensions/talking-head/index.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toMediaTimelineOperation } from "../../src/edl.ts";
+import {
+	applyTimeline,
+	assertProjectSourcesUnchanged,
+	assertSnapshotAssetsUnchanged,
+	createTalkingHeadProject,
+	getAnalysis,
+	getTalkingHeadProject,
+} from "../../src/project.ts";
+
+function result(details: unknown) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
+		details,
+	};
+}
+
+const stableId = Type.String({
+	description: "Stable ID using lowercase letters, numbers, and interior hyphens (1-64 characters).",
+	pattern: "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
+});
+
+const arrollSegment = Type.Object({
+	id: stableId,
+	sourceStartMs: Type.Number({ minimum: 0 }),
+	sourceEndMs: Type.Number({ exclusiveMinimum: 0 }),
+}, { additionalProperties: false });
+
+const brollPlacement = Type.Object({
+	id: stableId,
+	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 })),
+	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 })),
+}, { additionalProperties: false });
+
+export default function talkingHead(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "talking_head_create",
+		label: "Create talking-head edit",
+		description: "Create a workspace-local talking-head project from a source video and pi-speech-compatible word-timestamp transcript. Produces classified pause candidates and a conservative default A-roll EDL; it does not render media.",
+		parameters: Type.Object({
+			projectId: stableId,
+			sourcePath: Type.String({ description: "Workspace-relative source video path." }),
+			transcriptPath: Type.String({ description: "Workspace-relative pi-speech word-timestamp JSON path." }),
+			cutThresholdMs: Type.Optional(Type.Number({ minimum: 150, maximum: 10_000 })),
+			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) {
+			const policy = {
+				...(params.cutThresholdMs === undefined ? {} : { cutThresholdMs: params.cutThresholdMs }),
+				...(params.headPaddingMs === undefined ? {} : { headPaddingMs: params.headPaddingMs }),
+				...(params.tailPaddingMs === undefined ? {} : { tailPaddingMs: params.tailPaddingMs }),
+			};
+			const created = await createTalkingHeadProject(ctx.cwd, {
+				projectId: params.projectId,
+				sourcePath: params.sourcePath,
+				transcriptPath: params.transcriptPath,
+				policy,
+			});
+			return result({
+				...created,
+				mediaOperation: toMediaTimelineOperation(created.project, created.snapshot),
+			});
+		},
+	});
+
+	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.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			pauseOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			pauseLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			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 details: Record<string, unknown> = {
+				project,
+				snapshot,
+				pauses: {
+					offset,
+					limit,
+					total: analysis.candidates.length,
+					items: analysis.candidates.slice(offset, offset + limit),
+				},
+			};
+			if (params.includeMediaOperation) {
+				await assertProjectSourcesUnchanged(ctx.cwd, project);
+				await assertSnapshotAssetsUnchanged(ctx.cwd, snapshot);
+				details.mediaOperation = toMediaTimelineOperation(project, snapshot);
+			}
+			return result(details);
+		},
+	});
+
+	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. Returns a generic pi-media timeline operation ready for edit_apply.",
+		parameters: Type.Object({
+			projectId: stableId,
+			expectedRevision: Type.Integer({ minimum: 1 }),
+			aroll: Type.Array(arrollSegment, { minItems: 1, maxItems: 1_000 }),
+			broll: Type.Array(brollPlacement, { maxItems: 500 }),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const current = await getTalkingHeadProject(ctx.cwd, params.projectId);
+			const snapshot = await applyTimeline(ctx.cwd, params);
+			return result({
+				projectId: params.projectId,
+				snapshot,
+				mediaOperation: toMediaTimelineOperation(current.project, snapshot),
+			});
+		},
+	});
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@speclip/pi-talking-head",
+  "version": "0.1.0",
+  "description": "Pause-aware talking-head editing and B-roll planning for Pi, exported as generic pi-media EDLs",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linyqh/pi-talking-head.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "extensions",
+    "prompts",
+    "skills",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "check": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "pi-package",
+    "talking-head",
+    "video-editing",
+    "edl",
+    "b-roll",
+    "ffmpeg"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/talking-head/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.1 <0.85.0",
+    "typebox": "^1.3.7"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@types/node": "22.20.1",
+    "typebox": "1.3.7",
+    "typescript": "7.0.2"
+  }
+}

package/prompts/edit-talking-head.md

@@ -0,0 +1,7 @@
+---
+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: $@
+
+Show the proposed rhythm before writing a new revision. Never overwrite the source or an existing render.

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

@@ -0,0 +1,19 @@
+---
+name: talking-head-edit
+description: Plan a polished talking-head edit from word timestamps, preserve natural breath and speech boundaries, add justified B-roll placements, and hand a generic EDL to pi-media. Use when the user asks to cut pauses, tighten spoken delivery, remove dead air, edit a monologue, or add B-roll to a talking-head video.
+---
+
+# Talking-head edit
+
+Use `pi-speech` for word evidence, this package for editorial decisions, and `pi-media` for deterministic rendering.
+
+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`.
+
+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.
+
+Read [cut craft](references/cut-craft.md) when deciding whether a pause is natural, abrupt, or suitable for B-roll.

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

@@ -0,0 +1,17 @@
+# Cut craft
+
+## Cutting a breath
+
+- Cut only between word timestamps. Never cut through a word or punctuation tail.
+- Keep 30–200ms on both sides of a spoken range. The default 50ms before and 80ms after is intentionally asymmetric because endings often need more decay.
+- A long waveform gap is evidence of silence, not proof that it should disappear. Keep pauses that signal emphasis, emotion, a paragraph boundary, or a visible gesture.
+- 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.
+
+## 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.
+- 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/contracts.ts

@@ -0,0 +1,103 @@
+export interface TranscriptWord {
+	text: string;
+	beginMs: number;
+	endMs: number;
+	punctuation: string;
+}
+
+export interface TranscriptSentence {
+	id: number;
+	beginMs: number;
+	endMs: number;
+	text: string;
+	words: TranscriptWord[];
+}
+
+export interface WordTranscript {
+	text: string;
+	sentences: TranscriptSentence[];
+}
+
+export type PauseClassification = "unsafe" | "review" | "safe";
+
+export interface PauseCandidate {
+	id: string;
+	startMs: number;
+	endMs: number;
+	durationMs: number;
+	classification: PauseClassification;
+	beforeText: string;
+	afterText: string;
+}
+
+export interface ArollSegment {
+	id: string;
+	sourceStartMs: number;
+	sourceEndMs: number;
+}
+
+export interface BrollPlacement {
+	id: string;
+	assetPath: string;
+	assetBytes: number;
+	assetSha256: string;
+	outputStartMs: number;
+	outputEndMs: number;
+	assetStartMs?: number;
+	fit: "cover" | "contain";
+	audio: "keep-primary";
+	query?: string;
+	reason?: string;
+}
+
+export type BrollPlacementInput = Omit<BrollPlacement, "assetBytes" | "assetSha256">;
+
+export interface TranscriptAnalysis {
+	words: TranscriptWord[];
+	candidates: PauseCandidate[];
+	segments: ArollSegment[];
+	outputDurationMs: number;
+}
+
+export interface TalkingHeadPolicy {
+	cutThresholdMs: number;
+	headPaddingMs: number;
+	tailPaddingMs: number;
+}
+
+export interface FileRef {
+	path: string;
+	bytes: number;
+	sha256: string;
+}
+
+export interface TalkingHeadProject {
+	schemaVersion: 1;
+	projectId: string;
+	currentRevision: number;
+	source: FileRef;
+	transcript: FileRef;
+	analysisPath: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface TalkingHeadSnapshot {
+	schemaVersion: 1;
+	projectId: string;
+	revision: number;
+	parentRevision: number | null;
+	createdAt: string;
+	policy: TalkingHeadPolicy;
+	aroll: ArollSegment[];
+	broll: BrollPlacement[];
+	outputDurationMs: number;
+}
+
+export interface RenderArtifact extends FileRef {
+	projectId: string;
+	revision: number;
+	durationMs: number;
+	receiptPath: string;
+	createdAt: string;
+}

package/src/edl.ts

@@ -0,0 +1,48 @@
+import type { TalkingHeadProject, TalkingHeadSnapshot } from "./contracts.ts";
+
+export interface MediaTimelineOperationInput {
+	kind: "timeline";
+	segments: Array<{
+		id: string;
+		sourcePath: string;
+		sourceStartSeconds: number;
+		sourceEndSeconds: number;
+	}>;
+	overlays: Array<{
+		id: string;
+		sourcePath: string;
+		outputStartSeconds: number;
+		outputEndSeconds: number;
+		sourceStartSeconds?: number;
+		fit: "cover" | "contain";
+		audio: "keep-primary";
+	}>;
+}
+
+function seconds(milliseconds: number): number {
+	return milliseconds / 1_000;
+}
+
+export function toMediaTimelineOperation(
+	project: TalkingHeadProject,
+	snapshot: TalkingHeadSnapshot,
+): MediaTimelineOperationInput {
+	return {
+		kind: "timeline",
+		segments: snapshot.aroll.map((segment) => ({
+			id: segment.id,
+			sourcePath: project.source.path,
+			sourceStartSeconds: seconds(segment.sourceStartMs),
+			sourceEndSeconds: seconds(segment.sourceEndMs),
+		})),
+		overlays: snapshot.broll.map((placement) => ({
+			id: placement.id,
+			sourcePath: placement.assetPath,
+			outputStartSeconds: seconds(placement.outputStartMs),
+			outputEndSeconds: seconds(placement.outputEndMs),
+			...(placement.assetStartMs === undefined ? {} : { sourceStartSeconds: seconds(placement.assetStartMs) }),
+			fit: placement.fit,
+			audio: placement.audio,
+		})),
+	};
+}

package/src/project.ts

@@ -0,0 +1,289 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type {
+	ArollSegment,
+	BrollPlacement,
+	BrollPlacementInput,
+	TalkingHeadPolicy,
+	TalkingHeadProject,
+	TalkingHeadSnapshot,
+	TranscriptAnalysis,
+	WordTranscript,
+} from "./contracts.ts";
+import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
+import { resolveExistingWorkspaceFile, resolveWorkspacePath, snapshotFile, workspaceRelativePath } from "./workspace.ts";
+
+const PROJECT_ID = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+
+export interface CreateTalkingHeadProjectInput {
+	projectId: string;
+	sourcePath: string;
+	transcriptPath: string;
+	policy?: Partial<TalkingHeadPolicy>;
+}
+
+export interface ApplyTimelineInput {
+	projectId: string;
+	expectedRevision: number;
+	aroll: ArollSegment[];
+	broll: BrollPlacementInput[];
+}
+
+function assertProjectId(projectId: string): void {
+	if (!PROJECT_ID.test(projectId)) {
+		throw new Error("Project ID must use 1-64 lowercase letters, numbers, or interior hyphens");
+	}
+}
+
+async function projectsRoot(cwd: string): Promise<string> {
+	return await resolveWorkspacePath(cwd, ".talking-head/projects/.keep").then(dirname);
+}
+
+async function projectDirectory(cwd: string, projectId: string): Promise<string> {
+	assertProjectId(projectId);
+	return join(await projectsRoot(cwd), projectId);
+}
+
+async function readJson<T>(path: string, label: string): Promise<T> {
+	try {
+		return JSON.parse(await readFile(path, "utf8")) as T;
+	} catch (error) {
+		throw new Error(`Invalid ${label}: ${(error as Error).message}`);
+	}
+}
+
+async function writeJson(path: string, value: unknown, exclusive = false): Promise<void> {
+	await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, exclusive ? { flag: "wx" } : undefined);
+}
+
+function uniqueIds(values: Array<{ id: string }>, label: string): void {
+	const ids = new Set<string>();
+	for (const value of values) {
+		if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(value.id)) {
+			throw new Error(`${label} ID must use lowercase letters, numbers, or interior hyphens: ${value.id}`);
+		}
+		if (ids.has(value.id)) throw new Error(`Duplicate ${label} ID: ${value.id}`);
+		ids.add(value.id);
+	}
+}
+
+async function validateTimeline(
+	cwd: string,
+	aroll: ArollSegment[],
+	broll: BrollPlacementInput[],
+): 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");
+	for (const segment of aroll) {
+		if (!Number.isFinite(segment.sourceStartMs) || !Number.isFinite(segment.sourceEndMs)
+			|| segment.sourceStartMs < 0 || segment.sourceEndMs <= segment.sourceStartMs) {
+			throw new Error(`Invalid A-roll segment range: ${segment.id}`);
+		}
+	}
+	const outputDurationMs = timelineDuration(aroll);
+	if (broll.length > 500) throw new Error("B-roll must contain at most 500 placements");
+	uniqueIds(broll, "B-roll placement");
+	const normalizedBroll: BrollPlacement[] = [];
+	for (const placement of broll) {
+		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}`);
+		}
+		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 (placement.audio !== "keep-primary") throw new Error("B-roll audio must keep the primary A-roll audio");
+		const asset = await snapshotFile(cwd, placement.assetPath);
+		normalizedBroll.push({
+			...structuredClone(placement),
+			assetPath: asset.path,
+			assetBytes: asset.bytes,
+			assetSha256: asset.sha256,
+		});
+	}
+	return { outputDurationMs, broll: normalizedBroll };
+}
+
+function summary(analysis: TranscriptAnalysis) {
+	return {
+		wordCount: analysis.words.length,
+		pauseCount: analysis.candidates.length,
+		safePauses: analysis.candidates.filter((candidate) => candidate.classification === "safe").length,
+		reviewPauses: analysis.candidates.filter((candidate) => candidate.classification === "review").length,
+		unsafePauses: analysis.candidates.filter((candidate) => candidate.classification === "unsafe").length,
+		defaultSegmentCount: analysis.segments.length,
+		defaultOutputDurationMs: analysis.outputDurationMs,
+	};
+}
+
+function assertWordSafeSegments(aroll: ArollSegment[], analysis: TranscriptAnalysis): void {
+	for (const segment of aroll) {
+		for (const word of analysis.words) {
+			if (segment.sourceStartMs > word.beginMs && segment.sourceStartMs < word.endMs) {
+				throw new Error(`A-roll segment ${segment.id} starts inside word "${word.text}"`);
+			}
+			if (segment.sourceEndMs > word.beginMs && segment.sourceEndMs < word.endMs) {
+				throw new Error(`A-roll segment ${segment.id} ends inside word "${word.text}"`);
+			}
+		}
+	}
+}
+
+export async function createTalkingHeadProject(cwd: string, input: CreateTalkingHeadProjectInput) {
+	assertProjectId(input.projectId);
+	const source = await snapshotFile(cwd, input.sourcePath);
+	const transcript = await snapshotFile(cwd, input.transcriptPath);
+	const transcriptAbsolute = await resolveExistingWorkspaceFile(cwd, input.transcriptPath);
+	const transcriptPayload = await readJson<WordTranscript>(transcriptAbsolute, "word transcript");
+	const policy = { ...DEFAULT_POLICY, ...input.policy };
+	const analysis = analyzeTranscript(transcriptPayload, policy);
+	const root = await projectsRoot(cwd);
+	await mkdir(root, { recursive: true });
+	const target = await projectDirectory(cwd, input.projectId);
+	const temporary = join(root, `.${input.projectId}.${randomUUID()}.tmp`);
+	await mkdir(join(temporary, "snapshots"), { recursive: true });
+	const now = new Date().toISOString();
+	const analysisPath = `.talking-head/projects/${input.projectId}/analysis.json`;
+	const project: TalkingHeadProject = {
+		schemaVersion: 1,
+		projectId: input.projectId,
+		currentRevision: 1,
+		source,
+		transcript,
+		analysisPath,
+		createdAt: now,
+		updatedAt: now,
+	};
+	const snapshot: TalkingHeadSnapshot = {
+		schemaVersion: 1,
+		projectId: input.projectId,
+		revision: 1,
+		parentRevision: null,
+		createdAt: now,
+		policy,
+		aroll: analysis.segments,
+		broll: [],
+		outputDurationMs: analysis.outputDurationMs,
+	};
+	try {
+		await writeJson(join(temporary, "analysis.json"), analysis, true);
+		await writeJson(join(temporary, "snapshots", "1.json"), snapshot, true);
+		await writeJson(join(temporary, "project.json"), project, true);
+		try {
+			await rename(temporary, target);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST" || (error as NodeJS.ErrnoException).code === "ENOTEMPTY") {
+				throw new Error(`Project already exists: ${input.projectId}`);
+			}
+			throw error;
+		}
+	} catch (error) {
+		await rm(temporary, { recursive: true, force: true });
+		throw error;
+	}
+	return { project, snapshot, summary: summary(analysis) };
+}
+
+export async function getTalkingHeadProject(cwd: string, projectId: string, revision?: number) {
+	const directory = await projectDirectory(cwd, projectId);
+	const project = await readJson<TalkingHeadProject>(join(directory, "project.json"), `talking-head project ${projectId}`);
+	if (project.schemaVersion !== 1 || project.projectId !== projectId || !Number.isInteger(project.currentRevision)) {
+		throw new Error(`Invalid talking-head project: ${projectId}`);
+	}
+	const selectedRevision = revision ?? project.currentRevision;
+	if (!Number.isInteger(selectedRevision) || selectedRevision < 1 || selectedRevision > project.currentRevision) {
+		throw new Error(`Invalid talking-head revision: ${projectId}@${selectedRevision}`);
+	}
+	const snapshot = await readJson<TalkingHeadSnapshot>(
+		join(directory, "snapshots", `${selectedRevision}.json`),
+		`talking-head snapshot ${projectId}@${selectedRevision}`,
+	);
+	if (snapshot.schemaVersion !== 1 || snapshot.projectId !== projectId || snapshot.revision !== selectedRevision) {
+		throw new Error(`Invalid talking-head snapshot: ${projectId}@${selectedRevision}`);
+	}
+	return { project, snapshot };
+}
+
+async function acquireLock(directory: string): Promise<() => Promise<void>> {
+	const lockPath = join(directory, ".write-lock");
+	let handle;
+	try {
+		handle = await open(lockPath, "wx");
+		await handle.writeFile(`${process.pid}\n`);
+	} catch (error) {
+		await handle?.close().catch(() => undefined);
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Project is busy: ${directory.split("/").at(-1)}`);
+		throw error;
+	}
+	await handle.close();
+	return async () => { await unlink(lockPath).catch(() => undefined); };
+}
+
+export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Promise<TalkingHeadSnapshot> {
+	const directory = await projectDirectory(cwd, input.projectId);
+	const release = await acquireLock(directory);
+	try {
+		const { project, snapshot: current } = await getTalkingHeadProject(cwd, input.projectId);
+		if (project.currentRevision !== input.expectedRevision) {
+			throw new Error(`Project ${input.projectId} expected revision ${input.expectedRevision} but current revision is ${project.currentRevision}`);
+		}
+		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 revision = project.currentRevision + 1;
+		const now = new Date().toISOString();
+		const snapshot: TalkingHeadSnapshot = {
+			schemaVersion: 1,
+			projectId: input.projectId,
+			revision,
+			parentRevision: current.revision,
+			createdAt: now,
+			policy: current.policy,
+			aroll: structuredClone(input.aroll),
+			broll: validated.broll,
+			outputDurationMs: validated.outputDurationMs,
+		};
+		await writeJson(join(directory, "snapshots", `${revision}.json`), snapshot, true);
+		const nextProject: TalkingHeadProject = { ...project, currentRevision: revision, updatedAt: now };
+		const temporary = join(directory, `.project.${randomUUID()}.tmp`);
+		await writeJson(temporary, nextProject, true);
+		await rename(temporary, join(directory, "project.json"));
+		return snapshot;
+	} finally {
+		await release();
+	}
+}
+
+export async function getAnalysis(cwd: string, project: TalkingHeadProject): Promise<TranscriptAnalysis> {
+	const absolute = await resolveExistingWorkspaceFile(cwd, project.analysisPath);
+	return await readJson<TranscriptAnalysis>(absolute, `talking-head analysis ${project.projectId}`);
+}
+
+export async function assertProjectSourcesUnchanged(cwd: string, project: TalkingHeadProject): Promise<void> {
+	const currentSource = await snapshotFile(cwd, project.source.path);
+	const currentTranscript = await snapshotFile(cwd, project.transcript.path);
+	if (currentSource.sha256 !== project.source.sha256 || currentSource.bytes !== project.source.bytes) {
+		throw new Error(`Source media changed after project creation: ${project.source.path}`);
+	}
+	if (currentTranscript.sha256 !== project.transcript.sha256 || currentTranscript.bytes !== project.transcript.bytes) {
+		throw new Error(`Transcript changed after project creation: ${project.transcript.path}`);
+	}
+}
+
+export async function assertSnapshotAssetsUnchanged(cwd: string, snapshot: TalkingHeadSnapshot): Promise<void> {
+	for (const placement of snapshot.broll) {
+		const current = await snapshotFile(cwd, placement.assetPath);
+		if (current.sha256 !== placement.assetSha256 || current.bytes !== placement.assetBytes) {
+			throw new Error(`B-roll asset changed after timeline revision ${snapshot.revision}: ${placement.assetPath}`);
+		}
+	}
+}
+
+export async function projectStatePath(cwd: string, projectId: string, suffix: string): Promise<string> {
+	return await workspaceRelativePath(cwd, join(await projectDirectory(cwd, projectId), suffix));
+}

package/src/transcript.ts

@@ -0,0 +1,121 @@
+import type {
+	ArollSegment,
+	PauseCandidate,
+	PauseClassification,
+	TalkingHeadPolicy,
+	TranscriptAnalysis,
+	TranscriptWord,
+	WordTranscript,
+} from "./contracts.ts";
+
+export const DEFAULT_POLICY: TalkingHeadPolicy = {
+	cutThresholdMs: 500,
+	headPaddingMs: 50,
+	tailPaddingMs: 80,
+};
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function classifyPause(durationMs: number): PauseClassification {
+	if (durationMs >= 400) return "safe";
+	if (durationMs >= 150) return "review";
+	return "unsafe";
+}
+
+function validatePolicy(policy: TalkingHeadPolicy): void {
+	if (!Number.isFinite(policy.cutThresholdMs) || policy.cutThresholdMs < 150) {
+		throw new Error("cutThresholdMs must be at least 150ms");
+	}
+	for (const [name, value] of [["headPaddingMs", policy.headPaddingMs], ["tailPaddingMs", policy.tailPaddingMs]] as const) {
+		if (!Number.isFinite(value) || value < 30 || value > 200) {
+			throw new Error(`${name} must be within the 30-200ms working window`);
+		}
+	}
+}
+
+function flattenWords(transcript: WordTranscript): TranscriptWord[] {
+	if (typeof transcript.text !== "string" || !Array.isArray(transcript.sentences)) {
+		throw new Error("Transcript must contain text and sentences");
+	}
+	const words = transcript.sentences.flatMap((sentence) => {
+		if (!sentence || !Array.isArray(sentence.words)) throw new Error("Transcript sentence is missing words");
+		return sentence.words;
+	});
+	if (words.length === 0) throw new Error("Transcript contains no word timestamps");
+	let previousEnd = -1;
+	for (const word of words) {
+		if (typeof word.text !== "string" || !word.text.trim()
+			|| !finiteNonNegative(word.beginMs) || !finiteNonNegative(word.endMs)
+			|| word.endMs <= word.beginMs) {
+			throw new Error("Transcript contains an invalid word timestamp");
+		}
+		if (word.beginMs < previousEnd) throw new Error("Transcript word timestamps overlap or are out of order");
+		previousEnd = word.endMs;
+	}
+	return words.map((word) => ({ ...word, punctuation: word.punctuation ?? "" }));
+}
+
+function candidatesFrom(words: TranscriptWord[]): PauseCandidate[] {
+	const candidates: PauseCandidate[] = [];
+	for (let index = 1; index < words.length; index += 1) {
+		const before = words[index - 1];
+		const after = words[index];
+		if (!before || !after) continue;
+		const durationMs = after.beginMs - before.endMs;
+		if (durationMs <= 0) continue;
+		candidates.push({
+			id: `pause-${String(candidates.length + 1).padStart(3, "0")}`,
+			startMs: before.endMs,
+			endMs: after.beginMs,
+			durationMs,
+			classification: classifyPause(durationMs),
+			beforeText: `${before.text}${before.punctuation}`,
+			afterText: after.text,
+		});
+	}
+	return candidates;
+}
+
+function defaultSegments(words: TranscriptWord[], policy: TalkingHeadPolicy): ArollSegment[] {
+	const segments: ArollSegment[] = [];
+	let segmentStart = Math.max(0, words[0]!.beginMs - policy.headPaddingMs);
+	for (let index = 1; index < words.length; index += 1) {
+		const before = words[index - 1]!;
+		const after = words[index]!;
+		if (after.beginMs - before.endMs < policy.cutThresholdMs) continue;
+		segments.push({
+			id: `a-${String(segments.length + 1).padStart(3, "0")}`,
+			sourceStartMs: segmentStart,
+			sourceEndMs: before.endMs + policy.tailPaddingMs,
+		});
+		segmentStart = Math.max(0, after.beginMs - policy.headPaddingMs);
+	}
+	segments.push({
+		id: `a-${String(segments.length + 1).padStart(3, "0")}`,
+		sourceStartMs: segmentStart,
+		sourceEndMs: words.at(-1)!.endMs + policy.tailPaddingMs,
+	});
+	return segments;
+}
+
+export function timelineDuration(segments: ArollSegment[]): number {
+	return segments.reduce((total, segment) => total + segment.sourceEndMs - segment.sourceStartMs, 0);
+}
+
+export function analyzeTranscript(
+	transcript: WordTranscript,
+	overrides: Partial<TalkingHeadPolicy> = {},
+): TranscriptAnalysis {
+	const policy = { ...DEFAULT_POLICY, ...overrides };
+	validatePolicy(policy);
+	const words = flattenWords(transcript);
+	const segments = defaultSegments(words, policy);
+	return {
+		words,
+		candidates: candidatesFrom(words),
+		segments,
+		outputDurationMs: timelineDuration(segments),
+	};
+}

package/src/workspace.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { FileRef } from "./contracts.ts";
+
+function isWithin(root: string, candidate: string): boolean {
+	const pathFromRoot = relative(root, candidate);
+	return pathFromRoot === "" || (!pathFromRoot.startsWith(`..${sep}`) && pathFromRoot !== ".." && !isAbsolute(pathFromRoot));
+}
+
+async function nearestExistingAncestor(path: string): Promise<string> {
+	let current = path;
+	while (true) {
+		try {
+			await stat(current);
+			return current;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			const parent = dirname(current);
+			if (parent === current) throw error;
+			current = parent;
+		}
+	}
+}
+
+export async function workspaceRoot(cwd: string): Promise<string> {
+	return await realpath(cwd);
+}
+
+export async function resolveExistingWorkspaceFile(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-file symlink: ${inputPath}`);
+	const canonical = await realpath(lexical);
+	if (!isWithin(root, canonical)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	if (!(await stat(canonical)).isFile()) throw new Error(`Path is not a file: ${inputPath}`);
+	return canonical;
+}
+
+export async function resolveWorkspacePath(cwd: string, inputPath: string): Promise<string> {
+	const root = await workspaceRoot(cwd);
+	const lexical = resolve(root, inputPath);
+	if (lexical === root || !isWithin(root, lexical)) throw new Error(`Path is outside the workspace: ${inputPath}`);
+	const ancestor = await nearestExistingAncestor(dirname(lexical));
+	const canonicalAncestor = await realpath(ancestor);
+	if (!isWithin(root, canonicalAncestor)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	return lexical;
+}
+
+export async function workspaceRelativePath(cwd: string, absolutePath: string): Promise<string> {
+	const root = await workspaceRoot(cwd);
+	if (!isWithin(root, absolutePath)) throw new Error(`Path is outside the workspace: ${absolutePath}`);
+	return relative(root, absolutePath).split(sep).join("/");
+}
+
+async function sha256File(path: string): Promise<string> {
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+
+export async function snapshotFile(cwd: string, inputPath: string): Promise<FileRef> {
+	const absolute = await resolveExistingWorkspaceFile(cwd, inputPath);
+	return {
+		path: await workspaceRelativePath(cwd, absolute),
+		bytes: (await stat(absolute)).size,
+		sha256: await sha256File(absolute),
+	};
+}