@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/gen/local/voice-rules.js

@@ -0,0 +1,156 @@
+export const MAX_LINE_CHARS = 500;
+export const DEFAULT_SAMPLE = 'Hello there. This is how I sound.';
+export const MAX_TAGS = 4;
+export const MAX_EMOTIONS = 3;
+export const TAG_PATTERN = '^[a-z][a-z -]{0,23}$';
+export const NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9 _.'-]{0,39}$";
+export const MAX_DESCRIPTION_CHARS = 500;
+export const RECORD_VERSION = 1;
+export const PRESETS = [
+    ['Zephyr', 'bright'], ['Puck', 'upbeat'], ['Charon', 'informative'], ['Kore', 'firm'], ['Fenrir', 'excitable'],
+    ['Leda', 'youthful'], ['Orus', 'firm'], ['Aoede', 'breezy'], ['Callirrhoe', 'easy-going'], ['Autonoe', 'bright'],
+    ['Enceladus', 'breathy'], ['Iapetus', 'clear'], ['Umbriel', 'easy-going'], ['Algieba', 'smooth'], ['Despina', 'smooth'],
+    ['Erinome', 'clear'], ['Algenib', 'gravelly'], ['Rasalgethi', 'informative'], ['Laomedeia', 'upbeat'], ['Achernar', 'soft'],
+    ['Alnilam', 'firm'], ['Schedar', 'even'], ['Gacrux', 'mature'], ['Pulcherrima', 'forward'], ['Achird', 'friendly'],
+    ['Zubenelgenubi', 'casual'], ['Vindemiatrix', 'gentle'], ['Sadachbia', 'lively'], ['Sadaltager', 'knowledgeable'], ['Sulafat', 'warm'],
+];
+export const hostedPreset = (name) => PRESETS.find(([p]) => p.toLowerCase() === name.trim().toLowerCase())?.[0] ?? null;
+const isTag = (t) => new RegExp(TAG_PATTERN).test(t);
+export function tags(field, raw, max) {
+    const out = [];
+    for (const r of Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]) {
+        const t = String(r).trim().toLowerCase();
+        if (!isTag(t))
+            throw new Error(`\`${field}\` are delivery words in lowercase, e.g. "gruff", "whispering" (1–24 letters, spaces or -)`);
+        if (!out.includes(t))
+            out.push(t);
+    }
+    if (out.length > max)
+        throw new Error(`at most ${max} \`${field}\``);
+    return out;
+}
+export function text(field, raw, max) {
+    const t = String(raw ?? '').trim();
+    if (!t)
+        throw new Error(`\`${field}\` must not be empty`);
+    if ([...t].length > max)
+        throw new Error(`\`${field}\` is longer than ${max} characters`);
+    return t;
+}
+export const spoken = (voiceTags, emotion, line) => [...voiceTags, ...emotion].map((t) => `[${t}] `).join('') + line;
+export function castArgs(input) {
+    const name = String(input.name ?? '').trim();
+    if (!new RegExp(NAME_PATTERN).test(name))
+        throw new Error("`name` is the cast member's name: 1–40 letters, digits, spaces or _ . ' -");
+    if (typeof input.preset !== 'string' || !input.preset.trim())
+        throw new Error('give the voice: a `preset`');
+    return {
+        name,
+        voice: { preset: input.preset.trim(), tags: tags('tags', input.tags, MAX_TAGS) },
+        ...(input.description !== undefined ? { description: text('description', input.description, MAX_DESCRIPTION_CHARS) } : {}),
+        sample: input.sample !== undefined ? text('sample', input.sample, MAX_LINE_CHARS) : DEFAULT_SAMPLE,
+    };
+}
+export function lineArgs(input) {
+    const record = input.voice_asset_id;
+    const preset = typeof input.preset === 'string' ? input.preset.trim() : undefined;
+    const given = Array.isArray(input.tags) ? input.tags : [];
+    let voice;
+    if (record !== undefined && preset === undefined && given.length === 0)
+        voice = { record: String(record) };
+    else if (record !== undefined)
+        throw new Error('give `voice_asset_id` (a cast_voice record) or `preset` and `tags`, not both');
+    else if (preset)
+        voice = { inline: { preset, tags: tags('tags', input.tags, MAX_TAGS) } };
+    else
+        throw new Error('give the voice: `voice_asset_id` (a cast_voice record) or a `preset`');
+    return { text: text('text', input.text, MAX_LINE_CHARS), voice, emotion: tags('emotion', input.emotion, MAX_EMOTIONS) };
+}
+export const MAX_DIALOGUE_LINES = 60;
+export const MAX_SCRIPT_CHARS = 4000;
+export const DEFAULT_GAP_MS = 250;
+export const MAX_PAUSE_MS = 10000;
+export const DIALOGUE_VERSION = 1;
+const LINE_KEYS = ['speaker', 'text', 'voice', 'tags', 'pause_after_ms', 'track'];
+const SCRIPT_KEYS = ['lines', 'cast', 'gap_ms', 'model'];
+const NAME_WORDS = "1–40 letters, digits, spaces or _ . ' -";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function ms(field, raw) {
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 0 || raw > MAX_PAUSE_MS)
+        throw new Error(`\`${field}\` must be 0–${MAX_PAUSE_MS} (milliseconds)`);
+    return raw;
+}
+function name(field, raw, what) {
+    const n = typeof raw === 'string' ? raw.trim() : '';
+    if (!new RegExp(NAME_PATTERN).test(n))
+        throw new Error(`\`${field}\` is ${what}: ${NAME_WORDS}`);
+    return n;
+}
+export function dialogueArgs(input) {
+    for (const k of Object.keys(input))
+        if (!SCRIPT_KEYS.includes(k))
+            throw new Error(`dialogue takes ${SCRIPT_KEYS.join(', ')}; not \`${k}\``);
+    const raw = input.lines;
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new Error('give the scene as `lines`: [{speaker, text, voice?}, …]');
+    if (raw.length > MAX_DIALOGUE_LINES)
+        throw new Error(`at most ${MAX_DIALOGUE_LINES} lines (this scene has ${raw.length}) — split the scene`);
+    const cast = new Map();
+    if (input.cast !== undefined) {
+        if (!isObj(input.cast))
+            throw new Error('`cast` maps each speaker to a voice: {"Bram": "Charon"}');
+        for (const [k, v] of Object.entries(input.cast)) {
+            const who = name(`cast.${k}`, k, "a speaker's name");
+            if (typeof v !== 'string' || !v.trim())
+                throw new Error(`\`cast.${who}\` is a voice: a voice.json (its asset id) or a preset`);
+            cast.set(who, v.trim());
+        }
+    }
+    const gap = input.gap_ms === undefined ? DEFAULT_GAP_MS : ms('gap_ms', input.gap_ms);
+    const lines = raw.map((l, i) => {
+        const at = `lines[${i}]`;
+        if (!isObj(l))
+            throw new Error(`\`${at}\` is a line: {speaker, text, voice?}`);
+        for (const k of Object.keys(l))
+            if (!LINE_KEYS.includes(k))
+                throw new Error(`\`${at}\` takes ${LINE_KEYS.join(', ')}; not \`${k}\``);
+        const speaker = name(`${at}.speaker`, l.speaker, "the speaker's name");
+        const words = text(`${at}.text`, l.text, MAX_LINE_CHARS);
+        if (l.voice !== undefined && (typeof l.voice !== 'string' || !l.voice.trim()))
+            throw new Error(`\`${at}.voice\` is a voice: a voice.json (its asset id) or a preset`);
+        const given = typeof l.voice === 'string' ? l.voice.trim() : cast.get(speaker);
+        if (!given)
+            throw new Error(`${at}: give \`voice\` or a \`cast\` entry for ${speaker}`);
+        return {
+            speaker,
+            text: words,
+            voice: given,
+            tags: tags(`${at}.tags`, l.tags, MAX_TAGS),
+            pause_after_ms: l.pause_after_ms === undefined ? gap : ms(`${at}.pause_after_ms`, l.pause_after_ms),
+            track: l.track === undefined ? speaker : name(`${at}.track`, l.track, "a track's name"),
+        };
+    });
+    const total = lines.reduce((n, l) => n + [...l.text].length, 0);
+    if (total > MAX_SCRIPT_CHARS)
+        throw new Error(`the script's lines total ${total} characters; at most ${MAX_SCRIPT_CHARS} — split the scene`);
+    return { lines, gap_ms: gap };
+}
+export const secs = (frames, rate) => Math.round((frames / rate) * 1000) / 1000;
+export const pauseFrames = (ms, rate) => Math.round((ms * rate) / 1000);
+export function timeline(lines, frames, rate, files) {
+    const starts = [];
+    let at = 0;
+    lines.forEach((l, i) => {
+        starts.push(at);
+        at += frames[i] + (i < lines.length - 1 ? pauseFrames(l.pause_after_ms, rate) : 0);
+    });
+    const tracks = [];
+    lines.forEach((l, i) => {
+        let t = tracks.find((x) => x.name === l.track);
+        if (!t)
+            tracks.push((t = { name: l.track, speaker: l.speaker, clips: [] }));
+        t.clips.push({ line: i + 1, speaker: l.speaker, file: files[i], start: secs(starts[i], rate), duration: secs(frames[i], rate), text: l.text });
+    });
+    return { tracks, starts, frames: at, duration: secs(at, rate) };
+}
+export const lineStem = (i) => `line-${String(i + 1).padStart(2, '0')}`;

package/dist/gen/models.generated.js

@@ -0,0 +1,469 @@
+export const GEN_MODELS = {
+    "_generated": "from funpixel-media src/gen_models.rs by `UPDATE_GEN_MODELS=1 cargo nextest run -p funpixel-media -E 'test(the_mirror_is_current)'`; do not edit",
+    "kinds": [
+        "image",
+        "image_edit",
+        "sound",
+        "music",
+        "voice",
+        "video",
+        "video_edit",
+        "lip_sync",
+        "model3d",
+        "skybox"
+    ],
+    "models": [
+        {
+            "caps": {
+                "aspect_ratios": [
+                    "1:1",
+                    "3:2",
+                    "2:3",
+                    "4:3",
+                    "3:4",
+                    "16:9",
+                    "9:16",
+                    "21:9"
+                ],
+                "max_references": 16,
+                "native_alpha": true,
+                "qualities": [
+                    "low",
+                    "medium",
+                    "high"
+                ]
+            },
+            "fallback": "flux-2-pro",
+            "id": "gpt-image-2.5",
+            "kind": "image",
+            "label": "GPT Image 2.5",
+            "one_line": "our pick: strong art direction, real transparency, up to 16 reference pictures",
+            "plan": "any",
+            "price_rows": [
+                "image_low",
+                "image_medium",
+                "image_high"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "aspect_ratios": [
+                    "1:1",
+                    "3:2",
+                    "2:3",
+                    "4:3",
+                    "3:4",
+                    "16:9",
+                    "9:16",
+                    "21:9"
+                ],
+                "max_references": 16,
+                "native_alpha": true,
+                "qualities": [
+                    "low",
+                    "medium",
+                    "high"
+                ]
+            },
+            "id": "gpt-image-2.5-edit",
+            "kind": "image_edit",
+            "label": "GPT Image 2.5 edit",
+            "one_line": "our pick: changes what the words say and keeps the rest; a cut-out stays a cut-out",
+            "plan": "any",
+            "price_rows": [
+                "image_edit_low",
+                "image_edit_medium",
+                "image_edit_high"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "loops": true,
+                "seconds": [
+                    0.5,
+                    30.0
+                ]
+            },
+            "id": "eleven-sfx-2",
+            "kind": "sound",
+            "label": "Eleven SFX v2",
+            "one_line": "our pick: one sound effect from words, 0.5 to 30 s, loopable",
+            "plan": "any",
+            "price_rows": [
+                "sound"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "lengths": [
+                    "clip",
+                    "full"
+                ]
+            },
+            "id": "lyria-3",
+            "kind": "music",
+            "label": "Lyria 3",
+            "one_line": "our pick: a ~30 s loop or a full track, with or without vocals",
+            "plan": "any",
+            "price_rows": [
+                "music_clip",
+                "music_track"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "voices": 30
+            },
+            "id": "gemini-tts-3.8",
+            "kind": "voice",
+            "label": "Gemini 3.8 TTS",
+            "one_line": "our pick: 30 preset voices steered by delivery tags; no cloning",
+            "plan": "any",
+            "price_rows": [
+                "voice_line",
+                "voice_minute"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "aspect_ratios": [
+                    "16:9",
+                    "9:16",
+                    "1:1"
+                ],
+                "audio": true,
+                "camera": {
+                    "native": {},
+                    "phrase": {
+                        "aperture": [
+                            "deep",
+                            "shallow"
+                        ],
+                        "lens": [
+                            "wide",
+                            "normal",
+                            "tele",
+                            "macro"
+                        ],
+                        "move": [
+                            "static",
+                            "pan_left",
+                            "pan_right",
+                            "tilt_up",
+                            "tilt_down",
+                            "dolly_in",
+                            "dolly_out",
+                            "orbit_left",
+                            "orbit_right",
+                            "crane_up",
+                            "handheld"
+                        ],
+                        "speed": [
+                            "slow",
+                            "normal",
+                            "fast"
+                        ]
+                    }
+                },
+                "end_frame": true,
+                "max_references": 4,
+                "resolutions": [
+                    "480p",
+                    "720p",
+                    "1080p"
+                ],
+                "seconds": [
+                    2.0,
+                    30.0
+                ]
+            },
+            "id": "wan-3.0",
+            "kind": "video",
+            "label": "Wan 3.0",
+            "one_line": "our pick: 2–30 s at 480p, 720p or 1080p, an end frame, references, optional sound",
+            "plan": "paid",
+            "price_rows": [
+                "video_480p_second",
+                "video_720p_second",
+                "video_1080p_second"
+            ],
+            "reason": "Video is on paid plans",
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "aspect_ratios": [
+                    "16:9",
+                    "9:16",
+                    "1:1"
+                ],
+                "camera": {
+                    "native": {},
+                    "phrase": {
+                        "aperture": [
+                            "deep",
+                            "shallow"
+                        ],
+                        "lens": [
+                            "wide",
+                            "normal",
+                            "tele",
+                            "macro"
+                        ],
+                        "move": [
+                            "static",
+                            "pan_left",
+                            "pan_right",
+                            "tilt_up",
+                            "tilt_down",
+                            "dolly_in",
+                            "dolly_out",
+                            "orbit_left",
+                            "orbit_right",
+                            "crane_up",
+                            "handheld"
+                        ],
+                        "speed": [
+                            "slow",
+                            "normal"
+                        ]
+                    }
+                },
+                "seconds_steps": [
+                    5,
+                    10
+                ]
+            },
+            "id": "kling-2.5",
+            "kind": "video",
+            "label": "Kling 2.5",
+            "one_line": "5 or 10 s at one resolution, strong cinematic motion; no end frame, references or sound",
+            "plan": "paid",
+            "price_rows": [
+                "video_5s",
+                "video_10s"
+            ],
+            "reason": "Video is on paid plans",
+            "recommended": false,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "audio": true,
+                "max_references": 1,
+                "resolutions": [
+                    "720p",
+                    "1080p"
+                ],
+                "seconds": [
+                    2.0,
+                    10.0
+                ]
+            },
+            "id": "wan-2.7",
+            "kind": "video_edit",
+            "label": "Wan 2.7 edit",
+            "one_line": "our pick: edits a 2–10 s clip from an instruction, at 720p or 1080p",
+            "plan": "paid",
+            "price_rows": [
+                "video_edit_720p_second",
+                "video_edit_1080p_second"
+            ],
+            "reason": "Video is on paid plans",
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "face": "one clear face toward the camera, head and shoulders in frame: a person, a drawn character or an animal",
+                "max_audio_seconds": 60,
+                "resolutions": [
+                    "480p",
+                    "720p"
+                ],
+                "seconds": [
+                    1.0,
+                    60.0
+                ]
+            },
+            "id": "fabric-1.0",
+            "kind": "lip_sync",
+            "label": "Fabric 1.0",
+            "one_line": "our pick: a portrait and up to a minute of speech made into a talking clip, lips, head and shoulders moving, at 480p or 720p; the clip keeps the portrait's shape",
+            "plan": "paid",
+            "price_rows": [
+                "lip_sync_480p_second",
+                "lip_sync_720p_second"
+            ],
+            "reason": "Video is on paid plans",
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "aliases": [
+                "meshy"
+            ],
+            "caps": {
+                "max_clips": 8,
+                "rig": true,
+                "styles": [
+                    "standard",
+                    "hero"
+                ],
+                "views": 3
+            },
+            "fallback": "hunyuan-3.1",
+            "id": "meshy-7.1",
+            "kind": "model3d",
+            "label": "Meshy 7.1",
+            "one_line": "our pick: detailed textured models that rig humanoids in the same job",
+            "plan": "paid",
+            "price_rows": [
+                "model3d_meshy",
+                "model3d_rig",
+                "model3d_anim_clip"
+            ],
+            "reason": "3D models are on paid plans",
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "aliases": [
+                "hunyuan"
+            ],
+            "caps": {
+                "max_clips": 8,
+                "rig": true,
+                "styles": [
+                    "standard",
+                    "hero",
+                    "lowpoly"
+                ],
+                "views": 3
+            },
+            "id": "hunyuan-3.1",
+            "kind": "model3d",
+            "label": "Hunyuan 3.1",
+            "one_line": "4096 px maps, the cheap untextured low-poly draft, rigs humanoids",
+            "plan": "paid",
+            "price_rows": [
+                "model3d_rapid",
+                "model3d_pro",
+                "model3d_hero",
+                "model3d_rig",
+                "model3d_anim_clip"
+            ],
+            "reason": "3D models are on paid plans",
+            "recommended": false,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "aliases": [
+                "rodin"
+            ],
+            "caps": {
+                "styles": [
+                    "standard",
+                    "hero",
+                    "lowpoly"
+                ],
+                "views": 3
+            },
+            "id": "rodin-2.5",
+            "kind": "model3d",
+            "label": "Rodin 2.5",
+            "one_line": "hard-surface props, every view in one job; static only (no rig)",
+            "plan": "paid",
+            "price_rows": [
+                "model3d_rodin",
+                "model3d_rodin_hero",
+                "model3d_rodin_lowpoly"
+            ],
+            "reason": "3D models are on paid plans",
+            "recommended": false,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "aspect_ratios": [
+                    "2:1"
+                ]
+            },
+            "id": "skybox-67",
+            "kind": "skybox",
+            "label": "Skybox",
+            "one_line": "our pick: one equirectangular 360° sky, 2:1",
+            "plan": "any",
+            "price_rows": [
+                "skybox"
+            ],
+            "recommended": true,
+            "runs": {
+                "where": "hosted"
+            }
+        },
+        {
+            "caps": {
+                "languages": [
+                    "en-us",
+                    "en-gb",
+                    "es",
+                    "fr",
+                    "hi",
+                    "it",
+                    "ja",
+                    "pt-br",
+                    "zh"
+                ],
+                "voices": 54
+            },
+            "id": "kokoro-82m",
+            "kind": "voice",
+            "label": "Kokoro 82M",
+            "one_line": "runs on your Mac, free and offline, slower and not checked by us; 54 preset voices, delivery tags only as pace",
+            "plan": "any",
+            "price_rows": [],
+            "recommended": false,
+            "runs": {
+                "needs": "Apple Silicon",
+                "runner": "mlx-audio",
+                "where": "local"
+            }
+        }
+    ]
+};

package/dist/gen/models.js

@@ -0,0 +1,53 @@
+import { GEN_MODELS } from "./models.generated.js";
+export const MODELS = GEN_MODELS.models.map((m) => ({
+    id: m.id,
+    kind: m.kind,
+    label: m.label,
+    one_line: m.one_line,
+    recommended: m.recommended,
+    aliases: 'aliases' in m ? m.aliases : [],
+    where: m.runs.where,
+}));
+const KIND_OF = {
+    image: 'image',
+    texture: 'image',
+    strip: 'image',
+    sprite: 'image',
+    sound: 'sound',
+    music: 'music',
+    voice: 'voice',
+    line: 'voice',
+    dialogue: 'voice',
+    video: 'video',
+    'edit-video': 'video_edit',
+    lipsync: 'lip_sync',
+    model3d: 'model3d',
+};
+export const MODEL_GEN_KINDS = Object.keys(KIND_OF);
+export const CAMERA_WORDS = (() => {
+    const words = { move: [], lens: [], aperture: [], speed: [] };
+    for (const m of GEN_MODELS.models) {
+        const camera = m.caps.camera;
+        if (!camera)
+            continue;
+        for (const way of [camera.native, camera.phrase]) {
+            for (const axis of Object.keys(words)) {
+                for (const w of way[axis] ?? [])
+                    if (!words[axis].includes(w))
+                        words[axis].push(w);
+            }
+        }
+    }
+    return words;
+})();
+export const modelKindOf = (genKind) => KIND_OF[genKind] ?? null;
+export const modelsOf = (kind) => MODELS.filter((m) => m.kind === kind);
+export const ENGINE_ALIASES = modelsOf('model3d').flatMap((m) => [...m.aliases]);
+export function resolveModel(kind, name) {
+    const hit = modelsOf(kind).find((m) => m.id === name || m.aliases.includes(name));
+    if (!hit) {
+        const ids = modelsOf(kind).map((m) => (m.recommended ? `${m.id} (recommended)` : m.where === 'local' ? `${m.id} (on this Mac)` : m.id));
+        throw new Error(`--model ${name} is not a ${kind} model here: use one of ${ids.join(', ')}, or drop --model for our pick`);
+    }
+    return hit;
+}