Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
feat: add bounded web media profiles to FableLoom exports (#13108)
Adam Eivye45784d8fb63
diff --git a/docs/features/fableloom-export-v1.md b/docs/features/fableloom-export-v1.mdindex 02cabc2cdb..50986a56be 100644--- a/docs/features/fableloom-export-v1.md+++ b/docs/features/fableloom-export-v1.md@@ -23,8 +23,11 @@ downloaded through a different loom. Instance authentication retains its existinoptional policy; no export endpoint is always-public.This core version explicitly refuses `includePlayer:true`,-`includeCharacters:true`, `includeVoice:true` and media profiles other than-`"source"`. Their implementation belongs to the linked export slices.+`includeCharacters:true` and `includeVoice:true`. Their implementation belongs+to the linked export slices. Unknown media profiles are rejected at validation.+`DELETE /api/fableloom/:id/export/:jobId` cancels a queued/running export and+waits for worker and encoder shutdown before returning its failed status+(`EXPORT_CANCELLED`). Completed jobs remain completed.## Gates and approvals@@ -47,11 +50,42 @@ Media reads accept basenames only, resolve inside the appropriate gallery/videoroot, refuse escaping symlinks and snapshot bounded regular-file bytes. Nohistory ID is reconstructed as a filename. Input changes during a read failthe job. Preparation decodes stills to metadata-free PNG and remuxes H.264-yuv420p / optional AAC MP4 without re-encoding picture/audio samples. Other codecs,-animated stills, resizing, bitrate profiles and loudness normalization are not-supported yet. Embedded container metadata, H.264 user-data SEI, chapters and extra tracks are+yuv420p / optional AAC MP4 without re-encoding picture/audio samples. Animated stills remain unsupported. Web profiles accept decodable MP4 picture/audio+streams and transcode them as described below. Embedded container metadata, H.264 user-data SEI, chapters and extra tracks areremoved; authored source files remain unchanged.+## Web media profiles++`mediaProfile` defaults to `"source"` for compatibility. Choose `"web-720p"` or+`"web-1080p"` for H.264 yuv420p/AAC MP4, metadata-free PNG stills and a poster PNG+for each clip. Presets preserve aspect ratio, never upscale, cap frame rate at+30 fps, and fit within 1280×720 or 1920×1080. Video target/maximum bitrates are+2,000 or 4,000 kbit/s with a two-second VBV buffer; audio targets are 128 or+192 kbit/s at 48 kHz. Variable bitrate packets and container overhead mean the+actual byte report, not bitrate multiplied by duration, is the package size.++Two-pass loudness normalization targets −16 LUFS, −1.5 dBTP and LRA 11 for the+existing authored audio mix (including dialogue and SFX). Silence remains+silence; clips without audio remain silent. No stem separation, speech synthesis,+provider calls or new creative media generation occurs. Normalization changes+level, not authored occupancy intervals. Oversized, invalid, failed or timed-out+encodes fail the job visibly; clips are never shortened to fit the byte limit.++Set `includeWebm:true` with a web profile to additionally encode VP9/Opus WebM.+MP4 remains the primary playback file. Video descriptors add a `poster`+descriptor and, when requested, `alternatives` with `type:"video/webm"`. These+are additive runtime-v1 fields; each carries its own hash, duration and bytes.++`provenance.json` records each primary file's bytes, the complete resolved+profile (including recipe version and WebM choice), encoder version/build hash,+source content hash and cache key, plus poster/alternative descriptors. The+cache keys source bytes, media kind, complete profile and encoder identity;+different history IDs with identical content share an encode. Repeated exports+reuse verified cached bytes and hashes. A changed profile, source or encoder+invalidates reuse. Cache entries expire after 24 hours and are evicted oldest+first within a separate 256 MiB disk budget. Incomplete cache entries are never+accepted as completed encodes. Source media remains untouched.+## Package schema 1.0.0- `manifest.json`: export schema, playback runtime and PortOS versions; explicit@@ -59,7 +93,7 @@ removed; authored source files remain unchanged.Media uses only content hashes and relative `media/<sha256>.<ext>` references,with `durationMs`, `loopable` and projected audio occupancy.- `provenance.json`: per-use content hash, provider/model labels, parameter hash,- approval and conditioning status, and draft flags.+ approval and conditioning status, draft flags, and encoding provenance.- `media/`: deduplicated, metadata-free media.- `runtime-v1.md` and `README.md`: the versioned playback and hosting contracts.@@ -81,7 +115,7 @@ Only one job prepares media at a time. Graceful maintenance tracks it throughfinal status persistence and scratch cleanup.Prepared buffers are retained once by content hash, with a 256 MiB aggregatebudget; source-ID caches hold descriptors only. A preparation step adds at most-one 64 MiB source and one 64 MiB prepared result; ZIP construction adds at most+one 64 MiB source and up to three bounded prepared representations; ZIP construction adds at mostone 256 MiB archive buffer. Queued jobs retain only referenced video filenames.A failed job exposes an actionable code/message and its preflight findings,diff --git a/server/lib/fableLoomMediaProfiles.js b/server/lib/fableLoomMediaProfiles.jsnew file mode 100644index 0000000000..6c10828a18--- /dev/null+++ b/server/lib/fableLoomMediaProfiles.js@@ -0,0 +1,8 @@+/** Version changes invalidate cached encodes when the recipe changes. */+export const FABLELOOM_MEDIA_PROFILES = Object.freeze({+ source: Object.freeze({ id: 'source', version: 1 }),+ 'web-720p': Object.freeze({ id: 'web-720p', version: 1, width: 1280, height: 720,+ videoKbps: 2000, audioKbps: 128, fps: 30, integratedLufs: -16, truePeakDb: -1.5, loudnessRange: 11 }),+ 'web-1080p': Object.freeze({ id: 'web-1080p', version: 1, width: 1920, height: 1080,+ videoKbps: 4000, audioKbps: 192, fps: 30, integratedLufs: -16, truePeakDb: -1.5, loudnessRange: 11 }),+});diff --git a/server/lib/fableLoomValidation.js b/server/lib/fableLoomValidation.jsindex dee8da1c2e..44892e4a40 100644--- a/server/lib/fableLoomValidation.js+++ b/server/lib/fableLoomValidation.js@@ -54,7 +54,8 @@ export const exportOptionsSchema = z.object({includeCharacters: z.boolean().default(false),includeVoice: z.boolean().default(false),allowDraft: z.boolean().default(false),- mediaProfile: z.string().min(1).max(40).default('source'),+ mediaProfile: z.enum(['source', 'web-720p', 'web-1080p']).default('source'),+ includeWebm: z.boolean().default(false),}).strict();// The loom's pinned play routing is the shared per-record LLM route pindiff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.jsindex bc55c366af..136803b861 100644--- a/server/lib/hostControlRoutes.js+++ b/server/lib/hostControlRoutes.js@@ -1017,6 +1017,7 @@ export const HOST_CONTROL_ROUTES = Object.freeze([// Export preparation decodes authored media; download releases the resulting// private package. Both preserve authenticated delegated agent authority.'POST /api/fableloom/:id/export',+ 'DELETE /api/fableloom/:id/export/:jobId','GET /api/fableloom/:id/export/:jobId/download','POST /api/image-video/models/support-request',diff --git a/server/routes/fableLoom.js b/server/routes/fableLoom.jsindex bab6c722f6..740aab59e1 100644--- a/server/routes/fableLoom.js+++ b/server/routes/fableLoom.js@@ -142,6 +142,11 @@ router.get('/:id/export/:jobId', asyncHandler(async (req, res) => {res.json(await getFableLoomExport(req.params.id, req.params.jobId));}));+router.delete('/:id/export/:jobId', asyncHandler(async (req, res) => {+ const { cancelFableLoomExport } = await import('../services/fableLoom/exports.js');+ res.json(await cancelFableLoomExport(req.params.id, req.params.jobId));+}));+router.get('/:id/export/:jobId/download', asyncHandler(async (req, res) => {let artifact;let closed = false;diff --git a/server/services/fableLoom/exportMedia.js b/server/services/fableLoom/exportMedia.jsindex 4d538a4ebc..a0c25c09b2 100644--- a/server/services/fableLoom/exportMedia.js+++ b/server/services/fableLoom/exportMedia.js@@ -1,6 +1,7 @@import { constants } from 'node:fs';-import { open, realpath, stat } from 'node:fs/promises';+import { open, readFile, realpath, stat } from 'node:fs/promises';import { join } from 'node:path';+import { createHash } from 'node:crypto';import { promisify } from 'node:util';import sharp from 'sharp';import { execFile } from '../../lib/childProcess.js';@@ -9,6 +10,7 @@ import { findFfmpeg, findFfprobe, runFfmpegProcess } from '../../lib/ffmpeg.js';import { atomicWrite } from '../../lib/fileCore.js';import { isPathInsideDir } from '../../lib/pathSafety.js';import { FABLELOOM_EXPORT_LIMITS } from '../../lib/fableLoomExport.js';+import { FABLELOOM_MEDIA_PROFILES } from '../../lib/fableLoomMediaProfiles.js';import { ServerError } from '../../lib/errorHandler.js';const execFileAsync = promisify(execFile);@@ -46,53 +48,135 @@ export async function readFableLoomExportSource(root, filename) {}}-async function probe(path) {+export function checkExportCancelled(signal) {+ if (signal?.aborted) throw refusal('EXPORT_CANCELLED', 'Export cancelled. Start a new export when ready.');+}++async function probe(path, format = 'mov') {const bin = await findFfprobe();if (!bin) throw refusal('EXPORT_FFMPEG_REQUIRED', 'Install ffmpeg and ffprobe before exporting video.');const { stdout } = await execFileAsync(bin, [- '-v', 'error', '-protocol_whitelist', 'file', '-f', 'mov', '-i', path,- '-show_entries', 'stream=codec_type,codec_name,pix_fmt:format=duration', '-of', 'json',+ '-v', 'error', '-protocol_whitelist', 'file', '-f', format, '-i', path,+ '-show_entries', 'stream=codec_type,codec_name,pix_fmt,width,height:format=duration', '-of', 'json',], safeChildProcessOptions({ timeout: 10_000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 }));const result = JSON.parse(stdout);const video = result.streams?.filter(s => s.codec_type === 'video') || [];const audio = result.streams?.filter(s => s.codec_type === 'audio') || [];- if (video.length !== 1 || video[0].codec_name !== 'h264' || video[0].pix_fmt !== 'yuv420p'- || audio.length > 1 || audio.some(s => s.codec_name !== 'aac')) {- throw refusal('EXPORT_ENCODING_UNSUPPORTED', 'Source profile requires one H.264 yuv420p video stream and optional AAC audio. Transcode profiles are not available yet.');- }const durationMs = Math.round(Number(result.format?.duration) * 1000);- if (!Number.isSafeInteger(durationMs) || durationMs <= 0) {- throw refusal('EXPORT_MEDIA_INVALID', 'Video duration could not be verified.');+ if (video.length !== 1 || audio.length > 1 || !Number.isSafeInteger(durationMs) || durationMs <= 0+ || !Number.isSafeInteger(video[0].width * video[0].height) || video[0].width * video[0].height > 16 * 1024 * 1024) {+ throw refusal('EXPORT_MEDIA_INVALID', 'Video must have one bounded picture stream, optional audio and a valid duration.');+ }+ return { video: video[0], audio: audio[0], durationMs };+}++export async function fableLoomExportEncoder(kind) {+ const image = { sharp: sharp.versions.sharp, vips: sharp.versions.vips,+ imageBuildHash: createHash('sha256').update(JSON.stringify(sharp.versions)).digest('hex') };+ if (kind === 'image') return image;+ const bin = await findFfmpeg();+ if (!bin) throw refusal('EXPORT_FFMPEG_REQUIRED', 'Install ffmpeg and ffprobe before exporting video.');+ const { stdout } = await execFileAsync(bin, ['-version'], safeChildProcessOptions({ timeout: 10_000, maxBuffer: 64 * 1024 }));+ return { ffmpeg: stdout.match(/^ffmpeg version ([A-Za-z0-9._-]+)/)?.[1] || 'unknown',+ buildHash: createHash('sha256').update(stdout).digest('hex'), ...image };+}++async function encode(bin, args, signal, capture = false) {+ checkExportCancelled(signal);+ const result = await runFfmpegProcess({ bin, args: ['-nostdin', '-y', ...args], signal,+ timeoutMs: 120_000, returnStderr: capture, stderrTailBytes: capture ? 8192 : 2000 });+ checkExportCancelled(signal);+ if (!result.ok) throw refusal('EXPORT_TRANSCODE_FAILED', 'Media encoding failed or timed out. Check the source clip and ffmpeg support.');+ return result.stderr;+}++const loudness = profile => `loudnorm=I=${profile.integratedLufs}:TP=${profile.truePeakDb}:LRA=${profile.loudnessRange}`;+async function audioFilter(bin, inputArgs, profile, signal) {+ const stderr = await encode(bin, ['-v', 'info', ...inputArgs, '-vn', '-af', `${loudness(profile)}:print_format=json`, '-f', 'null', '-'], signal, true);+ const measurement = JSON.parse(stderr.slice(stderr.lastIndexOf('{'), stderr.lastIndexOf('}') + 1));+ // Silence has no finite integrated loudness; preserve silence through the same filter.+ if (!Number.isFinite(Number(measurement.input_i))) return loudness(profile);+ const values = ['input_i', 'input_tp', 'input_lra', 'input_thresh', 'target_offset'].map(k => Number(measurement[k]));+ if (!values.every(Number.isFinite)) throw refusal('EXPORT_MEDIA_INVALID', 'Audio loudness could not be measured.');+ return `${loudness(profile)}:measured_I=${values[0]}:measured_TP=${values[1]}:measured_LRA=${values[2]}:measured_thresh=${values[3]}:offset=${values[4]}:linear=true`;+}++/** Only prepared files use this extension set; authored video remains local MP4. */+async function outputBytes(path) {+ const info = await stat(path);+ if (!info.isFile() || info.size <= 0 || info.size >= FABLELOOM_EXPORT_LIMITS.maxAssetBytes) {+ throw refusal('EXPORT_MEDIA_SIZE', 'Prepared media reached the 64 MiB asset limit. Use a smaller profile or clip.');}- return durationMs;+ return readFile(path);}-/** Remove metadata without generating media or changing video/audio encodes. */-export async function prepareFableLoomExportMedia(bytes, kind, directory) {+/** Transcode existing authored media only; never calls a generation provider. */+export async function prepareFableLoomExportMedia(bytes, kind, directory, options = {}) {+ const profile = FABLELOOM_MEDIA_PROFILES[options.mediaProfile ?? 'source'];+ const { signal } = options;+ if (!profile || (profile.id === 'source' && options.includeWebm)) {+ throw refusal('EXPORT_OPTION_UNSUPPORTED', 'Choose a web profile to include WebM.');+ }+ checkExportCancelled(signal);if (kind === 'image') {const image = sharp(bytes, { limitInputPixels: 16 * 1024 * 1024 });const metadata = await image.metadata();if (!['png', 'jpeg', 'webp'].includes(metadata.format) || (metadata.pages || 1) !== 1) {throw refusal('EXPORT_ENCODING_UNSUPPORTED', 'Stills must be non-animated PNG, JPEG or WebP images.');}- return { bytes: await image.rotate().png({ compressionLevel: 9 }).toBuffer(), extension: 'png', durationMs: 0 };+ image.rotate();+ if (profile.width) image.resize({ width: profile.width, height: profile.height, fit: 'inside', withoutEnlargement: true });+ const output = await image.png({ compressionLevel: 9 }).toBuffer();+ checkExportCancelled(signal);+ return { bytes: output, extension: 'png', durationMs: 0 };}const input = join(directory, 'input.mp4');const output = join(directory, 'clean.mp4');await atomicWrite(input, bytes);- await probe(input);+ const source = await probe(input);const bin = await findFfmpeg();if (!bin) throw refusal('EXPORT_FFMPEG_REQUIRED', 'Install ffmpeg and ffprobe before exporting video.');- const result = await runFfmpegProcess({ bin, timeoutMs: 60_000, args: [- '-nostdin', '-y', '-v', 'error', '-protocol_whitelist', 'file', '-f', 'mov', '-i', input,- '-map', '0:v:0', '-map', '0:a:0?', '-map_metadata', '-1', '-map_metadata:s', '-1',- '-map_chapters', '-1', '-c', 'copy', '-bsf:v', 'filter_units=remove_types=6',- '-fflags', '+bitexact', '-movflags', '+faststart', output,- ] });- if (!result.ok) throw refusal('EXPORT_MEDIA_INVALID', 'Video metadata removal failed. Check the source clip and try again.');- const outputInfo = await stat(output);- if (outputInfo.size > FABLELOOM_EXPORT_LIMITS.maxAssetBytes) {- throw refusal('EXPORT_MEDIA_SIZE', 'Prepared media exceeds the 64 MiB asset limit.');+ const inputArgs = ['-protocol_whitelist', 'file', '-f', 'mov', '-i', input];+ const metadataArgs = ['-map_metadata', '-1', '-map_metadata:s', '-1', '-map_chapters', '-1'];+ const common = ['-v', 'error', ...inputArgs, '-map', '0:v:0', '-map', '0:a:0?', ...metadataArgs];+ let encoding;+ let filter;+ if (profile.id === 'source') {+ if (source.video.codec_name !== 'h264' || source.video.pix_fmt !== 'yuv420p' || (source.audio && source.audio.codec_name !== 'aac')) {+ throw refusal('EXPORT_ENCODING_UNSUPPORTED', 'Source profile requires H.264 yuv420p with optional AAC. Choose a web profile to transcode.');+ }+ encoding = ['-c', 'copy'];+ } else {+ filter = source.audio ? await audioFilter(bin, inputArgs, profile, signal) : null;+ const scale = `scale=w='min(iw,${profile.width})':h='min(ih,${profile.height})':force_original_aspect_ratio=decrease:force_divisible_by=2`;+ encoding = ['-vf', scale, '-fpsmax', String(profile.fps), '-c:v', 'libx264', '-preset', 'medium',+ '-pix_fmt', 'yuv420p', '-b:v', `${profile.videoKbps}k`, '-maxrate', `${profile.videoKbps}k`, '-bufsize', `${profile.videoKbps * 2}k`,+ '-threads', '1', '-c:a', 'aac', '-b:a', `${profile.audioKbps}k`, '-ar', '48000',+ ...(filter ? ['-af', filter] : []), '-t', String(source.durationMs / 1000)];+ }+ await encode(bin, [...common, ...encoding, '-bsf:v', 'filter_units=remove_types=6',+ '-fflags', '+bitexact', '-movflags', '+faststart', '-fs', String(FABLELOOM_EXPORT_LIMITS.maxAssetBytes), output], signal);+ const encoded = await probe(output);+ if (encoded.durationMs < source.durationMs - 1) throw refusal('EXPORT_MEDIA_SIZE', 'Encoding truncated the clip. Use a smaller profile or shorter clip.');+ const result = { bytes: await outputBytes(output), extension: 'mp4', durationMs: encoded.durationMs };+ if (profile.id !== 'source') {+ const poster = join(directory, 'poster.png');+ await encode(bin, ['-v', 'error', '-protocol_whitelist', 'file', '-i', output,+ '-frames:v', '1', ...metadataArgs, '-threads', '1', poster], signal);+ result.poster = { bytes: await outputBytes(poster), extension: 'png', durationMs: 0 };+ if (options.includeWebm) {+ const webm = join(directory, 'clean.webm');+ // Encode from the prepared MP4 so audio and picture timing share the primary representation.+ await encode(bin, ['-v', 'error', '-protocol_whitelist', 'file', '-i', output,+ '-map', '0:v:0', '-map', '0:a:0?', ...metadataArgs, '-c:v', 'libvpx-vp9', '-threads', '1',+ '-b:v', `${profile.videoKbps}k`, '-maxrate', `${profile.videoKbps}k`, '-bufsize', `${profile.videoKbps * 2}k`,+ '-c:a', 'libopus', '-b:a', `${profile.audioKbps}k`, '-fflags', '+bitexact',+ '-fs', String(FABLELOOM_EXPORT_LIMITS.maxAssetBytes), webm], signal);+ const alternate = await probe(webm, 'matroska');+ if (alternate.durationMs < source.durationMs - 1) throw refusal('EXPORT_MEDIA_SIZE', 'WebM encoding truncated the clip.');+ result.webm = { bytes: await outputBytes(webm), extension: 'webm', durationMs: alternate.durationMs };+ }}- return { bytes: await readFableLoomExportSource(directory, 'clean.mp4'), extension: 'mp4', durationMs: await probe(output) };+ checkExportCancelled(signal);+ return result;}diff --git a/server/services/fableLoom/exportMediaCache.js b/server/services/fableLoom/exportMediaCache.jsnew file mode 100644index 0000000000..e73bd02cef--- /dev/null+++ b/server/services/fableLoom/exportMediaCache.js@@ -0,0 +1,92 @@+import { createHash } from 'node:crypto';+import { readdir, readFile, stat } from 'node:fs/promises';+import { join } from 'node:path';+import { atomicWrite, ensureDir, rmGuarded } from '../../lib/fileCore.js';+import { canonicalStringify } from '../../lib/objects.js';+import { FABLELOOM_EXPORT_LIMITS } from '../../lib/fableLoomExport.js';+import { FABLELOOM_MEDIA_PROFILES } from '../../lib/fableLoomMediaProfiles.js';+import { checkExportCancelled, fableLoomExportEncoder, prepareFableLoomExportMedia } from './exportMedia.js';++const hash = bytes => createHash('sha256').update(bytes).digest('hex');+const parts = value => [['primary', value], ...['poster', 'webm'].filter(k => value[k]).map(k => [k, value[k]])];+const digestPattern = /^[a-f0-9]{64}$/;++/** The exporter serializes jobs; this bounded cache never retains buffers between calls. */+export async function createFableLoomMediaCache(root, options, signal) {+ const profile = { ...FABLELOOM_MEDIA_PROFILES[options.mediaProfile], includeWebm: options.includeWebm };+ const encoders = new Map();+ await ensureDir(root);+ const entries = [];+ let size = 0;+ for (const name of await readdir(root)) {+ if (!digestPattern.test(name)) continue;+ const directory = join(root, name);+ const files = await readdir(directory);+ const info = await stat(directory);+ let bytes = 0;+ for (const file of files) bytes += (await stat(join(directory, file))).size;+ if (Date.now() - info.mtimeMs >= FABLELOOM_EXPORT_LIMITS.maxAgeMs) await rmGuarded(directory, { recursive: true, force: true });+ else { entries.push({ name, bytes, modified: info.mtimeMs }); size += bytes; }+ }+ entries.sort((a, b) => a.modified - b.modified || a.name.localeCompare(b.name));+ async function evict(required) {+ while (size + required > FABLELOOM_EXPORT_LIMITS.maxPackageBytes && entries.length) {+ const oldest = entries.shift();+ await rmGuarded(join(root, oldest.name), { recursive: true, force: true });+ size -= oldest.bytes;+ }+ }+ await evict(0);+ return async (bytes, kind, work) => {+ checkExportCancelled(signal);+ if (!encoders.has(kind)) encoders.set(kind, await fableLoomExportEncoder(kind));+ const encoder = encoders.get(kind);+ const sourceSha256 = hash(bytes);+ const key = hash(canonicalStringify({ sourceSha256, kind, profile, encoder }));+ const directory = join(root, key);+ const encoding = { profile, encoder, sourceSha256, cacheKey: key };+ let cached;+ try {+ const meta = JSON.parse(await readFile(join(directory, 'entry.json'), 'utf8'));+ const expected = kind === 'video' && profile.id !== 'source'+ ? ['primary', 'poster', ...(profile.includeWebm ? ['webm'] : [])] : ['primary'];+ if (Object.keys(meta).sort().join() !== expected.sort().join()) throw new Error('Invalid cache entry');+ cached = {};+ for (const name of expected) {+ const item = meta[name];+ const extension = name === 'webm' ? 'webm' : name === 'poster' || kind === 'image' ? 'png' : 'mp4';+ if (!digestPattern.test(item.sha256) || item.extension !== extension || !Number.isSafeInteger(item.durationMs)+ || item.durationMs < 0 || !Number.isSafeInteger(item.size) || item.size <= 0+ || item.size > FABLELOOM_EXPORT_LIMITS.maxAssetBytes) throw new Error('Invalid cache descriptor');+ const file = join(directory, `${name}.${extension}`);+ if ((await stat(file)).size !== item.size) throw new Error('Cache size changed');+ const content = await readFile(file);+ if (hash(content) !== item.sha256) throw new Error('Cache hash changed');+ const value = { bytes: content, extension, durationMs: item.durationMs };+ if (name === 'primary') Object.assign(cached, value);+ else cached[name] = value;+ }+ } catch (failure) {+ if (failure.code && failure.code !== 'ENOENT') throw failure;+ cached = null;+ }+ if (cached) { checkExportCancelled(signal); return { ...cached, encoding }; }+ const result = await prepareFableLoomExportMedia(bytes, kind, work, { ...options, signal });+ checkExportCancelled(signal);+ const meta = Object.fromEntries(parts(result).map(([name, item]) => [name, {+ extension: item.extension, durationMs: item.durationMs, size: item.bytes.length, sha256: hash(item.bytes),+ }]));+ const required = parts(result).reduce((total, [, item]) => total + item.bytes.length, Buffer.byteLength(canonicalStringify(meta)) + 1);+ const existing = entries.findIndex(e => e.name === key);+ if (existing >= 0) { size -= entries[existing].bytes; entries.splice(existing, 1); }+ await rmGuarded(directory, { recursive: true, force: true });+ await evict(required);+ await ensureDir(directory);+ for (const [name, item] of parts(result)) await atomicWrite(join(directory, `${name}.${item.extension}`), item.bytes);+ checkExportCancelled(signal);+ await atomicWrite(join(directory, 'entry.json'), canonicalStringify(meta));+ entries.push({ name: key, bytes: required, modified: Date.now() });+ size += required;+ return { ...result, encoding };+ };+}diff --git a/server/services/fableLoom/exports.js b/server/services/fableLoom/exports.jsindex 8c486d7a50..728ccc3924 100644--- a/server/services/fableLoom/exports.js+++ b/server/services/fableLoom/exports.js@@ -19,11 +19,14 @@ import {import { getUniverse } from '../universeBuilder.js';import { loadHistory } from '../videoGen/history.js';import { getLoom } from './records.js';-import { prepareFableLoomExportMedia, readFableLoomExportSource } from './exportMedia.js';+import { checkExportCancelled, readFableLoomExportSource } from './exportMedia.js';+import { createFableLoomMediaCache } from './exportMediaCache.js';const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;const active = new Map();const downloads = new Map();+const controllers = new Map();+const completions = new Map();let admissionTail = Promise.resolve();let workerTail = Promise.resolve();const root = () => join(PATHS.data, 'cache', 'fableloom-exports');@@ -162,7 +165,7 @@ function createMediaStore(maxBytes = FABLELOOM_EXPORT_LIMITS.maxPackageBytes) {files.set(file, bytes);byteLength += bytes.length;}- return { file, sha256, durationMs };+ return { file, sha256, durationMs, bytes: bytes.length };},entries: () => files.entries(),get byteLength() { return byteLength; },@@ -186,14 +189,17 @@ Occupancy intervals are milliseconds relative to that packaged clip.provenance.json records each media use, provider/model, parameter hash, approvalstate and draftFlags. An allowDraft export does not certify production approval.-The source media profile strips metadata, encodes stills as PNG and stream-copies-H.264 yuv420p / optional AAC into MP4. It does not resize, normalize loudness or-transcode unsupported codecs. The player, character and voice opt-ins are not+The source profile remuxes H.264/AAC. Web profiles resize without upscaling,+encode H.264/AAC with bitrate caps, normalize the authored audio mix and include+poster PNGs. Explicitly requested WebM alternatives use VP9/Opus. Encoding+profiles, encoder identities and byte counts are recorded in provenance.json.+The player, character and voice opt-ins are notavailable in this package version. Your host owns free-text resolution, TTS andtransport, following runtime-v1.md; no PortOS URL or credential is needed.`;-async function build(job, snapshot, episodes, history, universe) {+async function build(job, snapshot, episodes, history, universe, signal) {+ checkExportCancelled(signal);job.status = 'validating';job.findings = inspectFableLoomExport(snapshot, episodes, universe);if (job.findings.some(f => f.severity === 'error')) {@@ -227,17 +233,22 @@ async function build(job, snapshot, episodes, history, universe) {const directory = join(jobDirectory(job.jobId), 'work');await ensureDir(directory);const cache = new Map();+ const prepare = await createFableLoomMediaCache(join(root(), 'media-cache'), job.options, signal);const media = createMediaStore();const nodeAssets = new Map();const provenance = [];for (const request of requests) {+ checkExportCancelled(signal);const key = `${request.kind}:${request.sourceId}`;let prepared = cache.get(key);if (!prepared) {const filename = request.kind === 'image' ? request.sourceId : history.find(h => h.id === request.sourceId)?.filename;if (!filename) throw error('EXPORT_MEDIA_MISSING', 'A referenced video history item is missing.');const bytes = await readFableLoomExportSource(request.kind === 'image' ? PATHS.images : PATHS.videos, filename);- prepared = media.add(await prepareFableLoomExportMedia(bytes, request.kind, directory));+ const result = await prepare(bytes, request.kind, directory);+ prepared = { ...media.add(result), encoding: result.encoding,+ ...(result.poster ? { poster: media.add(result.poster) } : {}),+ ...(result.webm ? { webm: media.add(result.webm) } : {}) };cache.set(key, prepared);}const occupancy = request.kind === 'video' ? fableLoomExportOccupancy(request.node, request.sourceId) : null;@@ -252,7 +263,9 @@ async function build(job, snapshot, episodes, history, universe) {const binding = {...request,playback: { file: prepared.file, sha256: prepared.sha256, durationMs: prepared.durationMs,- loopable: request.role === 'hold', ...(occupancy ? { audioOccupancy: occupancy } : {}) },+ loopable: request.role === 'hold', ...(occupancy ? { audioOccupancy: occupancy } : {}),+ ...(prepared.poster ? { poster: prepared.poster } : {}),+ ...(prepared.webm ? { alternatives: [{ ...prepared.webm, type: 'video/webm' }] } : {}) },};const nodeKey = `${request.episode.id}:${request.node.id}`;if (!nodeAssets.has(nodeKey)) nodeAssets.set(nodeKey, []);@@ -261,7 +274,9 @@ async function build(job, snapshot, episodes, history, universe) {episodeId: request.episode.id, nodeId: request.node.id, role: request.role,...(request.transitionId ? { transitionId: request.transitionId } : {}),...(request.index !== undefined ? { index: request.index } : {}),- file: prepared.file, sha256: prepared.sha256, ...assetProvenance(snapshot, request.node, request),+ file: prepared.file, sha256: prepared.sha256, bytes: prepared.bytes, encoding: prepared.encoding,+ ...(prepared.poster ? { poster: prepared.poster } : {}),+ ...(prepared.webm ? { webm: prepared.webm } : {}), ...assetProvenance(snapshot, request.node, request),});job.progress.completed++;await save(job);@@ -287,7 +302,9 @@ async function build(job, snapshot, episodes, history, universe) {if (archive.length > FABLELOOM_EXPORT_LIMITS.maxPackageBytes) {throw error('EXPORT_PACKAGE_SIZE', 'ZIP exceeds the 256 MiB limit. Export fewer episodes.');}+ checkExportCancelled(signal);await atomicWrite(join(jobDirectory(job.jobId), 'package.zip'), archive);+ checkExportCancelled(signal);job.filename = `fableloom-${hash(json(manifest)).slice(0, 16)}-v1.zip`;job.sizeReport = { mediaBytes: media.byteLength, totalBytes, archiveBytes: archive.length, mediaFiles: media.size };job.status = 'completed';@@ -297,18 +314,21 @@ async function run(job, context, permit) {let settled = false;try {try {- await build(job, context.snapshot, context.episodes, context.history, context.universe);+ await build(job, context.snapshot, context.episodes, context.history, context.universe, controllers.get(job.jobId).signal);} catch (failure) {job.status = 'failed';job.error = failure.code?.startsWith('EXPORT_')? { code: failure.code, message: failure.message }: { code: 'EXPORT_MEDIA_INVALID', message: 'A source media file is missing, unreadable or invalid. Check its attached media and start a new export.' };}+ if (job.status === 'failed') await rmGuarded(join(jobDirectory(job.jobId), 'package.zip'), { force: true });await rmGuarded(join(jobDirectory(job.jobId), 'work'), { recursive: true, force: true });await save(job);settled = true;} finally {active.delete(job.jobId);+ controllers.delete(job.jobId);+ completions.delete(job.jobId);if (settled) await permit.finish();else permit.markUnsettled();}@@ -316,8 +336,8 @@ async function run(job, context, permit) {export async function startFableLoomExport(loomId, input = {}) {const options = exportOptionsSchema.parse(input);- if (options.includePlayer || options.includeCharacters || options.includeVoice || options.mediaProfile !== 'source') {- throw error('EXPORT_OPTION_UNSUPPORTED', 'This exporter supports the source profile without player, character or voice packages.', 400);+ if (options.includePlayer || options.includeCharacters || options.includeVoice || (options.mediaProfile === 'source' && options.includeWebm)) {+ throw error('EXPORT_OPTION_UNSUPPORTED', 'Player, character and voice packages are unavailable. WebM requires a web media profile.', 400);}const jobId = randomUUID();const permit = maintenance.admit('media', jobId);@@ -342,9 +362,11 @@ export async function startFableLoomExport(loomId, input = {}) {progress: { completed: 0, total: 0 }, findings: [] };await save(job);active.set(jobId, job);+ controllers.set(jobId, new AbortController());return { job, snapshot, episodes, history, universe };});const pending = workerTail.then(() => permit.run(() => run(context.job, context, permit)));+ completions.set(jobId, pending);workerTail = pending.catch(() => { console.error('❌ FableLoom export persistence failed; maintenance ownership is retained.'); });return { jobId };} catch (failure) {@@ -353,6 +375,14 @@ export async function startFableLoomExport(loomId, input = {}) {}}+/** Wait for the worker and its children before reporting cancellation as settled. */+export async function cancelFableLoomExport(loomId, jobId) {+ await getFableLoomExport(loomId, jobId);+ controllers.get(jobId)?.abort();+ await completions.get(jobId);+ return getFableLoomExport(loomId, jobId);+}+export async function getFableLoomExport(loomId, jobId) {if (!await getLoom(loomId)) throw missing();const job = await readJob(jobId, loomId);diff --git a/server/services/fableLoom/exports.test.js b/server/services/fableLoom/exports.test.jsindex d267ce72b2..1ef31e00a3 100644--- a/server/services/fableLoom/exports.test.js+++ b/server/services/fableLoom/exports.test.js@@ -9,6 +9,7 @@ import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy, ownTestBodies }import { request } from '../../lib/testHelper.js';import { errorMiddleware } from '../../lib/errorHandler.js';import { readZipArchive } from '../../lib/zipArchive.js';+import * as ffmpeg from '../../lib/ffmpeg.js';import { findFfmpeg, findFfprobe, runFfmpegProcess } from '../../lib/ffmpeg.js';import { FABLELOOM_EXPORT_LIMITS } from '../../lib/fableLoomExport.js';import { execFileSync } from '../../lib/childProcess.js';@@ -190,6 +191,109 @@ describe('portable FableLoom export boundary', () => {expect(missingArtifact.text).not.toContain(removed.path);});+ videoIt('encodes bounded web media, normalizes audio, retains roles and reuses content/profile cache', async () => {+ const source = join(PATHS.videos, 'profile-fixture.mp4');+ expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: [+ '-nostdin', '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=blue:s=1600x900:r=15:d=1',+ '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=1', '-af', 'volume=0.1',+ '-c:v', 'mpeg4', '-c:a', 'aac', '-threads', '1', source,+ ] })).toEqual({ ok: true });+ const original = await readFile(source);+ loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'profile-fixture.mp4' })));+ const encode = vi.spyOn(ffmpeg, 'runFfmpegProcess');+ const options = { episodeIds: ['episode-one'], mediaProfile: 'web-720p', includeWebm: true };+ const firstId = await begin(options);+ const first = await archive(firstId);+ const firstCount = encode.mock.calls.length;+ const repeat = await archive(await begin(options));+ expect(repeat.bytes).toEqual(first.bytes);+ expect(encode).toHaveBeenCalledTimes(firstCount);+ // Three distinct history IDs with identical source content encode only once.+ expect(encode.mock.calls.filter(([args]) => args.args.includes('libx264'))).toHaveLength(1);+ const manifest = JSON.parse(first.files.get('manifest.json'));+ const assets = manifest.loom.episodes[0].nodes[0].playbackAssets;+ expect(assets.holds[0]).toMatchObject({ loopable: true, audioOccupancy: { durationMs: 1000,+ effects: [{ startMs: 0, endMs: 500 }], safeForLiveVoice: true } });+ expect(assets.exits.choose.file).toBe(assets.entry.file);+ expect(first.files.has(assets.entry.poster.file)).toBe(true);+ expect(assets.entry.alternatives).toHaveLength(1);+ const inspect = (file) => JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-show_format', '-of', 'json', file], { timeout: 10_000 }).toString());+ const encodedFile = join(PATHS.videos, 'packaged.mp4');+ await writeFile(encodedFile, first.files.get(assets.entry.file));+ const measured = inspect(encodedFile);+ expect(measured.streams.find(s => s.codec_type === 'video')).toMatchObject({ codec_name: 'h264', pix_fmt: 'yuv420p', width: 1280, height: 720 });+ expect(measured.streams.find(s => s.codec_type === 'audio')).toMatchObject({ codec_name: 'aac', sample_rate: '48000' });+ expect(Number(measured.streams.find(s => s.codec_type === 'video').bit_rate)).toBeLessThanOrEqual(2_000_000);+ expect(Number(measured.streams.find(s => s.codec_type === 'audio').bit_rate)).toBeLessThanOrEqual(128_000);+ const analyzed = await runFfmpegProcess({ bin, timeoutMs: 10_000, returnStderr: true, stderrTailBytes: 8192,+ args: ['-nostdin', '-i', encodedFile, '-vn', '-af', 'loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json', '-f', 'null', '-'] });+ expect(analyzed.ok).toBe(true);+ const level = JSON.parse(analyzed.stderr.slice(analyzed.stderr.lastIndexOf('{'), analyzed.stderr.lastIndexOf('}') + 1));+ expect(Math.abs(Number(level.input_i) + 16)).toBeLessThan(1);+ expect(Number(level.input_tp)).toBeLessThanOrEqual(-1.4);+ const webm = join(PATHS.videos, 'packaged.webm');+ await writeFile(webm, first.files.get(assets.entry.alternatives[0].file));+ expect(inspect(webm).streams.map(s => s.codec_name)).toEqual(['vp9', 'opus']);+ const provenance = JSON.parse(first.files.get('provenance.json'));+ expect(provenance.assets.find(a => a.role === 'entry')).toMatchObject({ bytes: first.files.get(assets.entry.file).length,+ encoding: { sourceSha256: hash(original), profile: { id: 'web-720p', videoKbps: 2000, includeWebm: true },+ encoder: { ffmpeg: expect.any(String), buildHash: expect.stringMatching(/^[a-f0-9]{64}$/) } } });+ const mediaFiles = [...first.files].filter(([name]) => name.startsWith('media/'));+ for (const [name, bytes] of mediaFiles) expect(name).toContain(hash(bytes));+ expect((await terminal(firstId)).sizeReport.mediaBytes).toBe(mediaFiles.reduce((n, [, bytes]) => n + bytes.length, 0));+ const changed = await archive(await begin({ ...options, mediaProfile: 'web-1080p', includeWebm: false }));+ const changedAssets = JSON.parse(changed.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;+ expect(changedAssets.entry.file).not.toBe(assets.entry.file);+ expect(changedAssets.entry).not.toHaveProperty('alternatives');+ expect(encode.mock.calls.filter(([args]) => args.args.includes('libx264'))).toHaveLength(2);+ expect(await readFile(source)).toEqual(original);+ });++ videoIt('preserves silent soundtracks and clips without audio in web profiles', async () => {+ const silent = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' }));+ const silentAssets = JSON.parse(silent.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;+ const output = join(PATHS.videos, 'without-audio.mp4');+ expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: ['-nostdin', '-y', '-v', 'error',+ '-i', join(PATHS.videos, 'independent-name.mp4'), '-an', '-c:v', 'copy', output] })).toEqual({ ok: true });+ loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'without-audio.mp4' })));+ const noAudio = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' }));+ const noAudioAssets = JSON.parse(noAudio.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;+ expect(noAudioAssets.entry.file).not.toBe(silentAssets.entry.file);+ await writeFile(output, noAudio.files.get(noAudioAssets.entry.file));+ const streams = JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', output], { timeout: 10_000 }).toString()).streams;+ expect(streams.map(stream => stream.codec_type)).toEqual(['video']);+ expect(noAudioAssets.holds[0].audioOccupancy).toEqual(silentAssets.holds[0].audioOccupancy);+ });++ videoIt('drains cancelled and failed encoder children before exposing terminal failure without an artifact', async () => {+ const realRun = ffmpeg.runFfmpegProcess;+ const started = Promise.withResolvers();+ let drained = false;+ vi.spyOn(ffmpeg, 'runFfmpegProcess').mockImplementation(async options => {+ const pending = realRun({ ...options, args: ['-nostdin', '-v', 'error', '-f', 'lavfi', '-i',+ 'color=c=blue:s=32x32:r=10', '-f', 'null', '-'] });+ started.resolve();+ const result = await pending;+ drained = true;+ return result;+ });+ const id = await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' });+ await started.promise;+ const cancelled = await request(app()).delete(`/api/fableloom/example-loom/export/${id}`);+ expect(cancelled.status).toBe(200);+ expect(cancelled.body).toMatchObject({ status: 'failed', error: { code: 'EXPORT_CANCELLED' } });+ expect(drained).toBe(true);+ expect(cancelled.body).not.toHaveProperty('downloadUrl');+ await expect(stat(join(PATHS.data, 'cache/fableloom-exports', id, 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });+ await expect(stat(join(PATHS.data, 'cache/fableloom-exports', id, 'work'))).rejects.toMatchObject({ code: 'ENOENT' });+ vi.spyOn(ffmpeg, 'runFfmpegProcess').mockImplementation(options => realRun({ ...options,+ args: ['-nostdin', '-v', 'error', '-f', 'lavfi', '-i', 'color=s=32x32:d=0.1', '-c:v', 'not-an-encoder', '-f', 'null', '-'] }));+ const failedId = await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' });+ expect(await terminal(failedId)).toMatchObject({ status: 'failed', error: { code: 'EXPORT_TRANSCODE_FAILED' } });+ await expect(getFableLoomExportDownload(loom.id, failedId)).rejects.toMatchObject({ code: 'EXPORT_NOT_READY' });+ await expect(stat(join(PATHS.data, 'cache/fableloom-exports', failedId, 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });+ });+videoIt('refuses unapproved media by default and records draft flags only after explicit opt-in', async () => {const node = loom.episodes[0].nodes[0];node.visualCanon.storyboardImageApproved = false;@@ -232,7 +336,7 @@ describe('portable FableLoom export boundary', () => {it('refuses unsupported and malformed options before creating jobs', async () => {for (const input of [{ includePlayer: true }, { includeCharacters: true }, { includeVoice: true },- { mediaProfile: 'webm' }, { mediaProfile: { width: 100 } }, { allowDraft: 'yes' },+ { mediaProfile: 'webm' }, { includeWebm: true }, { includeWebm: 'yes' }, { mediaProfile: { width: 100 } }, { allowDraft: 'yes' },{ episodeIds: [] }, { episodeIds: ['episode-one', 'episode-one'] }, { destination: sourcePath }]) {const response = await request(app()).post('/api/fableloom/example-loom/export').send(input);expect(response.status, JSON.stringify(input)).toBe(400);