theater.yaml

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.

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

Minimum screen time for each image or animation. Default: 8. A ready visual appears immediately when the current visual has already had this much screen time and the queue is empty. Set to 0 or a negative value for manual queue advancement.

safety_reduction boolean

When enabled, runs prompt cleanup on image generation prompts to reduce negative or restraining safety phrasing. Default: false.

How the canvas visual queue works

Saved images, generated images, and animations share a queue in canvas state. The first visual appears immediately. Later ready visuals wait only for the current visual's remaining minimum screen time, then take turns in arrival order. Each source keeps its newest waiting visual: a replacement retains that source's queue position without discarding another source's work. With the three tool sources, at most three visuals wait. A timer runs only while the queue contains a waiting visual.

With an 8-second minimum, a visual ready after the current visual has been shown for 12 seconds appears immediately. If a generated image and an animation arrive 2 and 3 seconds after a new visual, they appear at 8 and 16 seconds respectively. Pinning the canvas clears the queue; an explicit orator image override clears waiting visuals and displays the requested image immediately.

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

Shared minimum interval between show_image and create_image executions. Default: 9. Starts when execution begins, overlapping generation rather than adding a delay after it. Calls during cooldown or generation return promptly; the latest call to either tool replaces the single pending request. Generation finishes before another image-tool execution starts. Failed requests clear the cooldown.

The tool cooldown controls work admission; the canvas queue controls screen time. The default 9-second shared cooldown overlaps generation. Once ready, an image waits only for the current visual's remaining screen time and any sources ahead of it in the queue. Long tool cooldowns therefore often allow immediate display, without a fixed cycle tick adding latency. Reduce cycle_length to shorten screen time during bursts; reduce the shared cooldown to admit fresh requests sooner, at the cost of more generation.

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 H3 Max Turbo 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.

game_tool

This advanced feature is off by default. Build a game package in the theater editor or an IDE, then explicitly enable live-agent play outside Adventure Mode with a valid game/game.yaml. The existing game.yml and game.json alternatives are supported.

enabled boolean

Adds view_game_instructions, view_game_state, get_available_actions, and take_game_action when a playable package is loaded. Default: false.

Triggering player actions prompt a live-agent response. The agent uses the package's Narratron actions and current revision. See Game Packages for the authoring contract.

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.

notepad

Configures notepad_tool for normal narration. Adventure Mode uses planning.yaml and ignores this section.

max_stickies integer

Maximum sticky notes, clamped from 1 to 10 and raised to retain every required topic. Default: 5.

initial_stickies mapping or list

Initial topic-to-information pairs, or entries with topic and info.

required_stickies list or mapping

Topics always retained; a mapping can supply their initial values.

hidden_stickies list of strings

Topic names hidden until the sticky widget's visibility toggle reveals them. In Adventure Mode, set hidden: true on each topic in planning.yaml.

notepad:
  max_stickies: 5
  initial_stickies:
    Current Scene: "The observatory"
  required_stickies:
    - Current Scene
  hidden_stickies:
    - Current Scene

story_planning

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

input_cycle_duration number, seconds

Minimum interval between input batch starts. The first input starts immediately. Subsequent spoken actions and game updates accumulate in order until both the active batch and its interval finish. Zero processes inputs immediately in one serialized worker. Defaults to 15 seconds when omitted or null.

output_cycle_duration number, seconds

Minimum display time for each narration/dialogue scene, independent of input collection. Default: 15 seconds. The first output appears immediately; newer responses replace the waiting output without extending the current display time. Outputs may be skipped but never shown in reverse input order. Zero shows every ready response immediately.

adventure_mode boolean

Enables player-action resolution through the story planner. Default: false.

history_event_limit nonnegative integer

Maximum combined history of completed player/game actions, story outputs, and successful foreground lore reads for the responder, recorder, and planner. Default: 20 events; zero disables history. Inputs, outputs, and lore reads count separately. The unified story journal supplies one chronological view. Previous agent conversations are not replayed; current tasks, state, and active tool exchanges remain available. Role documents stay private.

history_chunk_size positive integer or null

Number of oldest history events discarded when the combined stream exceeds history_event_limit. Omitted or null uses half the maximum, at least one; an explicit value cannot exceed the maximum. With defaults, history grows to 20 events, drops 10 on overflow, then grows again. Each agent invocation keeps a frozen history prefix through tool continuations to preserve cache reuse.

enable_dice boolean

Allows responder dice rolls and hidden procedural rolls for story planning. Default: true when omitted. Set to false to resolve outcomes without dice.

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, 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.

enforce_structured boolean

Requires a nonempty planning.yaml contract and validates sticky updates in Adventure Mode. Default: true. All declared topics are required and pinned in contract order; capacity includes every topic. Set to false to let recorder and planner create and update shared freeform topics without a contract. Declared topics retain ownership and field validation. Freeform topics are visible by default and older optional notes are evicted at capacity; at least one freeform slot remains available alongside required topics.

Example: durable adventure context

story_planning:
  adventure_mode: true
  auto_begin: true
  enforce_structured: true
  input_cycle_duration: 5
  output_cycle_duration: 15
  history_event_limit: 20
  history_chunk_size: 10
  style: "Tense science-fiction mystery; setbacks are fair and consequential."
  require_user_input: true

Keep sticky contracts in a separate planning.yaml. Every topic has one owner: recorder for established facts or planner for contingent future developments. Each fields entry contains string description and initial values; quote numeric and boolean values. Omit render to display field: value | field: value in field order, or provide a custom template.

"Current Location":
  owner: recorder
  description: "Established location of the player."
  initial: "Aboard the Starling"

"Upcoming Encounter Suggestion":
  owner: planner
  hidden: true
  description: "One contingent obstacle or opportunity."
  fields:
    encounter:
      description: "Next possible encounter"
      initial: "A distress signal near the comet"
    story_goal:
      description: "Meaningful choice for the player"
      initial: "Choose whether to investigate"
    drama:
      description: "Stakes grounded in established facts"
      initial: "The ship is low on fuel"

Author three independent pinned guides: lore/RESPONDER.md for narration and action resolution, lore/RECORDER.md for factual notes and validated game actions, and lore/PLANNER.md for future plans. Each role can read only its own guide. Put shared facts and mechanics in separate lore documents, with a roadmap in each guide.

speech

Controls speech synthesis delivery settings for Adventure Mode character voicing. The underlying TTS provider and model are application-wide operational settings defined in app.yaml, which override corresponding fields here.

voice_language_code string

Language and locale code used to select matching character voices from the voice library (for example, en-US or en-GB). Default: en-US.

accent_augmentation boolean

When enabled, any character accent voice tags (such as accent=British or accent=Scottish) are automatically duplicated into structured delivery direction and style instructions for the speech synthesizer so subtle accents are clearly pronounced throughout delivery. Default: true.

Example: character speech delivery

speech:
  voice_language_code: "en-US"
  accent_augmentation: true

chat

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

cooldown_duration number, seconds

Minimum time between chat-tool updates. Default: 20.