@speclip/pi-subtitles 0.2.0 → 0.2.2

package/README.md

@@ -18,7 +18,7 @@ B-roll 只覆盖画面而保留 A-roll 主音频时，不会改变字幕时间
 ## 环境要求
 
 - Node.js 22.19+
-- Pi 0.84.1–0.84.x
+- Pi 0.84.1–0.85.x
 - 一份含词级时间戳的 JSON 转录
 
 ## 安装与验证
@@ -115,7 +115,7 @@ subtitles_export {
 
 工具会按项目画幅自动使用安全区样式，并返回 SRT / ASS 文件引用、SHA-256 和持久化导出回执。横屏使用固定 `1920×1080` ASS 设计坐标，竖屏使用 `1080×1920`；这与源视频是 1080p 还是 4K 无关，libass 会等比缩放。不要把 4K 源分辨率直接写成 ASS 的 `PlayRes`。
 
-默认样式为大号粗体白字、黑色描边和柔和阴影。横屏位于画面下方安全区并保持单行；竖屏字幕上移，同时扩大右边距避开常见交互区。几何参数只允许在安全范围内微调，不能通过 `assStyle` 把字幕缩回不可读尺寸。默认字体是 `Noto Sans CJK SC`，渲染环境仍需安装该字体或提供可用回退字体。
+横屏和竖屏统一使用 `Source Han Sans SC Heavy`。白色字形不再附着黑色描边，而是使用向右下偏移的半透明黑色柔化阴影；横屏保持下方安全区，竖屏仍上移并扩大右边距，避开常见交互区。字体、阴影和几何参数只能在安全范围内微调。渲染环境必须真实安装该字体，不能依赖静默字体回退。
 
 本包的完成状态是“字幕轨道已生成并校验”，不是“字幕已经烧进视频”。最后应把轨道交给支持字幕的渲染器，并检查实际成片中的同步、遮挡、安全区、字体回退和漏字。
 
@@ -140,7 +140,7 @@ npm run check
 npm pack --dry-run
 ```
 
-GitHub Release 标签必须与 `package.json` 完全一致，例如 `v0.2.0`。发布工作流会在标签快照上重新执行检查并通过 npm OIDC 发布。
+GitHub Release 标签必须与 `package.json` 完全一致，例如 `v0.2.1`。发布工作流会在标签快照上重新执行检查并通过 npm OIDC 发布。
 
 ## License
 

package/extensions/subtitles/index.ts

@@ -49,9 +49,11 @@ const assStyle = Type.Object({
 	fontSize: Type.Optional(Type.Number({ minimum: 1, maximum: 500 })),
 	primaryColour: Type.Optional(Type.String({ pattern: "^&H[0-9A-Fa-f]{8}$" })),
 	outlineColour: Type.Optional(Type.String({ pattern: "^&H[0-9A-Fa-f]{8}$" })),
+	shadowColour: Type.Optional(Type.String({ pattern: "^&H[0-9A-Fa-f]{8}$" })),
 	bold: Type.Optional(Type.Boolean()),
 	outline: Type.Optional(Type.Number({ minimum: 0, maximum: 20 })),
 	shadow: Type.Optional(Type.Number({ minimum: 0, maximum: 20 })),
+	blur: Type.Optional(Type.Number({ minimum: 0, maximum: 20 })),
 	alignment: Type.Optional(Type.Integer({ minimum: 1, maximum: 9 })),
 	marginL: Type.Optional(Type.Integer({ minimum: 0, maximum: 4_000 })),
 	marginR: Type.Optional(Type.Integer({ minimum: 0, maximum: 4_000 })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-subtitles",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Agent-reviewed subtitle timing, layout, and standard track export for Pi",
   "type": "module",
   "license": "MIT",
@@ -52,11 +52,12 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.1 <0.85.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.1 <0.86.0",
     "typebox": "^1.3.7"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.85.0",
+    "@earendil-works/pi-server": "0.85.0",
     "@types/node": "22.20.1",
     "typebox": "1.3.7",
     "typescript": "7.0.2"

package/skills/add-subtitles/SKILL.md

@@ -14,7 +14,7 @@ Use `pi-speech` for word timestamps and this package for final-timeline mapping,
 5. Keep speech meaning intact. Correct ASR spelling or punctuation only with audio evidence. Do not delete content merely to make a line shorter. Preserve intentional fillers, emphasis, terminology, numbers, names, and sentence-ending tone.
 6. Prefer one complete idea per cue and natural boundaries at strong punctuation or acoustic pauses. Landscape captions are always one line and must be split into another timed cue when too long; never insert `\n`. Portrait captions may use at most two balanced lines. Avoid one-character orphan cues and rapid flashes. Do not force every cue to an identical duration; subtitle timing follows the actual delivery rhythm.
 7. If edits are needed, gather the complete cue list across all pages and call `subtitles_apply` with the current `expectedRevision` and a concrete `changeReason`. Never submit one paginated slice as if it were the full revision. If the revision changed, re-read and reconcile instead of overwriting another review.
-8. Call `subtitles_export` with the exact reviewed revision. SRT is the portable timing/text track. Request ASS for final burn-in: the project layout selects a canonical safe-area preset with large bold white text, black outline, soft shadow, and canvas-independent design coordinates. Do not replace `PlayRes` with the source video's 4K resolution. The default style names `Noto Sans CJK SC`; embedding or installing that font is the renderer's responsibility.
+8. Call `subtitles_export` with the exact reviewed revision. SRT is the portable timing/text track. Request ASS for final burn-in: both layouts use `Source Han Sans SC Heavy`, white glyphs without a black outline, and a softened semi-transparent black shadow offset down and right. Do not replace `PlayRes` with the source video's 4K resolution. Verify that the renderer really resolves this font instead of silently falling back.
 9. Keep rendering explicit. This package does not burn subtitles into video and does not invent FFmpeg arguments. Hand the returned SRT or ASS artifact and provenance receipt to a renderer that supports subtitle tracks, then visually review the actual final video for safe-area placement, occlusion, glyph fallback, sync, and missing text.
 
 Never overwrite a transcript, subtitle track, or render. If the transcript hash changes, create a new subtitle project so timing decisions stay reproducible.

package/skills/add-subtitles/references/timing-and-layout.md

@@ -22,8 +22,8 @@ Timing values are working defaults, not hard editorial targets. Landscape single
 
 ## Safe-area presets
 
-- Landscape uses canonical `1920×1080` ASS coordinates: font 80, bold, outline 3, shadow 3, left/right margins 120, bottom margin 140.
-- Portrait uses canonical `1080×1920` ASS coordinates: font 72, bold, outline 3, shadow 3, left margin 90, right margin 200, bottom margin 460.
+- Landscape uses canonical `1920×1080` ASS coordinates: `Source Han Sans SC Heavy` at font 80, no outline, shadow offset 4 with blur 0.6, left/right margins 120, bottom margin 120.
+- Portrait uses canonical `1080×1920` ASS coordinates: the same Heavy font and shadow at font 72, left margin 90, right margin 200, bottom margin 460.
 - Keep these design coordinates for 1080p, 2K, and 4K sources. libass scales them to the actual frame.
 - Portrait's larger right and bottom margins avoid common right-side action controls and the lower interaction/caption region.
 

package/src/contracts.ts

@@ -53,9 +53,11 @@ export interface AssStyle {
 	fontSize: number;
 	primaryColour: string;
 	outlineColour: string;
+	shadowColour: string;
 	bold: boolean;
 	outline: number;
 	shadow: number;
+	blur: number;
 	alignment: number;
 	marginL: number;
 	marginR: number;

package/src/export.ts

@@ -5,17 +5,19 @@ import { resolveExistingWorkspaceFile, writeNewWorkspaceFile } from "./workspace
 export const DEFAULT_ASS_STYLE: AssStyle = {
 	playResX: 1920,
 	playResY: 1080,
-	fontName: "Noto Sans CJK SC",
+	fontName: "Source Han Sans SC Heavy",
 	fontSize: 80,
 	primaryColour: "&H00FFFFFF",
 	outlineColour: "&H00000000",
-	bold: true,
-	outline: 3,
-	shadow: 3,
+	shadowColour: "&H50000000",
+	bold: false,
+	outline: 0,
+	shadow: 4,
+	blur: 0.6,
 	alignment: 2,
 	marginL: 120,
 	marginR: 120,
-	marginV: 140,
+	marginV: 120,
 };
 
 export const PORTRAIT_ASS_STYLE: AssStyle = {
@@ -38,12 +40,13 @@ export function resolveAssStyle(layoutPreset: SubtitleLayoutPreset, overrides: P
 	const resolved = { ...base, ...overrides };
 	const limits = layoutPreset === "portrait"
 		? { font: [60, 90], marginL: [60, 140], marginR: [160, 260], marginV: [430, 500] }
-		: { font: [64, 96], marginL: [90, 180], marginR: [90, 180], marginV: [120, 170] };
+		: { font: [64, 96], marginL: [90, 180], marginR: [90, 180], marginV: [110, 150] };
 	const within = (value: number, [minimum, maximum]: number[]) => Number.isFinite(value) && value >= minimum! && value <= maximum!;
-	if (!resolved.bold || resolved.alignment !== 2 || !within(resolved.fontSize, limits.font)
+	if (resolved.fontName !== base.fontName || resolved.bold !== base.bold || resolved.alignment !== 2
+		|| resolved.outline !== 0 || !within(resolved.shadow, [3, 5]) || !within(resolved.blur, [0.4, 1])
+		|| resolved.shadowColour !== base.shadowColour || !within(resolved.fontSize, limits.font)
 		|| !within(resolved.marginL, limits.marginL) || !within(resolved.marginR, limits.marginR)
-		|| !within(resolved.marginV, limits.marginV) || !within(resolved.outline, [2, 5])
-		|| !within(resolved.shadow, [1, 5])) {
+		|| !within(resolved.marginV, limits.marginV)) {
 		throw new Error(`${layoutPreset} ASS style must preserve the readable safe-area preset`);
 	}
 	return resolved;
@@ -95,8 +98,9 @@ function assText(value: string): string {
 export function renderAss(cues: SubtitleCue[], style: Partial<AssStyle> = {}): string {
 	assertCues(cues);
 	const resolved = { ...DEFAULT_ASS_STYLE, ...style };
-	const header = `[Script Info]\nScriptType: v4.00+\nPlayResX: ${resolved.playResX}\nPlayResY: ${resolved.playResY}\nWrapStyle: 2\nScaledBorderAndShadow: yes\n\n[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\nStyle: Default,${resolved.fontName},${resolved.fontSize},${resolved.primaryColour},${resolved.primaryColour},${resolved.outlineColour},&H00000000,${resolved.bold ? -1 : 0},0,0,0,100,100,0,0,1,${resolved.outline},${resolved.shadow},${resolved.alignment},${resolved.marginL},${resolved.marginR},${resolved.marginV},1\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text`;
-	const events = cues.map((cue) => `Dialogue: 0,${assTime(cue.beginMs)},${assTime(cue.endMs)},Default,,0,0,0,,${assText(cue.text)}`);
+	const header = `[Script Info]\nScriptType: v4.00+\nPlayResX: ${resolved.playResX}\nPlayResY: ${resolved.playResY}\nWrapStyle: 2\nScaledBorderAndShadow: yes\n\n[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\nStyle: Default,${resolved.fontName},${resolved.fontSize},${resolved.primaryColour},${resolved.primaryColour},${resolved.outlineColour},${resolved.shadowColour},${resolved.bold ? -1 : 0},0,0,0,100,100,0,0,1,${resolved.outline},${resolved.shadow},${resolved.alignment},${resolved.marginL},${resolved.marginR},${resolved.marginV},1\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text`;
+	const blur = resolved.blur > 0 ? `{\\blur${resolved.blur}}` : "";
+	const events = cues.map((cue) => `Dialogue: 0,${assTime(cue.beginMs)},${assTime(cue.endMs)},Default,,0,0,0,,${blur}${assText(cue.text)}`);
 	return `${header}\n${events.join("\n")}\n`;
 }