@speclip/pi-talking-head 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @speclip/pi-talking-head
 
-给 [Pi](https://github.com/earendil-works/pi) 用的口播剪辑决策包。它读取 `pi-speech` 风格的词级时间戳，识别词间停顿，生成保守的 A-roll 剪辑方案，并可加入 B-roll 规划。
+给 [Pi](https://github.com/earendil-works/pi) 用的口播剪辑决策包。它读取 `pi-speech` 风格的词级时间戳，结合整句上下文识别词间停顿、语气词和相邻重复，生成保守的 A-roll 剪辑方案，并可加入 B-roll 规划。
 
 它不直接调用 FFmpeg。最终输出是 `pi-media@0.3.1` 的通用 timeline EDL，由 `pi-media` 负责素材校验、不可变 revision、渲染和验收。
 
@@ -42,25 +42,34 @@ talking_head_create {
 }
 ```
 
-默认只自动移除至少 500ms 的词间停顿。每个保留片段前留 50ms、后留 80ms，避免切掉辅音、尾音和自然气口。停顿还会分为：
+默认只自动移除至少 500ms、且没有语气词或表达边界保护信号的词间停顿。每个保留片段前留 50ms、后留 80ms，避免切掉辅音、尾音和自然气口。停顿还会分为：
 
 - `safe`：至少 400ms，通常可以切。
 - `review`：150–399ms，必须结合语义和画面判断。
 - `unsafe`：少于 150ms，默认不切。
 
-工具返回 revision 1、停顿摘要和可直接交给 `pi-media.edit_apply` 的 `mediaOperation`。
+若停顿紧邻候选语气词，或位于问号、感叹号等表达边界之后，即使超过阈值也会降级为 `review`，不会进入默认自动剪辑。工具返回 revision 1、内容与停顿摘要，以及可直接交给 `pi-media.edit_apply` 的 `mediaOperation`。
 
-### 2. 分页检查候选气口
+### 2. 分页检查整句和编辑候选
 
 ```js
 talking_head_get {
   projectId: "launch-video",
+  sentenceOffset: 0,
+  sentenceLimit: 20,
   pauseOffset: 0,
-  pauseLimit: 50
+  pauseLimit: 50,
+  fillerOffset: 0,
+  fillerLimit: 50,
+  repetitionOffset: 0,
+  repetitionLimit: 50,
+  includeTranscriptText: true
 }
 ```
 
-只有调用这个工具时才会把候选停顿放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
+工具会分页返回整句上下文、停顿、语气词和相邻重复；需要判断整段结构时可显式取得完整转录文本。`啊`、`额`、`嗯` 等只会成为 `review` 候选，Agent 必须判断它是口癖、语义成分还是刻意表达，不能自动删除。文本标点只能提供低置信度且可以并存的表达线索，不等同于声学情绪识别。
+
+只有调用这个工具时才会把这些证据放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
 
 ### 3. 写入人工确认后的时间线
 
@@ -114,10 +123,10 @@ review { path: "out/launch-final.mp4" }
 
 | 工具 | 作用 |
 | --- | --- |
-| `talking_head_create` | 从视频和词级转录建立 revision 1，分析停顿并生成默认 EDL |
-| `talking_head_get` | 读取指定 revision，分页返回停顿候选，可选导出 pi-media EDL |
+| `talking_head_create` | 从视频和词级转录建立 revision 1，分析句子、语气词、重复和停顿并生成默认 EDL |
+| `talking_head_get` | 读取指定 revision，分页返回整句与编辑候选，可选导出 pi-media EDL |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |
 
 ## 当前边界
 
-0.1.0 不负责语音转录、素材搜索、字幕、画面理解或渲染。它只提供稳定的口播时间线决策层。B-roll 的搜索与视觉匹配可以后续新增为独立 Skill 或 Extension，最终仍写入同一份 `broll` 数据并由 `pi-media` 渲染。
+当前版本不负责语音转录、声学情绪识别、素材搜索、字幕、画面理解或渲染。它提供整句文本与时间轴层面的编辑证据；需要依赖真实语气、呼吸或表演意图的决定，必须由 Agent 结合原音频和画面复核。B-roll 的搜索与视觉匹配最终仍写入同一份 `broll` 数据并由 `pi-media` 渲染。

package/extensions/talking-head/index.ts

@@ -75,29 +75,64 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_get",
 		label: "Inspect talking-head edit",
-		description: "Read one immutable talking-head revision and a bounded page of pause candidates. Optionally include the generic pi-media timeline operation for that revision.",
+		description: "Read one immutable talking-head revision plus bounded sentence, pause, filler-word, and repetition evidence for Agent editorial judgment. Optionally include the generic pi-media timeline operation.",
 		parameters: Type.Object({
 			projectId: stableId,
 			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			sentenceOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			sentenceLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 			pauseOffset: Type.Optional(Type.Integer({ minimum: 0 })),
 			pauseLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			fillerOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			fillerLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			repetitionOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			repetitionLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+			includeTranscriptText: Type.Optional(Type.Boolean({ description: "Include the complete transcript text for passage-level Agent review." })),
 			includeMediaOperation: Type.Optional(Type.Boolean()),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const { project, snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
 			const analysis = await getAnalysis(ctx.cwd, project);
-			const offset = params.pauseOffset ?? 0;
-			const limit = params.pauseLimit ?? 50;
+			const sentenceOffset = params.sentenceOffset ?? 0;
+			const sentenceLimit = params.sentenceLimit ?? 20;
+			const pauseOffset = params.pauseOffset ?? 0;
+			const pauseLimit = params.pauseLimit ?? 50;
+			const fillerOffset = params.fillerOffset ?? 0;
+			const fillerLimit = params.fillerLimit ?? 50;
+			const repetitionOffset = params.repetitionOffset ?? 0;
+			const repetitionLimit = params.repetitionLimit ?? 50;
+			const sentences = analysis.sentences ?? [];
+			const fillers = analysis.fillers ?? [];
+			const repetitions = analysis.repetitions ?? [];
 			const details: Record<string, unknown> = {
 				project,
 				snapshot,
+				sentences: {
+					offset: sentenceOffset,
+					limit: sentenceLimit,
+					total: sentences.length,
+					items: sentences.slice(sentenceOffset, sentenceOffset + sentenceLimit),
+				},
 				pauses: {
-					offset,
-					limit,
+					offset: pauseOffset,
+					limit: pauseLimit,
 					total: analysis.candidates.length,
-					items: analysis.candidates.slice(offset, offset + limit),
+					items: analysis.candidates.slice(pauseOffset, pauseOffset + pauseLimit),
+				},
+				fillers: {
+					offset: fillerOffset,
+					limit: fillerLimit,
+					total: fillers.length,
+					items: fillers.slice(fillerOffset, fillerOffset + fillerLimit),
+				},
+				repetitions: {
+					offset: repetitionOffset,
+					limit: repetitionLimit,
+					total: repetitions.length,
+					items: repetitions.slice(repetitionOffset, repetitionOffset + repetitionLimit),
 				},
 			};
+			if (params.includeTranscriptText) details.transcriptText = analysis.text;
 			if (params.includeMediaOperation) {
 				await assertProjectSourcesUnchanged(ctx.cwd, project);
 				await assertSnapshotAssetsUnchanged(ctx.cwd, snapshot);

package/package.json

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

package/prompts/edit-talking-head.md

@@ -2,6 +2,6 @@
 description: Tighten a talking-head video without destroying natural speech rhythm
 ---
 
-Use the `talking-head-edit` skill to analyze word-level pauses, propose a conservative cut strategy, optionally place justified B-roll, and export a generic pi-media EDL for this request: $@
+Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; 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

@@ -9,10 +9,11 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
 
 1. Obtain a `pi-speech`-compatible transcript JSON containing word-level `beginMs` and `endMs`. Do not infer frame-accurate cuts from sentence text alone.
 2. Call `talking_head_create` with the source video and transcript. Keep the default 500ms cut threshold, 50ms head padding, and 80ms tail padding unless the user requests a different rhythm.
-3. Inspect pause candidates with bounded `talking_head_get` pages. Treat `safe` as a candidate, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
-4. Before changing the revision, summarize the proposed rhythm: what will be removed, which short pauses will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
-5. Call `talking_head_apply` using exact word-boundary A-roll ranges. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
-6. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
+3. Inspect bounded `talking_head_get` pages. Review the full sentence context, filler candidates, and repetition candidates together with pauses. Treat `safe` and every recommendation as evidence, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
+4. Never delete a filler token automatically. Decide whether `啊`, `额`, `嗯`, or a repeated token is a false start, a discourse marker, or intentional emphasis from its sentence context. A text-only delivery cue is low-confidence evidence; review audio and picture before relying on emotion or performance intent.
+5. Before changing the revision, summarize the proposed rhythm: what words and gaps will be removed, which pauses or fillers will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
+6. 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`.
 
 Never overwrite source media or outputs. If a revision conflict occurs, re-read both projects and reconcile intent. If the source, transcript, or B-roll hash changed, stop and ask whether to create a new project rather than silently adopting new bytes.
 

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

@@ -8,6 +8,13 @@
 - Prefer one clean removal over many micro-cuts. Dense sub-150ms cuts create robotic cadence and visible jump cuts.
 - `pi-media` adds a 30ms audio fade at every primary-segment edge to suppress clicks. This does not repair a semantically bad cut.
 
+## Editing spoken content
+
+- Read the complete sentence before removing a filler or repeated word. `啊`, `嗯`, `那个`, and `就是` can carry hesitation, emphasis, transition, or actual meaning.
+- Treat transcript punctuation as a low-confidence delivery hint, not acoustic emotion detection. Confirm expressive decisions against the source audio and picture.
+- Prefer removing a complete false start at word boundaries over deleting an isolated sound that leaves an unnatural join.
+- If a necessary content cut creates a hard join, preserve room tone and use a short transition or justified B-roll rather than compressing every gap.
+
 ## Using B-roll
 
 - Place B-roll on the output timeline after A-roll cuts have stabilized.

package/src/contracts.ts

@@ -28,6 +28,57 @@ export interface PauseCandidate {
 	classification: PauseClassification;
 	beforeText: string;
 	afterText: string;
+	boundary: "within-sentence" | "between-sentences";
+	context: {
+		before: string;
+		after: string;
+	};
+	adjacentFillerIds: string[];
+	recommendation: EditorialRecommendation;
+	reasons: string[];
+}
+
+export type EditorialRecommendation = "cut" | "review" | "keep";
+export type DeliveryCue = "neutral" | "hesitation" | "emphasis" | "question";
+
+export interface SentenceAnalysis {
+	sentenceIndex: number;
+	sentenceId: number;
+	beginMs: number;
+	endMs: number;
+	text: string;
+	wordStartIndex: number;
+	wordEndIndex: number;
+	deliveryCues: DeliveryCue[];
+	confidence: "low";
+	evidence: string[];
+}
+
+export interface FillerCandidate {
+	id: string;
+	wordIndex: number;
+	sentenceIndex: number;
+	text: string;
+	startMs: number;
+	endMs: number;
+	kind: "hesitation" | "discourse";
+	matchConfidence: "exact" | "contextual";
+	recommendation: "review";
+	contextText: string;
+	reasons: string[];
+}
+
+export interface RepetitionCandidate {
+	id: string;
+	sentenceIndex: number;
+	text: string;
+	firstWordIndex: number;
+	secondWordIndex: number;
+	startMs: number;
+	endMs: number;
+	recommendation: "review";
+	contextText: string;
+	reasons: string[];
 }
 
 export interface ArollSegment {
@@ -53,7 +104,12 @@ export interface BrollPlacement {
 export type BrollPlacementInput = Omit<BrollPlacement, "assetBytes" | "assetSha256">;
 
 export interface TranscriptAnalysis {
+	schemaVersion: 2;
+	text: string;
 	words: TranscriptWord[];
+	sentences: SentenceAnalysis[];
+	fillers: FillerCandidate[];
+	repetitions: RepetitionCandidate[];
 	candidates: PauseCandidate[];
 	segments: ArollSegment[];
 	outputDurationMs: number;

package/src/project.ts

@@ -5,10 +5,15 @@ import type {
 	ArollSegment,
 	BrollPlacement,
 	BrollPlacementInput,
+	FillerCandidate,
+	PauseCandidate,
+	RepetitionCandidate,
+	SentenceAnalysis,
 	TalkingHeadPolicy,
 	TalkingHeadProject,
 	TalkingHeadSnapshot,
 	TranscriptAnalysis,
+	TranscriptWord,
 	WordTranscript,
 } from "./contracts.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
@@ -111,10 +116,15 @@ async function validateTimeline(
 function summary(analysis: TranscriptAnalysis) {
 	return {
 		wordCount: analysis.words.length,
+		sentenceCount: analysis.sentences.length,
+		fillerCount: analysis.fillers.length,
+		repetitionCount: analysis.repetitions.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,
+		automaticCutPauses: analysis.candidates.filter((candidate) => candidate.recommendation === "cut").length,
+		editorialReviewPauses: analysis.candidates.filter((candidate) => candidate.recommendation === "review").length,
 		defaultSegmentCount: analysis.segments.length,
 		defaultOutputDurationMs: analysis.outputDurationMs,
 	};
@@ -261,7 +271,60 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput): Pro
 
 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}`);
+	const persisted = await readJson<{
+		schemaVersion?: number;
+		text?: string;
+		words: TranscriptWord[];
+		sentences?: SentenceAnalysis[];
+		fillers?: FillerCandidate[];
+		repetitions?: RepetitionCandidate[];
+		candidates: Array<Partial<PauseCandidate> & Pick<PauseCandidate, "id" | "startMs" | "endMs" | "durationMs" | "classification" | "beforeText" | "afterText">>;
+		segments: ArollSegment[];
+		outputDurationMs: number;
+	}>(absolute, `talking-head analysis ${project.projectId}`);
+	if (!Array.isArray(persisted.words) || !Array.isArray(persisted.candidates)
+		|| !Array.isArray(persisted.segments) || !Number.isFinite(persisted.outputDurationMs)) {
+		throw new Error(`Invalid talking-head analysis: ${project.projectId}`);
+	}
+	const completeV2 = persisted.schemaVersion === 2
+		&& typeof persisted.text === "string"
+		&& Array.isArray(persisted.sentences)
+		&& Array.isArray(persisted.fillers)
+		&& Array.isArray(persisted.repetitions);
+	if (!completeV2) {
+		const currentTranscript = await snapshotFile(cwd, project.transcript.path);
+		if (currentTranscript.sha256 !== project.transcript.sha256 || currentTranscript.bytes !== project.transcript.bytes) {
+			throw new Error(`Transcript changed before legacy analysis migration: ${project.transcript.path}`);
+		}
+		const transcriptAbsolute = await resolveExistingWorkspaceFile(cwd, project.transcript.path);
+		const transcriptPayload = await readJson<WordTranscript>(transcriptAbsolute, "word transcript");
+		const { snapshot } = await getTalkingHeadProject(cwd, project.projectId);
+		return analyzeTranscript(transcriptPayload, snapshot.policy);
+	}
+	return {
+		schemaVersion: 2,
+		text: persisted.text ?? "",
+		words: persisted.words,
+		sentences: persisted.sentences ?? [],
+		fillers: persisted.fillers ?? [],
+		repetitions: persisted.repetitions ?? [],
+		candidates: persisted.candidates.map((candidate) => ({
+			id: candidate.id,
+			startMs: candidate.startMs,
+			endMs: candidate.endMs,
+			durationMs: candidate.durationMs,
+			classification: candidate.classification,
+			beforeText: candidate.beforeText,
+			afterText: candidate.afterText,
+			boundary: candidate.boundary ?? "within-sentence",
+			context: candidate.context ?? { before: candidate.beforeText, after: candidate.afterText },
+			adjacentFillerIds: candidate.adjacentFillerIds ?? [],
+			recommendation: candidate.recommendation ?? "review",
+			reasons: candidate.reasons ?? ["Legacy pause analysis requires editorial review before cutting."],
+		})),
+		segments: persisted.segments,
+		outputDurationMs: persisted.outputDurationMs,
+	};
 }
 
 export async function assertProjectSourcesUnchanged(cwd: string, project: TalkingHeadProject): Promise<void> {

package/src/transcript.ts

@@ -1,13 +1,19 @@
 import type {
 	ArollSegment,
+	FillerCandidate,
 	PauseCandidate,
 	PauseClassification,
+	RepetitionCandidate,
+	SentenceAnalysis,
 	TalkingHeadPolicy,
 	TranscriptAnalysis,
 	TranscriptWord,
 	WordTranscript,
 } from "./contracts.ts";
 
+const HESITATION_FILLERS = new Set(["嗯", "呃", "额", "唔", "呣", "em", "um", "uh"]);
+const CONTEXTUAL_FILLERS = new Set(["啊", "呀", "那个", "这个", "就是", "然后"]);
+
 export const DEFAULT_POLICY: TalkingHeadPolicy = {
 	cutThresholdMs: 500,
 	headPaddingMs: 50,
@@ -40,7 +46,17 @@ function flattenWords(transcript: WordTranscript): TranscriptWord[] {
 		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");
+		if (!sentence || !Number.isInteger(sentence.id) || typeof sentence.text !== "string"
+			|| !finiteNonNegative(sentence.beginMs) || !finiteNonNegative(sentence.endMs)
+			|| sentence.endMs <= sentence.beginMs || !Array.isArray(sentence.words) || sentence.words.length === 0) {
+			throw new Error("Transcript contains an invalid sentence timestamp or metadata");
+		}
+		const first = sentence.words[0]!;
+		const last = sentence.words.at(-1)!;
+		if (!finiteNonNegative(first.beginMs) || !finiteNonNegative(last.endMs)
+			|| first.beginMs < sentence.beginMs || last.endMs > sentence.endMs) {
+			throw new Error("Transcript sentence timestamp does not contain its word timestamps");
+		}
 		return sentence.words;
 	});
 	if (words.length === 0) throw new Error("Transcript contains no word timestamps");
@@ -57,14 +73,172 @@ function flattenWords(transcript: WordTranscript): TranscriptWord[] {
 	return words.map((word) => ({ ...word, punctuation: word.punctuation ?? "" }));
 }
 
-function candidatesFrom(words: TranscriptWord[]): PauseCandidate[] {
+function normalizedSpokenText(text: string): string {
+	return text.trim().toLowerCase().replace(/^[\p{P}\p{S}\s]+|[\p{P}\p{S}\s]+$/gu, "");
+}
+
+function fillerCandidates(transcript: WordTranscript, words: TranscriptWord[]): FillerCandidate[] {
+	const candidates: FillerCandidate[] = [];
+	let wordIndex = 0;
+	for (let sentenceIndex = 0; sentenceIndex < transcript.sentences.length; sentenceIndex += 1) {
+		const sentence = transcript.sentences[sentenceIndex]!;
+		for (const _word of sentence.words) {
+			const word = words[wordIndex]!;
+			const normalized = normalizedSpokenText(word.text);
+			const hesitation = HESITATION_FILLERS.has(normalized);
+			const contextual = CONTEXTUAL_FILLERS.has(normalized);
+			if (hesitation || contextual) {
+				candidates.push({
+					id: `filler-${String(candidates.length + 1).padStart(3, "0")}`,
+					wordIndex,
+					sentenceIndex,
+					text: word.text,
+					startMs: word.beginMs,
+					endMs: word.endMs,
+					kind: hesitation ? "hesitation" : "discourse",
+					matchConfidence: hesitation ? "exact" : "contextual",
+					recommendation: "review",
+					contextText: sentence.text,
+					reasons: hesitation
+						? ["The token commonly marks hesitation, but may still carry delivery intent."]
+						: ["The token can be either a filler or meaningful discourse, so context is required."],
+				});
+			}
+			wordIndex += 1;
+		}
+	}
+	return candidates;
+}
+
+function sentenceAnalyses(transcript: WordTranscript, fillers: FillerCandidate[]): SentenceAnalysis[] {
+	let wordStartIndex = 0;
+	const fillersBySentence = new Map<number, FillerCandidate[]>();
+	for (const filler of fillers) {
+		const current = fillersBySentence.get(filler.sentenceIndex) ?? [];
+		current.push(filler);
+		fillersBySentence.set(filler.sentenceIndex, current);
+	}
+	return transcript.sentences.map((sentence, sentenceIndex) => {
+		const wordEndIndex = wordStartIndex + sentence.words.length - 1;
+		const sentenceFillers = fillersBySentence.get(sentenceIndex) ?? [];
+		const deliveryCues: SentenceAnalysis["deliveryCues"] = [];
+		const evidence: string[] = [];
+		const hesitationCount = sentenceFillers.filter((candidate) => candidate.kind === "hesitation").length;
+		if (hesitationCount > 0) {
+			deliveryCues.push("hesitation");
+			evidence.push(`Contains ${hesitationCount} hesitation-lexicon token(s).`);
+		}
+		if (/[？?]/u.test(sentence.text) || sentence.words.some((word) => /[？?]/u.test(word.punctuation ?? ""))) {
+			deliveryCues.push("question");
+			evidence.push("Question punctuation is present in the transcript.");
+		}
+		if (/[！!]/u.test(sentence.text) || sentence.words.some((word) => /[！!]/u.test(word.punctuation ?? ""))) {
+			deliveryCues.push("emphasis");
+			evidence.push("Emphasis punctuation is present in the transcript.");
+		}
+		if (deliveryCues.length === 0) {
+			deliveryCues.push("neutral");
+			evidence.push("No explicit delivery cue was found in transcript text.");
+		}
+		const analysis: SentenceAnalysis = {
+			sentenceIndex,
+			sentenceId: sentence.id,
+			beginMs: sentence.beginMs,
+			endMs: sentence.endMs,
+			text: sentence.text,
+			wordStartIndex,
+			wordEndIndex,
+			deliveryCues,
+			confidence: "low",
+			evidence,
+		};
+		wordStartIndex = wordEndIndex + 1;
+		return analysis;
+	});
+}
+
+function repetitionCandidates(transcript: WordTranscript, words: TranscriptWord[]): RepetitionCandidate[] {
+	const candidates: RepetitionCandidate[] = [];
+	let sentenceWordStart = 0;
+	for (let sentenceIndex = 0; sentenceIndex < transcript.sentences.length; sentenceIndex += 1) {
+		const sentence = transcript.sentences[sentenceIndex]!;
+		for (let offset = 1; offset < sentence.words.length; offset += 1) {
+			const firstWordIndex = sentenceWordStart + offset - 1;
+			const secondWordIndex = sentenceWordStart + offset;
+			const first = words[firstWordIndex]!;
+			const second = words[secondWordIndex]!;
+			const normalized = normalizedSpokenText(first.text);
+			if (!normalized || normalized !== normalizedSpokenText(second.text)) continue;
+			candidates.push({
+				id: `repetition-${String(candidates.length + 1).padStart(3, "0")}`,
+				sentenceIndex,
+				text: first.text,
+				firstWordIndex,
+				secondWordIndex,
+				startMs: first.beginMs,
+				endMs: second.endMs,
+				recommendation: "review",
+				contextText: sentence.text,
+				reasons: ["Two adjacent normalized tokens are identical; review whether this is a false start or intentional emphasis."],
+			});
+		}
+		sentenceWordStart += sentence.words.length;
+	}
+	return candidates;
+}
+
+function wordSentenceIndexes(transcript: WordTranscript): number[] {
+	return transcript.sentences.flatMap((sentence, sentenceIndex) => sentence.words.map(() => sentenceIndex));
+}
+
+function candidatesFrom(
+	words: TranscriptWord[],
+	transcript: WordTranscript,
+	fillers: FillerCandidate[],
+	policy: TalkingHeadPolicy,
+): PauseCandidate[] {
 	const candidates: PauseCandidate[] = [];
+	const sentenceIndexes = wordSentenceIndexes(transcript);
+	const fillersByWordIndex = new Map<number, FillerCandidate[]>();
+	for (const filler of fillers) {
+		fillersByWordIndex.set(filler.wordIndex, [...(fillersByWordIndex.get(filler.wordIndex) ?? []), filler]);
+	}
 	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;
+		const beforeSentenceIndex = sentenceIndexes[index - 1]!;
+		const afterSentenceIndex = sentenceIndexes[index]!;
+		const adjacentFillers = [
+			...(fillersByWordIndex.get(index - 1) ?? []),
+			...(fillersByWordIndex.get(index) ?? []),
+		];
+		const sentenceBoundary = beforeSentenceIndex !== afterSentenceIndex;
+		const beforeSentence = transcript.sentences[beforeSentenceIndex]!;
+		const expressiveBoundary = /[！!？?…]/u.test(before.punctuation) || /[！!？?…]\s*$/u.test(beforeSentence.text);
+		const reasons: string[] = [];
+		let recommendation: PauseCandidate["recommendation"];
+		if (durationMs < 150) {
+			recommendation = "keep";
+			reasons.push("The gap is shorter than 150ms and removing it risks robotic cadence.");
+		} else if (adjacentFillers.length > 0) {
+			recommendation = "review";
+			reasons.push("The gap touches a possible filler whose meaning must be judged in sentence context.");
+		} else if (expressiveBoundary) {
+			recommendation = "review";
+			reasons.push("The pause follows expressive punctuation and may carry emphasis, emotion, or a question beat.");
+		} else if (sentenceBoundary) {
+			recommendation = "review";
+			reasons.push("The gap is between sentences and may mark a paragraph, topic, or deliberate delivery boundary.");
+		} else if (durationMs >= policy.cutThresholdMs) {
+			recommendation = "cut";
+			reasons.push(`The unprotected word gap meets the ${policy.cutThresholdMs}ms automatic cut threshold.`);
+		} else {
+			recommendation = "review";
+			reasons.push("The gap is noticeable but does not meet the automatic cut threshold.");
+		}
 		candidates.push({
 			id: `pause-${String(candidates.length + 1).padStart(3, "0")}`,
 			startMs: before.endMs,
@@ -73,18 +247,28 @@ function candidatesFrom(words: TranscriptWord[]): PauseCandidate[] {
 			classification: classifyPause(durationMs),
 			beforeText: `${before.text}${before.punctuation}`,
 			afterText: after.text,
+			boundary: beforeSentenceIndex === afterSentenceIndex ? "within-sentence" : "between-sentences",
+			context: {
+				before: transcript.sentences[beforeSentenceIndex]!.text,
+				after: transcript.sentences[afterSentenceIndex]!.text,
+			},
+			adjacentFillerIds: adjacentFillers.map((candidate) => candidate.id),
+			recommendation,
+			reasons,
 		});
 	}
 	return candidates;
 }
 
-function defaultSegments(words: TranscriptWord[], policy: TalkingHeadPolicy): ArollSegment[] {
+function defaultSegments(words: TranscriptWord[], policy: TalkingHeadPolicy, candidates: PauseCandidate[]): ArollSegment[] {
 	const segments: ArollSegment[] = [];
+	const candidateByGap = new Map(candidates.map((candidate) => [`${candidate.startMs}:${candidate.endMs}`, candidate]));
 	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;
+		const candidate = candidateByGap.get(`${before.endMs}:${after.beginMs}`);
+		if (candidate?.recommendation !== "cut") continue;
 		segments.push({
 			id: `a-${String(segments.length + 1).padStart(3, "0")}`,
 			sourceStartMs: segmentStart,
@@ -111,10 +295,18 @@ export function analyzeTranscript(
 	const policy = { ...DEFAULT_POLICY, ...overrides };
 	validatePolicy(policy);
 	const words = flattenWords(transcript);
-	const segments = defaultSegments(words, policy);
+	const fillers = fillerCandidates(transcript, words);
+	const repetitions = repetitionCandidates(transcript, words);
+	const candidates = candidatesFrom(words, transcript, fillers, policy);
+	const segments = defaultSegments(words, policy, candidates);
 	return {
+		schemaVersion: 2,
+		text: transcript.text,
 		words,
-		candidates: candidatesFrom(words),
+		sentences: sentenceAnalyses(transcript, fillers),
+		fillers,
+		repetitions,
+		candidates,
 		segments,
 		outputDurationMs: timelineDuration(segments),
 	};