How Cinematic Scene Tours Are Authored and Played Back for Social Clip Capture in God's Eye View

God's Eye View (GEV) implements cinematic scene tours as declarative scene recipes—JSON-like JavaScript objects that define sequential camera shots, layer visibility, and annotations, executed by the SceneDirector runtime for automated social clip generation.

The bilawalsidhu/gods-eye-view repository enables automated camera flythroughs and social media clip creation through a data-driven architecture. This system decouples tour authoring from playback execution, allowing content creators to define complex camera motions without modifying the rendering engine. The implementation centers on declarative scene recipes validated by policy helpers and executed by a dedicated director class.

Declarative Scene Recipes: The Authoring Format

All cinematic tours are defined as static data structures in src/scenes/recipes.js. The system exports a SCENE_RECIPES array containing plain JavaScript objects that describe complete camera journeys.

Each recipe requires three core properties:

• id – A unique string identifier used to trigger the tour
• title – Human-readable label displayed in the UI
• shots – Ordered array defining camera destinations, timing, and visual state

Individual shots specify precise camera control parameters including position (latitude, longitude, height), orientation (heading, pitch, roll), duration in seconds, and layer activation states. The format supports optional per-shot annotations and post-processing effects.

export const SCENE_RECIPES = [
  {
    id: 'sunrise-over-city',
    title: 'Sunrise Over City',
    shots: [
      {
        destination: { lat: 37.78, lon: -122.42, height: 15000 },
        orientation: { heading: 0, pitch: -0.3, roll: 0 },
        duration: 8,
        layers: { flights: true, satellites: false }
      },
      {
        destination: { lat: 37.80, lon: -122.45, height: 2000 },
        orientation: { heading: 45, pitch: -0.2, roll: 0 },
        duration: 5,
        layers: { flights: false, satellites: true },
        annotation: 'Golden Gate Bridge at sunrise'
      }
    ]
  }
];

Validating Tour Configurations with Scene Policy

The src/scenes/scenePolicy.js module enforces data integrity through helper functions sceneLayerPlan and stripSceneTrackingParams. These utilities ensure that each shot only manipulates layers it explicitly declares and that the overall scene adheres to GEV's exclusivity rules.

Validation occurs before playback initialization, preventing runtime errors from malformed recipes. The policy layer confirms that layer states transition cleanly between shots and that no invalid tracking parameters persist in the final scene configuration.

The SceneDirector Playback Engine

Runtime execution is handled by the SceneDirector class defined in src/scenes/director.js. This engine maintains three primary responsibilities:

• listScenes() – Returns available recipes for UI population
• getPlaybackStatus() – Tracks current playback state and progress
• startScene(sceneId, { single: true }) – Executes a specific tour by ID

The { single: true } configuration flag is critical for social clip workflows. When enabled, the director automatically halts after the final shot completes, returning the viewport to a static state optimal for screenshot or video capture.

Triggering Playback via Voice and Action Commands

User interaction flows through the control_scene command implemented in src/voice/gevActions.js. The action runner parses command arguments including action: "play" and sceneId: "<id>", validates the request against available recipes, and delegates execution to the director.

Integration requires initializing the action runner with a director instance:

import { createGevActionRunner } from './src/voice/gevActions.js';

const runner = createGevActionRunner({
  viewer,
  styleManager,
  dataManager,
  sceneDirector: new SceneDirector(viewer)
});

// List available cinematic scene tours
const listResult = await runner.runAction('control_scene', { action: 'list' });
console.log('Available scenes:', listResult.scenes);

// Play a specific tour for social clip capture
const playResult = await runner.runAction('control_scene', {
  action: 'play',
  sceneId: 'sunrise-over-city'
});

Social Clip Capture Workflow

The complete workflow for generating shareable content follows a deterministic sequence. First, the user or automated script issues a "play" command targeting a specific scene ID. The SceneDirector advances through each shot automatically, interpolating camera positions and toggling layer visibility according to the recipe.

While the cinematic scene tour runs, the capture system records the viewport. Because the scene initiates with { single: true }, playback terminates after the last shot concludes, leaving the final frame ready for extraction. This design ensures consistent, repeatable clip generation without manual camera manipulation.

UI elements can trigger this workflow directly:

<button id="run-scene-btn" data-scene-id="sunrise-over-city">Run Scene</button>
<script>
document.getElementById('run-scene-btn').addEventListener('click', async (e) => {
  const sceneId = e.target.dataset.sceneId;
  await runner.runAction('control_scene', { action: 'play', sceneId });
});
</script>

Summary

• Scene recipes in src/scenes/recipes.js store cinematic tours as declarative JavaScript objects containing ordered shot arrays
• Policy validation via src/scenes/scenePolicy.js enforces layer exclusivity and configuration integrity before playback
• The SceneDirector class in src/scenes/director.js executes tours with startScene(sceneId, { single: true }) for single-run capture sessions
• Voice and action commands in src/voice/gevActions.js provide the primary interface for triggering playback programmatically
• Social clip generation relies on the { single: true } flag to ensure tours run once and stop automatically after the final shot

Frequently Asked Questions

What file format are cinematic scene recipes stored in?

Scene recipes are stored as native JavaScript modules exporting the SCENE_RECIPES array from src/scenes/recipes.js. Each recipe is a plain object containing metadata (id, title) and an ordered shots array defining camera movements, durations, and layer states.

How does the SceneDirector know when to stop playback?

The startScene() method accepts a configuration object where { single: true } instructs the director to run the sequence exactly once and halt immediately after the final shot completes. Without this flag, the director might loop or transition to another state.

Which functions validate that a scene configuration is valid?

The src/scenes/scenePolicy.js module exports sceneLayerPlan and stripSceneTrackingParams helpers that validate shot-level layer declarations and remove invalid tracking parameters before the SceneDirector begins execution.

Can cinematic tours be triggered from voice commands?

Yes. The control_scene action in src/voice/gevActions.js exposes play, pause, and list operations that integrate with the voice recognition system. The action runner accepts action: "play" with a sceneId parameter to initiate specific tours without direct UI interaction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}