Skip to content

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

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.md
index 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 existin
optional 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/video
root, refuse escaping symlinks and snapshot bounded regular-file bytes. No
history ID is reconstructed as a filename. Input changes during a read fail
the 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 are
removed; 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 through
final status persistence and scratch cleanup.
Prepared buffers are retained once by content hash, with a 256 MiB aggregate
budget; 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 most
one 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.js
new file mode 100644
index 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.js
index 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 pin
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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, approval
state 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 not
available in this package version. Your host owns free-text resolution, TTS and
transport, 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.js
index 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);