@openbone/mcp 0.0.0-stage → 0.3.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.
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Pixel operations for preparing art (process_image): key out a flat background, cut a layer out by comparing two
3
+ * versions of a picture, trim, crop, feather edges, flip. They work on straight-alpha RGBA buffers; resizing and file
4
+ * I/O happen in the tool with the canvas.
5
+ */
6
+ export interface Pixels {
7
+ data: Uint8ClampedArray;
8
+ width: number;
9
+ height: number;
10
+ }
11
+ /** Where the result sits in the input image (after crops and trims), in input pixels. */
12
+ export interface Box {
13
+ x: number;
14
+ y: number;
15
+ width: number;
16
+ height: number;
17
+ }
18
+ export declare function parseHex(hex: string): [number, number, number];
19
+ /** Median colour of the image border (all edges, or only the top rows). */
20
+ export declare function borderColor(p: Pixels, edges?: "all" | "top", depth?: number): [number, number, number];
21
+ export interface KeyOptions {
22
+ /** Background colour; default: the border median. */
23
+ color?: string;
24
+ /** Where to sample the default colour: "all" edges or only the "top" (art that touches the other edges, like grass). */
25
+ sampleFrom?: "all" | "top";
26
+ /** Colour distance (0–441) still counted as background. */
27
+ tolerance?: number;
28
+ /** Distance over which pixels fade from background to opaque (soft, anti-aliased edges). */
29
+ softness?: number;
30
+ /** Pixels at least this bright (0–255 average) stay opaque, e.g. white flowers on a light grey background. */
31
+ keepBrighterThan?: number;
32
+ /**
33
+ * Remove the key colour's cast from what is left (green/blue screen spill on edges): the key's dominant channel is
34
+ * limited to the average of the other two (the usual green-screen despill). Default: on when the key colour is strongly coloured (green, blue, magenta…).
35
+ */
36
+ despill?: boolean;
37
+ }
38
+ /**
39
+ * Remove a flat background colour everywhere in the image (also in closed gaps), with soft edges, and take the
40
+ * background tint out of the semi-transparent edge pixels so no fringe of it is left.
41
+ */
42
+ export declare function keyColor(p: Pixels, o?: KeyOptions): {
43
+ color: [number, number, number];
44
+ };
45
+ /** Bounding box of pixels with alpha above `threshold`, grown by `padding`. Null when nothing is visible. */
46
+ export declare function alphaBounds(p: Pixels, threshold?: number, padding?: number): Box | null;
47
+ export declare function crop(p: Pixels, b: Box): Pixels;
48
+ /** Fade alpha to 0 over the given number of pixels at each side (so tiled copies overlap without seams). */
49
+ export declare function featherEdges(p: Pixels, o: {
50
+ left?: number;
51
+ right?: number;
52
+ top?: number;
53
+ bottom?: number;
54
+ }): void;
55
+ export declare function flip(p: Pixels, horizontal: boolean, vertical: boolean): Pixels;
56
+ /** Keep only the largest connected group of visible pixels (alpha > threshold), clearing stray specks. */
57
+ export declare function keepLargest(p: Pixels, threshold?: number): void;
58
+ export interface DifferenceOptions {
59
+ /** Channel difference (0–1) below which pixels count as unchanged. */
60
+ threshold?: number;
61
+ /** Range (0–1) over which alpha ramps up above the threshold. */
62
+ softness?: number;
63
+ /** Only look inside this box of the image (pixels outside become transparent). */
64
+ region?: Box;
65
+ /** Fade the matte out between these rows (e.g. where a tree meets repainted grass): {from, to}, alpha 1 at from, 0 at to. */
66
+ fadeRows?: {
67
+ from: number;
68
+ to: number;
69
+ };
70
+ /** Keep only the largest cut-out piece (default true). */
71
+ keepLargest?: boolean;
72
+ }
73
+ /**
74
+ * Cut out what differs between `p` and `other` (the same picture with the object removed, e.g. an inpainted "clean
75
+ * plate"): `p` keeps its colours, alpha becomes how much the two differ. A median and a small dilation clean the matte.
76
+ */
77
+ export declare function differenceMatte(p: Pixels, other: Pixels, o?: DifferenceOptions): void;
@@ -0,0 +1,235 @@
1
+ /**
2
+ * Pixel operations for preparing art (process_image): key out a flat background, cut a layer out by comparing two
3
+ * versions of a picture, trim, crop, feather edges, flip. They work on straight-alpha RGBA buffers; resizing and file
4
+ * I/O happen in the tool with the canvas.
5
+ */
6
+ const smooth = (t) => {
7
+ const c = Math.min(1, Math.max(0, t));
8
+ return c * c * (3 - 2 * c);
9
+ };
10
+ export function parseHex(hex) {
11
+ const h = hex.replace("#", "");
12
+ if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(h))
13
+ throw new Error(`Not a colour: ${hex}`);
14
+ return [Number.parseInt(h.slice(0, 2), 16), Number.parseInt(h.slice(2, 4), 16), Number.parseInt(h.slice(4, 6), 16)];
15
+ }
16
+ /** Median colour of the image border (all edges, or only the top rows). */
17
+ export function borderColor(p, edges = "all", depth = 4) {
18
+ const rs = [];
19
+ const gs = [];
20
+ const bs = [];
21
+ const take = (x, y) => {
22
+ const i = (y * p.width + x) * 4;
23
+ if (p.data[i + 3] < 128)
24
+ return;
25
+ rs.push(p.data[i]);
26
+ gs.push(p.data[i + 1]);
27
+ bs.push(p.data[i + 2]);
28
+ };
29
+ for (let y = 0; y < Math.min(depth, p.height); y++)
30
+ for (let x = 0; x < p.width; x += 2)
31
+ take(x, y);
32
+ if (edges === "all") {
33
+ for (let y = Math.max(0, p.height - depth); y < p.height; y++)
34
+ for (let x = 0; x < p.width; x += 2)
35
+ take(x, y);
36
+ for (let y = 0; y < p.height; y += 2)
37
+ for (let d = 0; d < depth; d++) {
38
+ take(d, y);
39
+ take(p.width - 1 - d, y);
40
+ }
41
+ }
42
+ if (!rs.length)
43
+ throw new Error("The border has no opaque pixels to take a background colour from: give `color`");
44
+ const med = (a) => a.sort((x, y) => x - y)[a.length >> 1];
45
+ return [med(rs), med(gs), med(bs)];
46
+ }
47
+ /**
48
+ * Remove a flat background colour everywhere in the image (also in closed gaps), with soft edges, and take the
49
+ * background tint out of the semi-transparent edge pixels so no fringe of it is left.
50
+ */
51
+ export function keyColor(p, o = {}) {
52
+ const bg = o.color ? parseHex(o.color) : borderColor(p, o.sampleFrom ?? "all");
53
+ const tol = o.tolerance ?? 18;
54
+ const soft = Math.max(1, o.softness ?? 34);
55
+ const d = p.data;
56
+ for (let i = 0; i < d.length; i += 4) {
57
+ const dist = Math.hypot(d[i] - bg[0], d[i + 1] - bg[1], d[i + 2] - bg[2]);
58
+ let a = smooth((dist - tol) / soft);
59
+ if (o.keepBrighterThan !== undefined)
60
+ a = Math.max(a, smooth(((d[i] + d[i + 1] + d[i + 2]) / 3 - o.keepBrighterThan) / 20));
61
+ const a0 = d[i + 3] / 255;
62
+ if (a > 0 && a < 1)
63
+ for (let c = 0; c < 3; c++)
64
+ d[i + c] = Math.min(255, Math.max(0, (d[i + c] - (1 - a) * bg[c]) / a));
65
+ d[i + 3] = Math.round(a * a0 * 255);
66
+ }
67
+ const k = bg.indexOf(Math.max(...bg));
68
+ const others = [0, 1, 2].filter((c) => c !== k);
69
+ const saturated = bg[k] - Math.max(bg[others[0]], bg[others[1]]) > 80;
70
+ if (o.despill ?? saturated)
71
+ for (let i = 0; i < d.length; i += 4)
72
+ if (d[i + 3] > 0)
73
+ d[i + k] = Math.min(d[i + k], (d[i + others[0]] + d[i + others[1]]) / 2);
74
+ return { color: bg };
75
+ }
76
+ /** Bounding box of pixels with alpha above `threshold`, grown by `padding`. Null when nothing is visible. */
77
+ export function alphaBounds(p, threshold = 8, padding = 0) {
78
+ let x0 = p.width;
79
+ let y0 = p.height;
80
+ let x1 = -1;
81
+ let y1 = -1;
82
+ for (let y = 0; y < p.height; y++)
83
+ for (let x = 0; x < p.width; x++)
84
+ if (p.data[(y * p.width + x) * 4 + 3] > threshold) {
85
+ if (x < x0)
86
+ x0 = x;
87
+ if (x > x1)
88
+ x1 = x;
89
+ if (y < y0)
90
+ y0 = y;
91
+ if (y > y1)
92
+ y1 = y;
93
+ }
94
+ if (x1 < 0)
95
+ return null;
96
+ x0 = Math.max(0, x0 - padding);
97
+ y0 = Math.max(0, y0 - padding);
98
+ x1 = Math.min(p.width - 1, x1 + padding);
99
+ y1 = Math.min(p.height - 1, y1 + padding);
100
+ return { x: x0, y: y0, width: x1 - x0 + 1, height: y1 - y0 + 1 };
101
+ }
102
+ export function crop(p, b) {
103
+ const x = Math.max(0, Math.round(b.x));
104
+ const y = Math.max(0, Math.round(b.y));
105
+ const w = Math.max(1, Math.min(p.width - x, Math.round(b.width)));
106
+ const h = Math.max(1, Math.min(p.height - y, Math.round(b.height)));
107
+ const out = new Uint8ClampedArray(w * h * 4);
108
+ for (let r = 0; r < h; r++)
109
+ out.set(p.data.subarray(((y + r) * p.width + x) * 4, ((y + r) * p.width + x + w) * 4), r * w * 4);
110
+ return { data: out, width: w, height: h };
111
+ }
112
+ /** Fade alpha to 0 over the given number of pixels at each side (so tiled copies overlap without seams). */
113
+ export function featherEdges(p, o) {
114
+ for (let y = 0; y < p.height; y++)
115
+ for (let x = 0; x < p.width; x++) {
116
+ let f = 1;
117
+ if (o.left)
118
+ f = Math.min(f, smooth(x / o.left));
119
+ if (o.right)
120
+ f = Math.min(f, smooth((p.width - 1 - x) / o.right));
121
+ if (o.top)
122
+ f = Math.min(f, smooth(y / o.top));
123
+ if (o.bottom)
124
+ f = Math.min(f, smooth((p.height - 1 - y) / o.bottom));
125
+ if (f < 1)
126
+ p.data[(y * p.width + x) * 4 + 3] *= f;
127
+ }
128
+ }
129
+ export function flip(p, horizontal, vertical) {
130
+ const out = new Uint8ClampedArray(p.data.length);
131
+ for (let y = 0; y < p.height; y++)
132
+ for (let x = 0; x < p.width; x++) {
133
+ const sx = horizontal ? p.width - 1 - x : x;
134
+ const sy = vertical ? p.height - 1 - y : y;
135
+ out.set(p.data.subarray((sy * p.width + sx) * 4, (sy * p.width + sx) * 4 + 4), (y * p.width + x) * 4);
136
+ }
137
+ return { data: out, width: p.width, height: p.height };
138
+ }
139
+ /** Keep only the largest connected group of visible pixels (alpha > threshold), clearing stray specks. */
140
+ export function keepLargest(p, threshold = 12) {
141
+ const n = p.width * p.height;
142
+ const label = new Int32Array(n);
143
+ const stack = new Int32Array(n);
144
+ let best = 0;
145
+ let bestSize = 0;
146
+ let next = 0;
147
+ for (let s = 0; s < n; s++) {
148
+ if (label[s] || p.data[s * 4 + 3] <= threshold)
149
+ continue;
150
+ next++;
151
+ let size = 0;
152
+ let top = 0;
153
+ stack[top++] = s;
154
+ label[s] = next;
155
+ while (top) {
156
+ const i = stack[--top];
157
+ size++;
158
+ const x = i % p.width;
159
+ const nb = [x > 0 ? i - 1 : -1, x < p.width - 1 ? i + 1 : -1, i - p.width, i + p.width];
160
+ for (const j of nb)
161
+ if (j >= 0 && j < n && !label[j] && p.data[j * 4 + 3] > threshold) {
162
+ label[j] = next;
163
+ stack[top++] = j;
164
+ }
165
+ }
166
+ if (size > bestSize) {
167
+ bestSize = size;
168
+ best = next;
169
+ }
170
+ }
171
+ // Keep the faint edge pixels that touch the kept group (they carry the anti-aliasing).
172
+ for (let i = 0; i < n; i++) {
173
+ if (label[i] === best)
174
+ continue;
175
+ if (label[i] === 0 && p.data[i * 4 + 3] > 0) {
176
+ const x = i % p.width;
177
+ const near = [x > 0 ? i - 1 : -1, x < p.width - 1 ? i + 1 : -1, i - p.width, i + p.width].some((j) => j >= 0 && j < n && label[j] === best);
178
+ if (near)
179
+ continue;
180
+ }
181
+ p.data[i * 4 + 3] = 0;
182
+ }
183
+ }
184
+ /**
185
+ * Cut out what differs between `p` and `other` (the same picture with the object removed, e.g. an inpainted "clean
186
+ * plate"): `p` keeps its colours, alpha becomes how much the two differ. A median and a small dilation clean the matte.
187
+ */
188
+ export function differenceMatte(p, other, o = {}) {
189
+ if (other.width !== p.width || other.height !== p.height)
190
+ throw new Error(`The other image is ${other.width}×${other.height}; it must be ${p.width}×${p.height} (resize it first)`);
191
+ const w = p.width;
192
+ const h = p.height;
193
+ const diff = new Float32Array(w * h);
194
+ for (let i = 0; i < w * h; i++) {
195
+ const a = i * 4;
196
+ diff[i] = Math.max(Math.abs(p.data[a] - other.data[a]), Math.abs(p.data[a + 1] - other.data[a + 1]), Math.abs(p.data[a + 2] - other.data[a + 2])) / 255;
197
+ }
198
+ // 5×5 median (drops repaint noise), then 3×3 max (closes thin gaps), then a light blur.
199
+ const med = filter(diff, w, h, 2, (v) => v.sort((x, y) => x - y)[v.length >> 1]);
200
+ const dil = filter(med, w, h, 1, (v) => Math.max(...v));
201
+ const blur = filter(dil, w, h, 1, (v) => v.reduce((s, x) => s + x, 0) / v.length);
202
+ const th = o.threshold ?? 0.06;
203
+ const soft = o.softness ?? 0.09;
204
+ const r = o.region;
205
+ for (let y = 0; y < h; y++)
206
+ for (let x = 0; x < w; x++) {
207
+ const i = y * w + x;
208
+ let a = smooth((blur[i] - th) / soft);
209
+ if (r && (x < r.x || y < r.y || x >= r.x + r.width || y >= r.y + r.height))
210
+ a = 0;
211
+ if (o.fadeRows) {
212
+ const { from, to } = o.fadeRows;
213
+ a *= to === from ? (y < from ? 1 : 0) : smooth((to - y) / (to - from));
214
+ }
215
+ p.data[i * 4 + 3] = Math.round(a * p.data[i * 4 + 3]);
216
+ }
217
+ if (o.keepLargest ?? true)
218
+ keepLargest(p);
219
+ }
220
+ function filter(src, w, h, r, f) {
221
+ const out = new Float32Array(src.length);
222
+ const v = [];
223
+ for (let y = 0; y < h; y++)
224
+ for (let x = 0; x < w; x++) {
225
+ v.length = 0;
226
+ for (let dy = -r; dy <= r; dy++)
227
+ for (let dx = -r; dx <= r; dx++) {
228
+ const yy = Math.min(h - 1, Math.max(0, y + dy));
229
+ const xx = Math.min(w - 1, Math.max(0, x + dx));
230
+ v.push(src[yy * w + xx]);
231
+ }
232
+ out[y * w + x] = f(v);
233
+ }
234
+ return out;
235
+ }
@@ -0,0 +1,8 @@
1
+ export { createServer, snake } from "./server.js";
2
+ export { ProjectSession } from "./session.js";
3
+ export { startBridge } from "./bridge.js";
4
+ export { renderPng, renderGif, pose } from "./render.js";
5
+ export { GUIDE } from "./guide.js";
6
+ export { packAtlas } from "./render.js";
7
+ export { EXPORT_FORMATS, type ExportFormat, type ExportRequest, type ExportResult, type AtlasExportOptions, exportFile, exportBaseName } from "./export.js";
8
+ export { type AtlasSettings, type AtlasScaleVariant, atlasBuildOptions, parseScaleVariants } from "@openbone/render-canvas";
package/dist/index.js ADDED
@@ -0,0 +1,8 @@
1
+ export { createServer, snake } from "./server.js";
2
+ export { ProjectSession } from "./session.js";
3
+ export { startBridge } from "./bridge.js";
4
+ export { renderPng, renderGif, pose } from "./render.js";
5
+ export { GUIDE } from "./guide.js";
6
+ export { packAtlas } from "./render.js";
7
+ export { EXPORT_FORMATS, exportFile, exportBaseName } from "./export.js";
8
+ export { atlasBuildOptions, parseScaleVariants } from "@openbone/render-canvas";
@@ -0,0 +1,7 @@
1
+ export declare function isLocalOrigin(origin: string | undefined): boolean;
2
+ export declare function isLocalHost(host: string | undefined): boolean;
3
+ /** Both checks, for an incoming request's headers. */
4
+ export declare function isLocalRequest(headers: {
5
+ origin?: string;
6
+ host?: string;
7
+ }): boolean;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Who may talk to the local servers (the editor bridge and MCP over HTTP).
3
+ *
4
+ * Both listen on 127.0.0.1, so other machines can't reach them, but any web page open in a browser on this machine
5
+ * can still try: a page can open a WebSocket to ws://127.0.0.1:7717, and with DNS rebinding (a site whose name starts
6
+ * resolving to 127.0.0.1) it can send same-origin HTTP requests. Browsers always say where a request comes from
7
+ * (Origin) and which name it was sent to (Host), so:
8
+ * - Origin must be absent (CLI tools, MCP clients, scripts: not a browser page) or a local page: the editor's dev
9
+ * server on localhost/127.0.0.1/[::1] (any port) or the desktop app (tauri://localhost, http(s)://tauri.localhost).
10
+ * - Host must be a loopback name, which a DNS-rebinding site's name never is.
11
+ */
12
+ const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
13
+ export function isLocalOrigin(origin) {
14
+ if (origin === undefined || origin === "")
15
+ return true;
16
+ let url;
17
+ try {
18
+ url = new URL(origin); // "null" (file://, sandboxed iframes) doesn't parse and is refused
19
+ }
20
+ catch {
21
+ return false;
22
+ }
23
+ if (url.protocol === "tauri:")
24
+ return url.hostname === "localhost";
25
+ if (url.protocol !== "http:" && url.protocol !== "https:")
26
+ return false;
27
+ return LOCAL_HOSTNAMES.has(url.hostname) || url.hostname === "tauri.localhost";
28
+ }
29
+ export function isLocalHost(host) {
30
+ if (!host)
31
+ return false;
32
+ const name = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0];
33
+ return LOCAL_HOSTNAMES.has(name.toLowerCase());
34
+ }
35
+ /** Both checks, for an incoming request's headers. */
36
+ export function isLocalRequest(headers) {
37
+ return isLocalOrigin(headers.origin) && isLocalHost(headers.host);
38
+ }
@@ -0,0 +1,27 @@
1
+ import { type DecodedAudio } from "@openbone/export";
2
+ /** The ffmpeg executable, or null when there is none. */
3
+ export declare function findFfmpeg(): string | null;
4
+ /**
5
+ * Decode an audio file: WAV in-process, anything else through ffmpeg (stereo float at `sampleRate`). Null when it
6
+ * can't be decoded (no ffmpeg, or a broken file).
7
+ */
8
+ export declare function decodeAudio(bytes: Uint8Array, sampleRate?: number): Promise<DecodedAudio | null>;
9
+ export interface VideoFrame {
10
+ width: number;
11
+ height: number;
12
+ /** RGBA, opaque (already flattened onto the background). */
13
+ data: Uint8ClampedArray | Uint8Array;
14
+ }
15
+ /**
16
+ * Encode frames (and an optional sound track) as MP4 (H.264 + AAC, yuv420p, plays everywhere) or WebM (VP9 + Opus)
17
+ * with ffmpeg. `quality` 0..1 maps to the encoder's constant-quality setting.
18
+ */
19
+ export declare function encodeVideoFfmpeg(frames: VideoFrame[], o: {
20
+ format: "mp4" | "webm";
21
+ fps: number;
22
+ quality?: number;
23
+ audio?: {
24
+ sampleRate: number;
25
+ channels: Float32Array[];
26
+ } | null;
27
+ }): Promise<Uint8Array>;
package/dist/media.js ADDED
@@ -0,0 +1,124 @@
1
+ import { spawn, spawnSync } from "node:child_process";
2
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import path from "node:path";
5
+ import { decodeWav, encodeWav } from "@openbone/export";
6
+ /**
7
+ * Sound decoding and MP4 / WebM encoding for exports in Node. WAV is decoded here; other audio (MP3, OGG, FLAC…) and
8
+ * the MP4 (H.264 + AAC) and WebM (VP9 + Opus) encoders come from an `ffmpeg` found on the PATH (or OPENBONE_FFMPEG).
9
+ * ffmpeg is used as an external program, not bundled, so this package keeps its permissive licence; without it, WAV
10
+ * sound still works and MP4 / WebM say how to get them (the editor makes them with the browser's encoders).
11
+ */
12
+ let ffmpegPath;
13
+ /** The ffmpeg executable, or null when there is none. */
14
+ export function findFfmpeg() {
15
+ if (ffmpegPath !== undefined)
16
+ return ffmpegPath;
17
+ const candidate = process.env.OPENBONE_FFMPEG || "ffmpeg";
18
+ try {
19
+ const r = spawnSync(candidate, ["-hide_banner", "-version"], { encoding: "utf8" });
20
+ ffmpegPath = r.status === 0 ? candidate : null;
21
+ }
22
+ catch {
23
+ ffmpegPath = null;
24
+ }
25
+ return ffmpegPath;
26
+ }
27
+ /** Run ffmpeg with `input` on stdin; resolves with stdout. */
28
+ function ffmpeg(args, input) {
29
+ const bin = findFfmpeg();
30
+ if (!bin)
31
+ return Promise.reject(new Error("ffmpeg not found"));
32
+ return new Promise((resolve, reject) => {
33
+ const p = spawn(bin, ["-hide_banner", "-loglevel", "error", ...args], { stdio: ["pipe", "pipe", "pipe"] });
34
+ const out = [];
35
+ let err = "";
36
+ p.stdout.on("data", (d) => out.push(d));
37
+ p.stderr.on("data", (d) => (err += d.toString()));
38
+ p.on("error", reject);
39
+ p.on("close", (code) => (code === 0 ? resolve(Buffer.concat(out)) : reject(new Error(`ffmpeg failed (${code}): ${err.trim().slice(0, 500)}`))));
40
+ p.stdin.on("error", () => {
41
+ /* ffmpeg closed its input early: the exit code says why */
42
+ });
43
+ const write = (b) => new Promise((res) => {
44
+ if (p.stdin.write(b))
45
+ res();
46
+ else
47
+ p.stdin.once("drain", () => res());
48
+ });
49
+ if (typeof input === "function")
50
+ void input(write)
51
+ .then(() => p.stdin.end())
52
+ .catch(reject);
53
+ else if (input)
54
+ p.stdin.end(input);
55
+ else
56
+ p.stdin.end();
57
+ });
58
+ }
59
+ /**
60
+ * Decode an audio file: WAV in-process, anything else through ffmpeg (stereo float at `sampleRate`). Null when it
61
+ * can't be decoded (no ffmpeg, or a broken file).
62
+ */
63
+ export async function decodeAudio(bytes, sampleRate = 48000) {
64
+ const wav = decodeWav(bytes);
65
+ if (wav)
66
+ return wav;
67
+ if (!findFfmpeg())
68
+ return null;
69
+ try {
70
+ const raw = await ffmpeg(["-i", "pipe:0", "-f", "f32le", "-ac", "2", "-ar", String(sampleRate), "pipe:1"], bytes);
71
+ const f = new Float32Array(raw.buffer, raw.byteOffset, Math.floor(raw.byteLength / 4));
72
+ const n = f.length >> 1;
73
+ const l = new Float32Array(n);
74
+ const r = new Float32Array(n);
75
+ for (let i = 0; i < n; i++) {
76
+ l[i] = f[i * 2];
77
+ r[i] = f[i * 2 + 1];
78
+ }
79
+ return { sampleRate, channels: [l, r] };
80
+ }
81
+ catch {
82
+ return null;
83
+ }
84
+ }
85
+ /**
86
+ * Encode frames (and an optional sound track) as MP4 (H.264 + AAC, yuv420p, plays everywhere) or WebM (VP9 + Opus)
87
+ * with ffmpeg. `quality` 0..1 maps to the encoder's constant-quality setting.
88
+ */
89
+ export async function encodeVideoFfmpeg(frames, o) {
90
+ if (!findFfmpeg())
91
+ throw new Error(`${o.format.toUpperCase()} export needs ffmpeg on the PATH (or OPENBONE_FFMPEG set to it). Install ffmpeg, or export ${o.format.toUpperCase()} from the editor (it uses the browser's encoders), or use AVI / MOV.`);
92
+ const { width, height } = frames[0];
93
+ // H.264 / yuv420p need even sizes.
94
+ const w = width + (width % 2);
95
+ const h = height + (height % 2);
96
+ const dir = mkdtempSync(path.join(tmpdir(), "openbone-video-"));
97
+ try {
98
+ const out = path.join(dir, `out.${o.format}`);
99
+ const args = ["-y", "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${width}x${height}`, "-r", String(o.fps), "-i", "pipe:0"];
100
+ if (o.audio) {
101
+ const wav = path.join(dir, "sound.wav");
102
+ writeFileSync(wav, encodeWav(o.audio));
103
+ args.push("-i", wav);
104
+ }
105
+ const q = Math.max(0, Math.min(1, o.quality ?? 0.85));
106
+ if (w !== width || h !== height)
107
+ args.push("-vf", `pad=${w}:${h}:0:0`);
108
+ if (o.format === "mp4")
109
+ args.push("-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", String(Math.round(35 - q * 20)), "-preset", "medium", "-movflags", "+faststart");
110
+ else
111
+ args.push("-c:v", "libvpx-vp9", "-pix_fmt", "yuv420p", "-b:v", "0", "-crf", String(Math.round(45 - q * 20)), "-row-mt", "1");
112
+ if (o.audio)
113
+ args.push(...(o.format === "mp4" ? ["-c:a", "aac", "-b:a", "192k"] : ["-c:a", "libopus", "-b:a", "160k"]), "-shortest");
114
+ args.push(out);
115
+ await ffmpeg(args, async (write) => {
116
+ for (const f of frames)
117
+ await write(f.data instanceof Uint8Array ? f.data : new Uint8Array(f.data.buffer, f.data.byteOffset, f.data.byteLength));
118
+ });
119
+ return new Uint8Array(readFileSync(out));
120
+ }
121
+ finally {
122
+ rmSync(dir, { recursive: true, force: true });
123
+ }
124
+ }
@@ -0,0 +1,81 @@
1
+ import { type Canvas, type Image } from "@napi-rs/canvas";
2
+ import { type AtlasData, type OpenBoneDocument } from "@openbone/core";
3
+ import { type AtlasEnv, type AtlasScaleVariant, type BuildAtlasOptions, type BuiltAtlas } from "@openbone/render-canvas";
4
+ import { OpenBoneInstance, type ScriptHost } from "@openbone/runtime";
5
+ import type { ProjectSession } from "./session.js";
6
+ export interface Step {
7
+ /** Seconds to advance after applying this step's inputs. */
8
+ advance?: number;
9
+ setInputs?: Record<string, boolean | number | string>;
10
+ fire?: string[];
11
+ /** Pointer in artboard pixels (y-down, top-left origin). */
12
+ pointer?: {
13
+ type: "down" | "up" | "move";
14
+ x: number;
15
+ y: number;
16
+ };
17
+ }
18
+ export interface PoseRequest {
19
+ /** Skin to show (name or id); defaults to the default skin only. */
20
+ skin?: string;
21
+ animation?: string;
22
+ time?: number;
23
+ stateMachine?: string;
24
+ steps?: Step[];
25
+ }
26
+ export interface RenderRequest extends PoseRequest {
27
+ scale?: number;
28
+ showBones?: boolean;
29
+ showBoundingBoxes?: boolean;
30
+ wireframe?: boolean;
31
+ background?: string | null;
32
+ }
33
+ export declare function loadImages(session: Pick<ProjectSession, "readImageSrc">, doc: OpenBoneDocument): Promise<Map<string, Image>>;
34
+ export declare function useSkin(inst: OpenBoneInstance, skin?: string): void;
35
+ /** Build a posed instance for the request. Returns logs from state machine simulation. */
36
+ export declare function pose(doc: OpenBoneDocument, req: PoseRequest, scriptHost?: ScriptHost | null): {
37
+ inst: OpenBoneInstance;
38
+ log: string[];
39
+ };
40
+ export declare function renderPng(session: ProjectSession, req: RenderRequest, scriptHost?: ScriptHost | null): Promise<{
41
+ png: Buffer<ArrayBufferLike>;
42
+ log: string[];
43
+ }>;
44
+ /**
45
+ * Largest GIF returned inline by render_gif. A tool result travels as one JSON-RPC message (the image as base64, a
46
+ * third bigger), and MCP clients drop the connection on very large messages: a 14 MB GIF (19 MB of base64) did. Bigger
47
+ * GIFs are still saved to disk; the result then carries a contact sheet of a few frames instead.
48
+ */
49
+ export declare const MAX_INLINE_GIF: number;
50
+ /** A grid of evenly spaced frames, for a preview of a long render. */
51
+ export declare function contactSheet(frameW: number, frameH: number, count: number, cols?: number, rows?: number): {
52
+ add(canvas: Canvas, index: number): void;
53
+ png: () => Buffer<ArrayBufferLike>;
54
+ picks: number[];
55
+ };
56
+ export declare function renderGif(session: ProjectSession, req: {
57
+ animation?: string;
58
+ stateMachine?: string;
59
+ skin?: string;
60
+ duration: number;
61
+ fps: number;
62
+ scale?: number;
63
+ showBones?: boolean;
64
+ steps?: Step[];
65
+ }, scriptHost?: ScriptHost | null,
66
+ /** Called with each rendered frame (e.g. to build a preview); the canvas is reused, so copy what you need. */
67
+ onFrame?: (canvas: Canvas, index: number, count: number) => void): Promise<Buffer<ArrayBuffer>>;
68
+ /**
69
+ * Lay out every image of `doc` on atlas pages and compose the page PNGs (as data: URIs), with the same code the
70
+ * editor uses (`buildAtlas`). Images that already live only in an atlas are cut back out of their page. The result
71
+ * is ready for the `setAtlas` op.
72
+ */
73
+ export declare function packAtlas(session: Pick<ProjectSession, "readImageSrc">, doc: OpenBoneDocument, opts?: BuildAtlasOptions): Promise<AtlasData>;
74
+ /** `packAtlas` with the scale used and any warnings (e.g. JPEG pages losing transparency). */
75
+ export declare function packAtlasFull(session: Pick<ProjectSession, "readImageSrc">, doc: OpenBoneDocument, opts?: BuildAtlasOptions): Promise<BuiltAtlas>;
76
+ /** One atlas per scale variant (multi-scale packs), images loaded once. */
77
+ export declare function packAtlasScales(session: Pick<ProjectSession, "readImageSrc">, doc: OpenBoneDocument, opts: BuildAtlasOptions, variants: AtlasScaleVariant[]): Promise<(BuiltAtlas & {
78
+ suffix: string;
79
+ })[]>;
80
+ /** Canvases, image loading and PNG / JPEG encoding for the atlas packer, in Node (@napi-rs/canvas). */
81
+ export declare function atlasEnv(session: Pick<ProjectSession, "readImageSrc">): AtlasEnv;