@zenaigc/zenmcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +53 -2
  2. package/dist/src/acquire/download.js +152 -0
  3. package/dist/src/acquire/errors.js +8 -0
  4. package/dist/src/acquire/share.js +67 -0
  5. package/dist/src/acquire/social.js +98 -0
  6. package/dist/src/acquire/trim.js +95 -0
  7. package/dist/src/assets/files.js +29 -0
  8. package/dist/src/assets/generator.js +141 -0
  9. package/dist/src/assets/images.js +90 -0
  10. package/dist/src/assets/index.js +3 -0
  11. package/dist/src/assets/model-library.js +87 -0
  12. package/dist/src/assets/upload-cache.js +36 -0
  13. package/dist/src/contract/cloud-v1.js +334 -0
  14. package/dist/src/core/hash.js +18 -0
  15. package/dist/src/core/index.js +4 -0
  16. package/dist/src/core/job-store.js +251 -0
  17. package/dist/src/core/safety.js +43 -0
  18. package/dist/src/core/schema.js +295 -0
  19. package/dist/src/doctor.js +22 -0
  20. package/dist/src/effects/check.js +19 -0
  21. package/dist/src/effects/font.js +78 -0
  22. package/dist/src/effects/index.js +188 -0
  23. package/dist/src/engine/card.js +50 -0
  24. package/dist/src/engine/direct.js +493 -0
  25. package/dist/src/engine/generate.js +234 -0
  26. package/dist/src/engine/index.js +3 -0
  27. package/dist/src/engine/media.js +24 -0
  28. package/dist/src/engine/steps.js +444 -0
  29. package/dist/src/engine/storage.js +90 -0
  30. package/dist/src/gateway/attempt-store.js +110 -0
  31. package/dist/src/gateway/budget.js +39 -0
  32. package/dist/src/gateway/cloud-gateway.js +141 -0
  33. package/dist/src/gateway/config.js +10 -0
  34. package/dist/src/gateway/device-auth.js +53 -0
  35. package/dist/src/gateway/errors.js +105 -0
  36. package/dist/src/gateway/http.js +124 -0
  37. package/dist/src/gateway/index.js +8 -0
  38. package/dist/src/gateway/paid-runner.js +376 -0
  39. package/dist/src/gateway/types.js +42 -0
  40. package/dist/src/inspect/index.js +276 -0
  41. package/dist/src/inspect/media.js +43 -0
  42. package/dist/src/mcp/server.js +178 -0
  43. package/dist/src/models/wan3/index.js +173 -0
  44. package/dist/src/models/wan3/limits.js +25 -0
  45. package/dist/src/timeline/conform.js +255 -0
  46. package/dist/src/timeline/cuts.js +225 -0
  47. package/dist/src/timeline/diff.js +82 -0
  48. package/dist/src/timeline/errors.js +8 -0
  49. package/dist/src/timeline/ffmpeg.js +164 -0
  50. package/dist/src/timeline/index.js +6 -0
  51. package/dist/src/timeline/params.js +46 -0
  52. package/dist/src/timeline/probe.js +98 -0
  53. package/dist/src/timeline/types.js +1 -0
  54. package/dist/templates/pop-title/README.md +18 -0
  55. package/dist/templates/pop-title/index.html +102 -0
  56. package/dist/templates/pop-title/pop-title.js +97 -0
  57. package/dist/templates/pop-title/render.js +42 -0
  58. package/dist/templates/pop-title/size-1080/index.html +102 -0
  59. package/dist/templates/pop-title/variables.example.json +9 -0
  60. package/dist/templates/pop-title/vendor/FONT.md +10 -0
  61. package/dist/templates/pop-title/vendor/NotoSansCJKsc-Bold.otf +0 -0
  62. package/dist/templates/pop-title/vendor/OFL.txt +92 -0
  63. package/dist/templates/pop-title/vendor/gsap.min.js +11 -0
  64. package/package.json +33 -4
@@ -0,0 +1,173 @@
1
+ import { createHash } from "node:crypto";
2
+ import { jobSchema } from "../../core/schema.js";
3
+ import { WAN3_LIMITS as limits } from "./limits.js";
4
+ function mediaOf(plan) {
5
+ const ids = [...new Set(plan.job.storyboard.segments.flatMap(segment => plan.job.bindings.filter(binding => binding.segment === segment.id).map(binding => binding.asset)))];
6
+ const assets = ids.flatMap(id => {
7
+ const asset = plan.job.assets.find(item => item.id === id);
8
+ return asset ? [asset] : [];
9
+ });
10
+ let images = 0;
11
+ let videos = 0;
12
+ return [...assets.filter(asset => asset.role === "identity"),
13
+ ...assets.filter(asset => asset.role !== "identity" && asset.role !== "motion_ref"),
14
+ ...assets.filter(asset => asset.role === "motion_ref")]
15
+ .map(asset => ({
16
+ slot: asset.role === "motion_ref" ? `视频${++videos}` : `图${++images}`,
17
+ type: asset.role === "motion_ref" ? "reference_video" : "reference_image",
18
+ asset: asset.id,
19
+ role: asset.role,
20
+ sha256: asset.sha256,
21
+ }));
22
+ }
23
+ function seconds(plan, frame) {
24
+ const fps = plan.job.storyboard.source.fps;
25
+ return frame * fps.den / fps.num;
26
+ }
27
+ function stamp(value) {
28
+ return value.toFixed(6).replace(/\.?0+$/, "");
29
+ }
30
+ function bounds(plan, index) {
31
+ const segments = plan.job.storyboard.segments;
32
+ const segment = segments[index];
33
+ return [seconds(plan, segment.start_frame), index === segments.length - 1
34
+ ? plan.output.duration_seconds : seconds(plan, segment.end_frame)];
35
+ }
36
+ function productIds(plan, segment) {
37
+ return [...new Set(plan.job.bindings.filter(binding => binding.segment === segment &&
38
+ plan.job.assets.some(asset => asset.id === binding.asset && asset.role === "product"))
39
+ .map(binding => binding.asset))];
40
+ }
41
+ /**
42
+ * Structural plan checks only. Compilation checks audio=false on the generated
43
+ * prompt via lintPrompt: action + audio term blocks, adjacent negation suppresses
44
+ * that term, and other audio terms warn. This lexical heuristic has incomplete
45
+ * coverage; it does not understand natural-language intent.
46
+ */
47
+ export function lintPlan(plan) {
48
+ const issues = [];
49
+ const block = (code, message, segment) => issues.push({ level: "block", code, message, ...(segment ? { segment } : {}) });
50
+ if (!jobSchema.safeParse(plan.job).success) {
51
+ block("invalid_job", "任务不符合 Core Job 契约。");
52
+ return issues;
53
+ }
54
+ const duration = plan.output.duration_seconds;
55
+ if (!Number.isInteger(duration) || duration < limits.minDuration || duration > limits.maxDuration) {
56
+ block("invalid_duration", "本模板要求明确的 2–30 整数秒终点。");
57
+ }
58
+ if (!["480P", "720P", "1080P"].includes(plan.output.resolution) || !limits.allowedRatios.includes(plan.output.ratio) ||
59
+ (plan.output.seed !== undefined && !Number.isSafeInteger(plan.output.seed))) {
60
+ block("invalid_output", "输出分辨率、比例或 seed 无效。");
61
+ }
62
+ if (!Number.isFinite(plan.motion_ref_seconds) || plan.motion_ref_seconds < limits.minReferenceVideoSeconds || plan.motion_ref_seconds > limits.maxReferenceVideoSeconds) {
63
+ block("reference_video_duration", "参考视频必须为 1–15 秒。");
64
+ }
65
+ if (plan.motion_ref_seconds + duration > limits.maxMediaTotalSeconds) {
66
+ block("media_duration_total", "参考视频与输出视频的总时长不能超过 30 秒。");
67
+ }
68
+ const media = mediaOf(plan);
69
+ if (media.filter(item => item.type === "reference_image").length > limits.maxImages)
70
+ block("image_limit", "参考图不能超过 10 张。");
71
+ const videos = media.filter(item => item.type === "reference_video");
72
+ if (videos.length !== 1 || videos[0]?.asset !== plan.motion_ref)
73
+ block("motion_reference", "必须绑定且仅绑定指定的动作参考视频。");
74
+ for (const item of media) {
75
+ if (!plan.job.assets.find(asset => asset.id === item.asset)?.approved)
76
+ block("unapproved_asset", `素材 ${item.asset} 尚未确认。`);
77
+ }
78
+ plan.job.storyboard.segments.forEach((segment, index) => {
79
+ if (!["穿戴", "穿搭", "服装", "wearable", "clothing"].includes(segment.tags.product))
80
+ block("unsupported_task", "当前模板仅支持穿搭任务。", segment.id);
81
+ const bindings = plan.job.bindings.filter(binding => binding.segment === segment.id);
82
+ const products = productIds(plan, segment.id);
83
+ if (products.length !== 1 || !bindings.some(binding => binding.asset === plan.motion_ref) ||
84
+ !bindings.some(binding => plan.job.assets.some(asset => asset.id === binding.asset && asset.role === "identity"))) {
85
+ block("missing_segment_binding", "每段需恰好一个服装素材、身份参考和指定动作参考绑定。", segment.id);
86
+ }
87
+ for (const id of products) {
88
+ if (!plan.attributes[id]?.trim())
89
+ block("missing_attributes", `缺少素材 ${id} 的确认定稿属性。`, segment.id);
90
+ }
91
+ const [start, end] = bounds(plan, index);
92
+ if (Number.isFinite(duration) && duration >= limits.minDuration && !(end > start))
93
+ block("invalid_duration", "输出终点必须晚于最后镜头起点。", segment.id);
94
+ if (end > start && end - start < limits.recommendedMinShotSeconds)
95
+ issues.push({ level: "warn", code: "short_segment", segment: segment.id, message: "镜头短于官方建议的 2 秒,存在丢套风险。" });
96
+ });
97
+ return issues;
98
+ }
99
+ export function lintPrompt(prompt, plan) {
100
+ const issues = [];
101
+ if ([...prompt].length > limits.maxPromptCharacters)
102
+ issues.push({ level: "block", code: "prompt_too_long", message: "提示词超过 20,000 字符。" });
103
+ // Small lexical heuristic, not semantic understanding. No clause-wide exemptions.
104
+ const audio = /声音|聲音|音乐|音樂|配乐|配樂|音轨|音軌|音效|节拍|節拍|\bbeats?\b|\bmusic\b|\bsoundtrack\b|\bsound\b|\bbgm\b|\baudio\b/gi;
105
+ const action = /添加|加入|配上|使用|沿用|跟随|跟隨|保留|对齐|對齊|\b(?:add|use|match|follow|keep|align|generate)\b/i;
106
+ const adjacentNegation = /(?:不要|无|無|不新增|不添加|不加入|不使用|不沿用|不保留|禁止|\bno|\bwithout|\bdo not)\s*(?:背景)?\s*$/i;
107
+ let requested = false;
108
+ let mentioned = false;
109
+ for (const clause of prompt.split(/[。;;!!,,::\n]/)) {
110
+ for (const term of clause.matchAll(audio)) {
111
+ const before = clause.slice(0, term.index);
112
+ if (adjacentNegation.test(before))
113
+ continue;
114
+ const after = clause.slice(term.index + term[0].length);
115
+ // Also recognize the local reverse form, e.g. 节拍对齐.
116
+ if (action.test(before) || /^(?:对齐|對齊|跟随|跟隨)/.test(after))
117
+ requested = true;
118
+ else
119
+ mentioned = true;
120
+ }
121
+ }
122
+ if (requested)
123
+ issues.push({ level: "block", code: "audio_conflict", message: "audio=false 时检测到动作词与声音词组合的声音请求。" });
124
+ if (mentioned)
125
+ issues.push({ level: "warn", code: "audio_term", message: "检测到声音相关词但未匹配声音请求;词法启发式覆盖不完整,请人工核对。" });
126
+ const shots = prompt.split(/\n/).filter(line => /^(?:镜头\d+|\d+\.\d+\s*[–—-])/.test(line));
127
+ const lengths = shots.map(line => [...line.replace(/^.*?秒[)::]+/, "")].length);
128
+ lengths.forEach((length, index) => {
129
+ const others = lengths.filter((_, other) => other !== index).sort((a, b) => a - b);
130
+ const median = others[Math.floor(others.length / 2)];
131
+ if (median !== undefined && length >= limits.emphasisMinCharacters && length > median * limits.emphasisRatio) {
132
+ issues.push({ level: "warn", code: "experimental_single_item_emphasis", segment: plan.job.storyboard.segments[index]?.id, message: "EXPERIMENTAL:该镜头文字显著长于其他镜头,尚未证实会影响生成。" });
133
+ }
134
+ });
135
+ return issues;
136
+ }
137
+ export function compileWan3(plan) {
138
+ const issues = lintPlan(plan);
139
+ if (issues.some(issue => issue.level === "block"))
140
+ return { request: null, issues };
141
+ const media = mediaOf(plan);
142
+ const refs = media.map(item => {
143
+ if (item.role === "identity")
144
+ return `${item.slot}是身份参考,全片长相、发型和体型保持一致。`;
145
+ if (item.role === "motion_ref")
146
+ return `${item.slot}只用于动作、构图、镜头节奏和切点,不继承其人物外观、服装和鞋款。`;
147
+ if (item.role === "product")
148
+ return `${item.slot}定义对应镜头的穿搭:${plan.attributes[item.asset]}。`;
149
+ return `${item.slot}用于${item.role === "scene" ? "场景" : "细节"}参考。`;
150
+ });
151
+ const shots = plan.job.storyboard.segments.map((segment, index) => {
152
+ const [start, end] = bounds(plan, index);
153
+ const id = productIds(plan, segment.id)[0];
154
+ const slot = media.find(item => item.asset === id).slot;
155
+ const action = plan.actions?.[segment.id]?.trim();
156
+ return `镜头${index + 1}(${stamp(start)}–${stamp(end)}秒):${index ? "硬切," : ""}穿${slot},${plan.attributes[id]}。${action ? `${action}。` : ""}`;
157
+ });
158
+ const prompt = [
159
+ `创作一条${stamp(plan.output.duration_seconds)}秒、${plan.output.ratio}画幅、自然手机实拍质感的换装视频。同一位人物按镜头顺序展示穿搭。`,
160
+ `【参考素材】\n${refs.join("\n")}\n每个镜头只穿对应图中的服装和鞋子,不同图的服装和鞋子不要串位。`,
161
+ `【分镜】\n${shots.join("\n")}`,
162
+ "【负向清单】\n不要字幕、水印;不要换人;不要服装混搭;不要把上一套的袖子、鞋子带到下一套。",
163
+ ].join("\n\n");
164
+ issues.push(...lintPrompt(prompt, plan));
165
+ if (issues.some(issue => issue.level === "block"))
166
+ return { request: null, issues };
167
+ const params = { audio: false, prompt_extend: false, watermark: false,
168
+ resolution: plan.output.resolution, ratio: plan.output.ratio, duration: plan.output.duration_seconds };
169
+ if (plan.output.seed !== undefined)
170
+ params.seed = plan.output.seed;
171
+ return { request: { spec_version: limits.version, model: "wan3.0-video", prompt,
172
+ prompt_sha256: createHash("sha256").update(prompt).digest("hex"), params, media }, issues };
173
+ }
@@ -0,0 +1,25 @@
1
+ /** Versioned against the repository's Wan specification, read 2026-11-05.
2
+ * Official API: https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference
3
+ * Official prompt guide: https://help.aliyun.com/zh/model-studio/wan3-video-generation-prompt-guide
4
+ * Duration -1 or 2–30 is also recorded in the local spec from API validation.
5
+ * No live provider request is made by this module.
6
+ */
7
+ export const WAN3_LIMITS = {
8
+ version: "wan3-clothing-v1-2026-11-05",
9
+ maxImages: 10,
10
+ // doc-upstream: https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference
11
+ // Documented upstream limits; gateway pass-through is unverified.
12
+ allowedRatios: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"],
13
+ maxMediaTotalSeconds: 30,
14
+ minReferenceVideoSeconds: 1,
15
+ maxReferenceVideoSeconds: 15,
16
+ maxPromptCharacters: 20_000,
17
+ // The clothing template needs a known final timestamp; smart duration is rejected.
18
+ smartDuration: -1,
19
+ minDuration: 2,
20
+ maxDuration: 30,
21
+ recommendedMinShotSeconds: 2,
22
+ // EXPERIMENTAL: relative text length is only a warning, not a quality verdict.
23
+ emphasisRatio: 2,
24
+ emphasisMinCharacters: 40,
25
+ };
@@ -0,0 +1,255 @@
1
+ import { mkdir } from "node:fs/promises";
2
+ import { dirname } from "node:path";
3
+ import { TimelineError } from "./errors.js";
4
+ import { collectStderr, readRawFrames, spawnIo, waitClose, writeRawFrame } from "./ffmpeg.js";
5
+ import { timelineParams } from "./params.js";
6
+ import { probe } from "./probe.js";
7
+ /**
8
+ * Rebuild `input` so each target segment has exactly its target length.
9
+ *
10
+ * Output frame j inside a segment of n source frames and L target frames
11
+ * reads source frame floor(j * n / L) within that segment. A cut's `frame`
12
+ * is the first frame after the transition, and its `start` is the first
13
+ * high-difference frame. Frames in `[start, frame)` are skipped: they enter
14
+ * neither adjacent segment. Any cut that is not `found`, including
15
+ * `ambiguous`, is rejected.
16
+ *
17
+ * The file is silent libx264 yuv420p at the source rational frame rate.
18
+ */
19
+ export async function conform(input, plan, output, params = timelineParams) {
20
+ assertEncodeParams(params);
21
+ const meta = await probe(input);
22
+ const segments = planSegments(plan, meta.frames);
23
+ const picks = pickFrames(segments);
24
+ if (picks.length !== plan.target_frames) {
25
+ throw new TimelineError("conform_failed", `mapped ${picks.length} frames, target is ${plan.target_frames}`);
26
+ }
27
+ if (meta.width % 2 !== 0 || meta.height % 2 !== 0) {
28
+ throw new TimelineError("conform_failed", `yuv420p needs even dimensions, got ${meta.width}x${meta.height}`);
29
+ }
30
+ await mkdir(dirname(output), { recursive: true });
31
+ await rewrite(input, output, meta.width, meta.height, meta.fps.num, meta.fps.den, picks, params);
32
+ const written = await probe(output);
33
+ if (written.frames !== plan.target_frames) {
34
+ throw new TimelineError("conform_failed", `output has ${written.frames} frames, target is ${plan.target_frames}`);
35
+ }
36
+ if (written.fps.num !== meta.fps.num || written.fps.den !== meta.fps.den) {
37
+ throw new TimelineError("conform_failed", `output fps ${written.fps.num}/${written.fps.den} does not match ${meta.fps.num}/${meta.fps.den}`);
38
+ }
39
+ if (written.has_audio) {
40
+ throw new TimelineError("conform_failed", "output was not silent");
41
+ }
42
+ if (written.width !== meta.width || written.height !== meta.height) {
43
+ throw new TimelineError("conform_failed", `output size ${written.width}x${written.height} does not match ${meta.width}x${meta.height}`);
44
+ }
45
+ return {
46
+ frames: written.frames,
47
+ segments: segments.map((segment) => ({
48
+ source_frames: segment.sourceFrames,
49
+ target_frames: segment.targetFrames,
50
+ ratio: segment.sourceFrames / segment.targetFrames,
51
+ })),
52
+ };
53
+ }
54
+ function planSegments(plan, sourceFrames) {
55
+ if (!Number.isInteger(plan.target_frames) || plan.target_frames <= 0) {
56
+ throw new TimelineError("bad_params", "target_frames must be a positive integer");
57
+ }
58
+ if (plan.actual_cuts.length !== plan.target_cuts.length) {
59
+ throw new TimelineError("bad_params", `actual cuts (${plan.actual_cuts.length}) and target cuts (${plan.target_cuts.length}) differ`);
60
+ }
61
+ const actual = plan.actual_cuts.map((cut) => acceptedCut(cut, sourceFrames));
62
+ const target = acceptedTargetCuts(plan.target_cuts, plan.target_frames);
63
+ const sourceBounds = bounds(actual, sourceFrames);
64
+ const targetBounds = bounds(target.map((frame) => ({ start: frame, frame })), plan.target_frames);
65
+ return sourceBounds.map((source, index) => {
66
+ const goal = targetBounds[index];
67
+ if (goal === undefined) {
68
+ throw new TimelineError("conform_failed", "target segment is missing");
69
+ }
70
+ if (source.length <= 0 || goal.length <= 0) {
71
+ throw new TimelineError("conform_rejected", "a segment has no frames");
72
+ }
73
+ return {
74
+ sourceStart: source.start,
75
+ sourceFrames: source.length,
76
+ targetFrames: goal.length,
77
+ };
78
+ });
79
+ }
80
+ function acceptedCut(cut, sourceFrames) {
81
+ if (cut.status !== "found" || cut.frame === null || cut.start === null) {
82
+ throw new TimelineError("conform_rejected", `expected frame ${cut.expected} is ${cut.status}`);
83
+ }
84
+ if (!Number.isInteger(cut.frame) || cut.frame <= 0 || cut.frame >= sourceFrames) {
85
+ throw new TimelineError("conform_rejected", `found frame ${cut.frame} is outside the source`);
86
+ }
87
+ if (!Number.isInteger(cut.start) || cut.start <= 0 || cut.start > cut.frame) {
88
+ throw new TimelineError("conform_rejected", `cut start ${cut.start} is outside the transition`);
89
+ }
90
+ if (!Number.isInteger(cut.span) || cut.span !== cut.frame - cut.start + 1) {
91
+ throw new TimelineError("conform_rejected", `cut span ${cut.span} does not match start and frame`);
92
+ }
93
+ return { start: cut.start, frame: cut.frame };
94
+ }
95
+ function acceptedTargetCuts(cuts, targetFrames) {
96
+ let previous = 0;
97
+ const accepted = [];
98
+ for (const cut of cuts) {
99
+ if (!Number.isInteger(cut) || cut <= previous || cut >= targetFrames) {
100
+ throw new TimelineError("bad_params", `target cut ${cut} is outside the rising open range (0, ${targetFrames})`);
101
+ }
102
+ previous = cut;
103
+ accepted.push(cut);
104
+ }
105
+ return accepted;
106
+ }
107
+ function bounds(cuts, total) {
108
+ const segments = [];
109
+ let cursor = 0;
110
+ for (const cut of cuts) {
111
+ if (cut.start < cursor || cut.frame < cut.start || cut.frame > total) {
112
+ throw new TimelineError("conform_rejected", "cut frames overlap or leave the timeline");
113
+ }
114
+ // [cursor, start) is this shot. [start, frame) is the transition and
115
+ // is not mapped into either shot. The next shot begins at frame.
116
+ if (cut.start === cursor) {
117
+ throw new TimelineError("conform_rejected", "a segment has no frames");
118
+ }
119
+ segments.push({ start: cursor, length: cut.start - cursor });
120
+ cursor = cut.frame;
121
+ }
122
+ if (cursor >= total) {
123
+ throw new TimelineError("conform_rejected", "a segment has no frames");
124
+ }
125
+ segments.push({ start: cursor, length: total - cursor });
126
+ return segments;
127
+ }
128
+ function pickFrames(segments) {
129
+ const picks = [];
130
+ for (const segment of segments) {
131
+ for (let j = 0; j < segment.targetFrames; j += 1) {
132
+ const offset = Number((BigInt(j) * BigInt(segment.sourceFrames)) / BigInt(segment.targetFrames));
133
+ picks.push(segment.sourceStart + offset);
134
+ }
135
+ }
136
+ return picks;
137
+ }
138
+ async function rewrite(input, output, width, height, fpsNum, fpsDen, picks, params) {
139
+ const rate = `${fpsNum}/${fpsDen}`;
140
+ const decoder = spawnIo("ffmpeg", [
141
+ "-v",
142
+ "error",
143
+ "-i",
144
+ input,
145
+ "-map",
146
+ "0:v:0",
147
+ "-fps_mode",
148
+ "passthrough",
149
+ "-f",
150
+ "rawvideo",
151
+ "-pix_fmt",
152
+ "rgb24",
153
+ "pipe:1",
154
+ ], "pipe");
155
+ const encoder = spawnIo("ffmpeg", [
156
+ "-y",
157
+ "-v",
158
+ "error",
159
+ "-f",
160
+ "rawvideo",
161
+ "-pix_fmt",
162
+ "rgb24",
163
+ "-s",
164
+ `${width}x${height}`,
165
+ "-framerate",
166
+ rate,
167
+ "-i",
168
+ "pipe:0",
169
+ "-an",
170
+ "-c:v",
171
+ "libx264",
172
+ "-pix_fmt",
173
+ "yuv420p",
174
+ "-preset",
175
+ params.encodePreset,
176
+ "-crf",
177
+ String(params.encodeCrf),
178
+ output,
179
+ ], "ignore");
180
+ const decoderErr = collectStderr(decoder.stderr);
181
+ const encoderErr = collectStderr(encoder.stderr);
182
+ const decoderDone = waitClose(decoder);
183
+ const encoderDone = waitClose(encoder);
184
+ if (decoder.stdout === null || encoder.stdin === null) {
185
+ decoder.kill("SIGKILL");
186
+ encoder.kill("SIGKILL");
187
+ await Promise.allSettled([decoderDone, encoderDone]);
188
+ throw new TimelineError("ffmpeg_failed", "conform pipes were not created");
189
+ }
190
+ const stdin = encoder.stdin;
191
+ let pickIndex = 0;
192
+ let sourceIndex = 0;
193
+ const frameBytes = width * height * 3;
194
+ try {
195
+ await readRawFrames(decoder.stdout, frameBytes, async (frame) => {
196
+ while (pickIndex < picks.length && picks[pickIndex] === sourceIndex) {
197
+ await writeRawFrame(stdin, frame);
198
+ pickIndex += 1;
199
+ }
200
+ sourceIndex += 1;
201
+ const next = picks[pickIndex];
202
+ if (pickIndex >= picks.length) {
203
+ return "stop";
204
+ }
205
+ if (next === undefined || next < sourceIndex) {
206
+ throw new TimelineError("conform_failed", "frame map went backwards");
207
+ }
208
+ return "continue";
209
+ });
210
+ if (pickIndex !== picks.length) {
211
+ throw new TimelineError("conform_failed", `source ended at frame ${sourceIndex} before output frame ${pickIndex}`);
212
+ }
213
+ await endStdin(stdin);
214
+ }
215
+ catch (error) {
216
+ decoder.kill("SIGKILL");
217
+ encoder.kill("SIGKILL");
218
+ const settled = await Promise.allSettled([decoderDone, encoderDone]);
219
+ const spawnFailure = settled.find((item) => item.status === "rejected");
220
+ if (spawnFailure?.status === "rejected") {
221
+ throw spawnFailure.reason;
222
+ }
223
+ throw error;
224
+ }
225
+ decoder.stdout.destroy();
226
+ decoder.kill("SIGKILL");
227
+ const encoderCode = await encoderDone;
228
+ await decoderDone.catch(() => undefined);
229
+ if (encoderCode !== 0) {
230
+ const detail = encoderErr() || decoderErr();
231
+ throw new TimelineError("ffmpeg_failed", `conform encode failed (${encoderCode})${detail ? `\n${detail}` : ""}`);
232
+ }
233
+ }
234
+ function endStdin(stdin) {
235
+ return new Promise((resolve, reject) => {
236
+ stdin.end((error) => {
237
+ if (error) {
238
+ reject(error);
239
+ return;
240
+ }
241
+ resolve();
242
+ });
243
+ });
244
+ }
245
+ function assertEncodeParams(params) {
246
+ if (params.version !== timelineParams.version) {
247
+ throw new TimelineError("bad_params", `unsupported params version ${params.version}`);
248
+ }
249
+ if (!Number.isInteger(params.encodeCrf) || params.encodeCrf < 0 || params.encodeCrf > 51) {
250
+ throw new TimelineError("bad_params", `encodeCrf must be an integer from 0 to 51`);
251
+ }
252
+ if (!/^[a-z0-9]+$/.test(params.encodePreset)) {
253
+ throw new TimelineError("bad_params", `encodePreset is not a plain preset name`);
254
+ }
255
+ }
@@ -0,0 +1,225 @@
1
+ import { TimelineError } from "./errors.js";
2
+ import { timelineParams } from "./params.js";
3
+ const NOT_FOUND = {
4
+ start: null,
5
+ frame: null,
6
+ span: 0,
7
+ score: 0,
8
+ status: "not_found",
9
+ };
10
+ /**
11
+ * Unknown hard cuts from the diff series.
12
+ *
13
+ * A sample is hot when it clears median + madK * MAD by more than gateSlack
14
+ * gray levels. MAD is the raw median absolute deviation. Adjacent hot
15
+ * samples are one run.
16
+ * `start` is the frame of the first hot difference (diff index i maps to
17
+ * frame i + 1). `frame` is the first frame after the run. `span` is the
18
+ * number of hot samples. A run longer than `maxSpan` is gradual motion and
19
+ * is dropped. `score` is the maximum diff inside the run.
20
+ */
21
+ export function detectCuts(diffs, params = timelineParams) {
22
+ assertDetectionParams(params);
23
+ if (diffs.length === 0) {
24
+ return [];
25
+ }
26
+ const threshold = adaptiveThreshold(diffs, params.madK) + params.gateSlack;
27
+ const cuts = [];
28
+ let index = 0;
29
+ while (index < diffs.length) {
30
+ const value = diffs[index] ?? 0;
31
+ if (!(value > threshold)) {
32
+ index += 1;
33
+ continue;
34
+ }
35
+ const first = index;
36
+ let score = value;
37
+ while (index + 1 < diffs.length && (diffs[index + 1] ?? 0) > threshold) {
38
+ index += 1;
39
+ score = Math.max(score, diffs[index] ?? 0);
40
+ }
41
+ const span = index - first + 1;
42
+ if (span <= params.maxSpan) {
43
+ cuts.push({
44
+ start: first + 1,
45
+ frame: index + 1,
46
+ span,
47
+ score,
48
+ });
49
+ }
50
+ index += 1;
51
+ }
52
+ return cuts;
53
+ }
54
+ /**
55
+ * Place each expected cut on a peak inside its own window.
56
+ *
57
+ * This does not use the global median gate. The peak must stand out from
58
+ * the median of the other samples in the window by both a ratio and a
59
+ * difference. Adjacent samples that stay at least `locateShoulderRatio` of
60
+ * the peak form one transition. No outstanding peak yields `not_found`.
61
+ * A second local peak within `ambiguityRatio` yields `ambiguous`.
62
+ * The window must be <= half the shortest segment. Assigned resume frames
63
+ * stay strictly increasing.
64
+ */
65
+ export function locateCuts(diffs, expected, params = timelineParams) {
66
+ assertDetectionParams(params);
67
+ const frames = diffs.length + 1;
68
+ assertExpected(expected, frames);
69
+ if (expected.length === 0) {
70
+ return [];
71
+ }
72
+ const shortest = shortestSegment(expected, frames);
73
+ const half = Math.floor(shortest / 2);
74
+ if (!Number.isInteger(params.locateWindow) || params.locateWindow < 0) {
75
+ throw new TimelineError("bad_params", "locate window must be a non-negative integer");
76
+ }
77
+ if (params.locateWindow > half) {
78
+ throw new TimelineError("bad_params", `locate window ${params.locateWindow} exceeds half the shortest segment (${half})`);
79
+ }
80
+ const used = new Set();
81
+ let previous = -1;
82
+ return expected.map((cut) => locateOne(diffs, cut, params, used, () => previous, (frame) => {
83
+ previous = frame;
84
+ }));
85
+ }
86
+ function locateOne(diffs, expected, params, used, previous, commit) {
87
+ const window = params.locateWindow;
88
+ const lo = Math.max(0, expected - window - 1);
89
+ const hi = Math.min(diffs.length - 1, expected + window - 1);
90
+ if (lo > hi) {
91
+ return { expected, ...NOT_FOUND };
92
+ }
93
+ let peakIndex = lo;
94
+ for (let index = lo + 1; index <= hi; index += 1) {
95
+ if ((diffs[index] ?? 0) > (diffs[peakIndex] ?? 0)) {
96
+ peakIndex = index;
97
+ }
98
+ }
99
+ const peak = diffs[peakIndex] ?? 0;
100
+ if (!(peak > 0)) {
101
+ return { expected, ...NOT_FOUND };
102
+ }
103
+ const shoulder = peak * params.locateShoulderRatio;
104
+ let first = peakIndex;
105
+ let last = peakIndex;
106
+ while (first > lo && (diffs[first - 1] ?? 0) >= shoulder) {
107
+ first -= 1;
108
+ }
109
+ while (last < hi && (diffs[last + 1] ?? 0) >= shoulder) {
110
+ last += 1;
111
+ }
112
+ const span = last - first + 1;
113
+ const start = first + 1;
114
+ const frame = last + 1;
115
+ if (span > params.maxSpan || start < expected - window || start > expected + window) {
116
+ return { expected, ...NOT_FOUND };
117
+ }
118
+ if (start <= previous() || frame <= previous() || used.has(start)) {
119
+ return { expected, ...NOT_FOUND };
120
+ }
121
+ const rest = [];
122
+ for (let index = lo; index <= hi; index += 1) {
123
+ if (index < first || index > last) {
124
+ rest.push(diffs[index] ?? 0);
125
+ }
126
+ }
127
+ const background = rest.length === 0 ? 0 : median(Float64Array.from(rest));
128
+ const prominent = peak >= params.locateProminenceRatio * background &&
129
+ peak - background >= params.locateProminenceDelta;
130
+ if (!prominent) {
131
+ return { expected, ...NOT_FOUND };
132
+ }
133
+ let second = 0;
134
+ for (let index = lo; index <= hi; index += 1) {
135
+ if (index >= first && index <= last) {
136
+ continue;
137
+ }
138
+ const value = diffs[index] ?? 0;
139
+ const left = index > lo ? (diffs[index - 1] ?? 0) : Number.NEGATIVE_INFINITY;
140
+ const right = index < hi ? (diffs[index + 1] ?? 0) : Number.NEGATIVE_INFINITY;
141
+ if (value >= left && value >= right && value > second) {
142
+ second = value;
143
+ }
144
+ }
145
+ if (second > 0 && peak < params.ambiguityRatio * second) {
146
+ return {
147
+ expected,
148
+ start: null,
149
+ frame: null,
150
+ span: 0,
151
+ score: peak,
152
+ status: "ambiguous",
153
+ };
154
+ }
155
+ used.add(start);
156
+ commit(frame);
157
+ return { expected, start, frame, span, score: peak, status: "found" };
158
+ }
159
+ function assertDetectionParams(params) {
160
+ if (params.version !== timelineParams.version) {
161
+ throw new TimelineError("bad_params", `unsupported params version ${params.version}`);
162
+ }
163
+ if (!Number.isFinite(params.madK) || params.madK <= 0) {
164
+ throw new TimelineError("bad_params", "madK must be a positive finite number");
165
+ }
166
+ if (!Number.isFinite(params.gateSlack) || params.gateSlack < 0) {
167
+ throw new TimelineError("bad_params", "gateSlack must be a finite number >= 0");
168
+ }
169
+ if (!Number.isInteger(params.maxSpan) || params.maxSpan < 1) {
170
+ throw new TimelineError("bad_params", "maxSpan must be a positive integer");
171
+ }
172
+ if (!Number.isFinite(params.ambiguityRatio) || params.ambiguityRatio < 1) {
173
+ throw new TimelineError("bad_params", "ambiguityRatio must be a finite number >= 1");
174
+ }
175
+ if (!Number.isFinite(params.locateProminenceRatio) || params.locateProminenceRatio < 1) {
176
+ throw new TimelineError("bad_params", "locateProminenceRatio must be a finite number >= 1");
177
+ }
178
+ if (!Number.isFinite(params.locateProminenceDelta) || params.locateProminenceDelta < 0) {
179
+ throw new TimelineError("bad_params", "locateProminenceDelta must be a finite number >= 0");
180
+ }
181
+ if (!Number.isFinite(params.locateShoulderRatio) ||
182
+ params.locateShoulderRatio <= 0 ||
183
+ params.locateShoulderRatio > 1) {
184
+ throw new TimelineError("bad_params", "locateShoulderRatio must be in (0, 1]");
185
+ }
186
+ }
187
+ function adaptiveThreshold(diffs, madK) {
188
+ const middle = median(diffs);
189
+ const deviation = medianAbsDev(diffs, middle);
190
+ return middle + madK * deviation;
191
+ }
192
+ function median(values) {
193
+ const copy = Float64Array.from(values);
194
+ copy.sort();
195
+ const mid = Math.floor(copy.length / 2);
196
+ if (copy.length % 2 === 1) {
197
+ return copy[mid] ?? 0;
198
+ }
199
+ return ((copy[mid - 1] ?? 0) + (copy[mid] ?? 0)) / 2;
200
+ }
201
+ function medianAbsDev(values, middle) {
202
+ const deviations = new Float64Array(values.length);
203
+ for (let i = 0; i < values.length; i += 1) {
204
+ deviations[i] = Math.abs((values[i] ?? 0) - middle);
205
+ }
206
+ return median(deviations);
207
+ }
208
+ function assertExpected(expected, frames) {
209
+ let previous = 0;
210
+ for (const cut of expected) {
211
+ if (!Number.isInteger(cut) || cut <= previous || cut >= frames) {
212
+ throw new TimelineError("bad_params", `expected cut ${cut} is outside the rising open range (0, ${frames})`);
213
+ }
214
+ previous = cut;
215
+ }
216
+ }
217
+ function shortestSegment(expected, frames) {
218
+ let previous = 0;
219
+ let shortest = frames;
220
+ for (const cut of expected) {
221
+ shortest = Math.min(shortest, cut - previous);
222
+ previous = cut;
223
+ }
224
+ return Math.min(shortest, frames - previous);
225
+ }