Skip to content

feat(fableloom): add entry, hold-loop, and transition playback assets (#5382) - #5401

Merged
atomantic merged 2 commits into
mainfrom
claim/issue-5382
Aug 29, 2026
Merged

feat(fableloom): add entry, hold-loop, and transition playback assets (#5382)#5401
atomantic merged 2 commits into
mainfrom
claim/issue-5382

Conversation

@atomantic

Copy link
Copy Markdown
Owner

Summary

Implements entry clips, hold-loop variations, transition-specific exits, and audio-occupancy validation for FableLoom interactive narratives (part of #5377).

  • Backward-Compatible Asset Model: Retains legacy videoHistoryId fallback while introducing playbackAssets (entryVideoHistoryId, holdLoopVideoHistoryIds, exitByTransition, audioOccupancy, provenance) and interactionWindow (enabled, protagonistCharacterId, protagonistPresence, audioTarget, ambientDuckDb, holdLoopRotation).
  • Deterministic 4-Phase Playback State Machine: Models entry, hold, exit, and ended phases on the player surface and backend resolver with hold-loop rotation (deterministic, shuffle, sequential) and transition exit clip rehearsing before node advancement.
  • Audio Occupancy & Live Conversation Safety: Strictly validates audio manifests across character dialogue, music, and author-marked blocking effects (safeForLiveVoice is enforced false if dialogue or blocking sound effects are present). Calculates ambient ducking factors (-8 dB default) during live interaction.
  • Deterministic Production Readiness Inspection: Preflight analyzers (inspectNodeProductionReadiness, inspectEpisodeProductionReadiness) inspect scenes and report actionable findings on the canvas, node editor, and validation panel without AI provider calls.

Key Changes

  • server/lib/fableLoomPlayback.js & server/lib/fableLoomLimits.js: Pure helpers for audio occupancy validation, track muxing, ambient ducking math, deterministic asset resolution across phases, and production readiness analyzers.
  • server/lib/fableLoomValidation.js: Zod validation schemas for audioOccupancySchema, playbackAssetsSchema, and interactionWindowSchema.
  • server/services/fableLoom/records.js: Node sanitizers, patch handlers, and attachNodePlaybackAsset service helper.
  • server/routes/fableLoom.js: Surface production readiness on episode validation and node readiness endpoint.
  • client/src/components/fableloom/LoomPlayPanel.jsx: Rehearsal player running the 4-phase state machine, hold loop rotation, transition exit clip playback, live voice window indicator, and inspection details drawer.
  • client/src/components/fableloom/LoomNodeEditor.jsx: Live interaction controls, ducking slider, hold rotation selector, and readiness findings alert.
  • client/src/components/fableloom/LoomValidationPanel.jsx: Production readiness section in episode analysis.

Closes #5382

@atomantic
atomantic merged commit 5fe9b50 into main Aug 29, 2026
7 checks passed
@atomantic
atomantic deleted the claim/issue-5382 branch August 29, 2026 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add FableLoom entry, hold-loop, and transition playback assets

1 participant