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

> Learn how cinematic scene tours are authored as declarative scene recipes and played back by the SceneDirector runtime for automated social clip generation in God's Eye View.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: internals
- Published: 2026-08-29

---

**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](https://github.com/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.

```javascript
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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:

```javascript
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:

```html
<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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scenes/recipes.js) store cinematic tours as declarative JavaScript objects containing ordered shot arrays
- **Policy validation** via [`src/scenes/scenePolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scenes/scenePolicy.js) enforces layer exclusivity and configuration integrity before playback
- **The `SceneDirector`** class in [`src/scenes/director.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.