Docs / Configuration reference

theater.yaml

The per-theater configuration file. It is created from theater_default.yaml, then merged with the values you set here when a theater starts.

Getting started

theater.yaml contains the settings for one theater. Start with the generated defaults, then change the values that fit your show.

Use spaces for indentation; YAML does not tolerate tabs. Restart an already-running theater session after saving configuration changes.

live_agent:
  special_instructions: "Keep the narration mysterious and concise."
visuals:
  style: "rain-soaked art nouveau fantasy"
story_planning:
  adventure_mode: true
  auto_begin: true
  style: "dangerous, fair, and player-agency-first"

live_agent

Controls the live narrator’s behavior and Gemini Live session options.

proactivity boolean
Enables proactive audio behavior in the live model. Default: false.
affective_dialog boolean
Enables affective dialogue behavior in the live model. Default: false.
special_instructions string
Additional instructions inserted into the narrator’s prompt. Use this for voice, tone, boundaries, or presentation direction. An empty value omits this prompt section.

starting_image

Optional filename or alias for the first image shown on an otherwise blank canvas. The file must be an image in the theater’s references directory. Matching tolerates spaces and punctuation; if no match is found, Narratron logs a warning and leaves the canvas unchanged.

starting_image: "opening scene.jpg"

observability_tool

Optionally gives the narrator a tool to request an immediate canvas observation outside the regular observation cadence. When enabled, the model can use that observation to visually inspect the current canvas—such as the displayed scene, audience drawings, and other visible state—before continuing the story.

enabled boolean
Adds request_canvas_observability to the narrator’s toolset and permits model-requested visual inspection. Default: false.
cooldown_duration number, seconds
Minimum time between immediate observation requests. Default: 30. A successful request postpones the next regular observation.

visuals

Shared rendering direction for images and animations. The image model is selected globally in app.yaml; theaters customize the style and canvas pacing.

model string
Image-provider model identifier. This application-controlled setting is normally supplied from app.yaml.
style string
Appended to generated-image and animation prompts unless the prompt supplies its own style. Leave blank for no extra direction.
cycle_length number, seconds
Sets the visual-cycle interval. Set to 0 or a negative value to prevent the background timer from running.

How the visual cycle works

The cycle is a one-visual staging queue, not a slideshow of every generated asset. The first successful image or animation appears immediately and starts a timer. Later visual requests are staged as the single next visual, which is promoted on each cycle_length tick.

image_generation

Controls whether the narrator can create still images. Disabling generation still lets the narrator browse and display images in the theater’s references directory.

enabled boolean
Enables the create-image tool. Default: true.
cooldown_duration number, seconds
Minimum delay between image-generation requests. Default: 6.

animation

Enables narrator tools (create_animation and play_animation) to generate and display loop-ready animated scenes on the canvas. Supports multiple animation techniques—including AI text-to-video generation, depth-layered parallax, and 3-frame sequences—with automatic scene classification or forced overrides.

enabled boolean
Adds animation creation and playback tools to the narrator’s toolset. Default: false.
cooldown_duration number, seconds
Minimum delay between animation-generation requests. If omitted, it inherits the image tool’s cooldown. Default: 20 in the theater default.
forced_technique string or null
Forces a specific animation technique across the theater, bypassing LLM classification. Supported values: 'triframe', 'layered', 'video', or null. Default: null (automatic classification).

Animation techniques & classification

When forced_technique is null (the default), an internal LLM analyzes the narrator’s scene prompt and automatically chooses the best technique:

  • video: Chosen for cinematic, continuous motion or fluid natural action scenes (such as rushing rivers, billowing clouds, fluttering cloth, flying dragons, and atmospheric weather). Synthesizes an MP4 video clip.
  • layered: Chosen for scenic vistas, atmospheric backdrops, or high-energy single-moment climaxes. Generates a base still and decomposes it into multi-plane depth layers with parallax motion using FAL Qwen Layered.
  • triframe: Chosen for high-complexity motions and distinct narrative transitions. Generates a 3-frame sequence with clear action differences and smooth crossfades.

How the video technique works

The video technique provides full-motion cinematic scenes generated by AI text-to-video models:

  • Style inheritance & loop constraint: The video prompt automatically inherits the theater’s global visual style from image_generation.style. A loopable constraint is automatically appended (for example, Style: <style>, loopable) so the resulting clip visually matches still images and loops seamlessly.
  • Predictable pricing & app-controlled duration: Video clip duration is set and controlled globally at the application level (5 seconds) rather than configured per theater, keeping generation costs and credit pricing predictable and consistent.
  • Model backend: Utilizes MiniMax Hailuo fast text-to-video generation via FAL (fal-minimax-h3-turbo) to synthesize fluid, high-fidelity MP4 footage.
  • Playback & canvas rendering: Videos are saved locally in the theater’s animations/ folder alongside a video.json manifest, and registered under image aliases (<animation_id>_video and <animation_id>). The canvas and OBS overlay display them as auto-looping, muted HTML5 video elements with smooth crossfades into subsequent scenes.

Example: video animation configuration

animation:
  enabled: true
  cooldown_duration: 20
  # Force all animations to use the video technique, or leave null for automatic classification
  forced_technique: "video"

interactive_canvas

Allows the narrator to build interactive A2UI surfaces—such as status cards, grids, and action buttons—on the canvas.

enabled boolean
Adds interactive-canvas tools. Default: false.
max_surfaces integer
Maximum simultaneously active surfaces. The implementation clamps the value from 1 to 5. Default: 5.
cooldown_duration number, seconds
Minimum delay between canvas mutations. Default: 10.
In Adventure Mode, each completed story-planner turn unlocks one image or interactive-canvas mutation.

music

Configures playback from theater playlists and optional AI-generated music.

use_generated_music boolean
Enables the tool that generates original music. Default: false.
generation_cooldown number, seconds
Minimum delay between generated-music requests. Default: 90.
switch_cooldown number, seconds
Minimum delay between playback changes. Default: 15.
style string
Default prompt direction for generated music.

story_planning

Defines the Adventure Mode planner: its durable story context, planning horizon, pacing, and optional NPC speech.

adventure_mode boolean
Enables player-action resolution through the story planner. Default: false.
character_voicing boolean
With Adventure Mode, synthesizes generated NPC dialogue with stable assigned voices. It is ignored unless adventure_mode is true and contributes to voice usage.
text_beautification boolean
In Adventure Mode, applies expressive visual text effects (vibrating, scintillating, glitch, fonts) to high-energy narration and dialogue spans using TextBeautifier. Default: true.
style string
Guidance for the planner’s pacing, consequences, and narrative tone. Limited to 500 characters.
nodes_ahead integer
Upcoming plot beats the planner maintains. Clamped from 1 to 10. Default: 3.
max_named_elements integer
Maximum sticky-note story elements. Alias for max_sticky_notes; the effective value is clamped from 1 to 10, but never below the number of required stickies.
initial_elements mapping or list
Initial sticky notes. A mapping uses topic-to-information pairs; a list can contain objects with topic/name and info/content.
required_stickies list, mapping, or string
Sticky-note topics the planner must retain. A mapping can supply initial information. Required notes are restored if absent and are never evicted for ordinary notes.
hidden_stickies list of strings
Sticky-note topics hidden in the canvas UI view by default when hovering over the sticky notes widget. A toggle within that expandable allows players to reveal them on demand.
cooldown_duration number, seconds
Base delay between player actions unless action_cooldown_base_seconds is supplied. Default: 7.
require_voice_input boolean
Requires detected orator speech before the next player action is accepted. Default: true.
action_cooldown_words_per_second number
One extra second is added to the next action cooldown per this many words in the previous planner response. Values below 1 become 1. Default: 20.
action_cooldown_max_seconds number, seconds
Caps the total delay before the next action. It cannot be lower than the base cooldown. Default: 25.

Example: durable adventure context

story_planning:
  adventure_mode: true
  initial_elements:
    ship: "The Starling is damaged and low on fuel."
    captain: "Missing since the comet storm."
  required_stickies:
    - ship
    - captain
  hidden_stickies:
    - captain
  nodes_ahead: 4
  style: "Tense science-fiction mystery; setbacks are fair and consequential."
  require_user_input: false

chat

Controls pacing for the narrator’s chat/status tool.

cooldown_duration number, seconds
Minimum time between chat-tool updates. Default: 20.