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
FableLoom portable export v1
FableLoom exports authored stories and existing rendered media for an author's own external host. PortOS remains private. Exports never upload, deploy, expose PortOS, fetch a media URL, call a provider, or generate new creative media.
API
An operator starts a job with POST /api/fableloom/:id/export:
{"episodeIds":["example-episode"],"allowDraft":false,"mediaProfile":"source"}
Omit episodeIds for all episodes. Selections are unique and retain authored
episode order. Unknown options, wrong types and unknown episode IDs are refused.
The response is 202 {"jobId":"<uuid>"}. Read
GET /api/fableloom/:id/export/:jobId for status, progress, validation findings,
expiry and a size report. A completed job supplies a relative downloadUrl for
GET /api/fableloom/:id/export/:jobId/download; downloads require operator
authority, including valid delegated agent sessions. Jobs cannot be read or
downloaded through a different loom. Instance authentication retains its existing
optional policy; no export endpoint is always-public.
includePlayer:true adds the dependency-free player/ reference client
described in the runtime contract. includeVoice:true without
includeCharacters:true is refused (EXPORT_VOICE_REQUIRES_CHARACTERS).
Character files and voice reference audio are explicit opt-ins, off by default.
includeWebm:true on the source profile is refused
(EXPORT_OPTION_UNSUPPORTED). 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
The job snapshots the authored record, selected episodes, video history and linked universe. It reuses graph, outline and production validation. All reachable scenes need a still and an entry clip. Decision scenes also need holds; legacy entry/video assets may supply their hold. Attached exit clips must exist; an absent exit means a direct cut under runtime v1.
A still needs its existing storyboard approval. Video needs the loom's current
delivery approval, which record mutations invalidate. Each asset also needs
locked visual-conditioning provenance. Missing provenance, unapproved, draft
and degraded assets fail by default. allowDraft:true permits those approval
conditions and records explicit draftFlags per media use. It does not relax
graph, outline, production, missing media, encoding, occupancy, path or size
failures. Enabled live holds require verified speech-safe occupancy; intervals
cannot exceed the actual clip duration.
Character and voice opt-ins
The default package has no characters/ members and no voice bytes.
includeCharacters:true adds characters/<id>.json for the canonical cast:
the loom protagonist, when one is set, and characters staged on reachable
scenes (visual appearances and interaction speakers). Unreachable scenes and
other universe characters stay out. Each file projects persona and speech
notes (personality, speechAccent, speechPattern, mannerisms),
pronunciation anchors (term and pronunciation only), safety/never-say
notes, and play-turn inputs for contract 1.0.0 (prompt id
fableloom-play-turn). Scene prose and choices stay in the manifest.
Background, secrets, visual identity, engine voice presets, adapters, LoRAs,
local paths and session history are not projected.
Portable character approval is voiceCanon.approved. A missing or unapproved
canon fails with EXPORT_CHARACTER_DRAFT unless allowDraft:true, which
records draftFlags of unapproved (a voice-canon object exists) or
unknown (it does not) and still does not invent approval. An empty cast
(EXPORT_CAST_MISSING), a character missing from the universe
(EXPORT_CHARACTER_MISSING), or a non-portable id (EXPORT_CHARACTER_ID)
still fails. Those findings do not echo a non-portable id.
includeVoice:true requires the character opt-in. For each exported character
it selects exactly one voice profile whose approval status is approved,
whose universe and character binding match, and whose interactive route is
enabled. Zero matches fail with EXPORT_VOICE_UNAPPROVED. More than one fails
with EXPORT_VOICE_AMBIGUOUS. Reference bytes must be a managed audio
basename (wav, mp3, flac, ogg, or m4a) inside that profile's source
directory, and the bytes must match the recorded sha256. The package stores
media/<sha256>.<ext> plus a voices row: character id, relative file,
content hash, byte count, approval, consent, license posture and voice-canon
source policy. It does not store the profile id, engine, model, transcript,
checkpoint, local path or approval timestamp.
A reference is exportable when performer consent is confirmed, or when its
license posture is generated-original-voice, licensed, or designed. A
cloned profile, or a consented-performance posture, without confirmed
consent fails with EXPORT_VOICE_CONSENT_MISSING. Unlabeled or absent audio
fails with EXPORT_VOICE_REFERENCE_MISSING. A hash mismatch fails with
EXPORT_VOICE_REFERENCE_MISMATCH. A path that leaves the voice library fails
with EXPORT_VOICE_REFERENCE_INVALID. allowDraft does not package
unapproved, unconsented, ambiguous or missing voice bytes.
The host README states that character files and any voice bytes are inputs for
the host's own resolver and TTS. The package does not grant PortOS access and
contains no PortOS URL, credential or callback. Set includePlayer: true to
include the standalone reference player described below.
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. 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. Audio too short or sparse for a finite integrated-loudness measurement uses peak normalization to −1.5 dBTP without padding its duration. Discarded subtitle/data tracks do not extend the retained picture/audio duration. 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 authored metadata, ordered episodes, reachable graphs and playback roles. Media uses only content hashes and relativemedia/<sha256>.<ext>references, withdurationMs,loopableand projected audio occupancy. WithincludeCharacters,characterslists each cast member's id, role andcharacters/<id>.jsonpath. The default manifest omits that key.characters/<id>.json: the portable character projection, only whenincludeCharactersis set.provenance.json: per-use content hash, provider/model labels, parameter hash, approval and conditioning status, draft flags, and encoding provenance.charactersis present only with the character opt-in.voicesis present only withincludeVoice.media/: deduplicated, metadata-free scene media, plus approved voice reference audio whenincludeVoiceis set.runtime-v1.mdandREADME.md: the versioned playback and hosting contracts. The README tells the host that it owns TTS and that the package grants no PortOS access.player/whenincludePlayeris set: static HTML, CSS and scripts that readmanifest.jsonand run runtime v1 in the browser. That directory has no instance data, credential, or authoring-service address.
All JSON object keys and ZIP member order are stable. ZIP timestamps are fixed. The same source bytes and authored snapshot, with the same PortOS/media-tool versions, produce identical manifest, media hashes and ZIP bytes. There are no job IDs, timestamps, instance/peer IDs, local paths, credentials, provider configuration, adapters, LoRAs, source prompts, sessions or transcripts in the package. Only authored scene/choice text, the documented character projection and approved voice-reference bytes leave the authoring record.
Lifecycle and failures
Jobs and ZIPs are regenerable ephemeral-file cache entries. They expire after
24 hours; starting another export evicts expired entries and then the oldest
terminal entries to keep at most four jobs. Four queued/running jobs return
EXPORT_QUEUE_FULL. Each asset is capped at 64 MiB and each ZIP at 256 MiB.
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 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,
never a raw filesystem/encoder error or source path. It has no download URL.
An interrupted job is failed on the first read after restart; it is not replayed.
An expired job returns 410 EXPORT_EXPIRED; an unavailable/failed/not-yet-ready
artifact cannot be downloaded. Exporting again is the recovery path.