# Video Generation and the Media Fallback System

Once the script is ready, Shuffll assembles visuals for each scene. Because not every scene will have explicit media provided, Shuffll uses a prioritised fallback system to find the best available source.

## How media is selected for each scene

For every scene, Shuffll works through the following sources in order. As soon as a source produces a result, it stops and moves to the next scene.


```
1. Videos you provided  (customTemplate.scenes[].videosToAdd)
2. Stock footage        (searched by scene content)
3. Workspace assets     (your uploaded media library)
4. Image → Video        (Stability AI generates a still, then it is animated)
5. AI video generation  (full clip generated from the scene script)
```

This means that if you explicitly attach a video to a scene, it will always be used. If you don't, Shuffll searches stock footage, then your workspace, and finally generates something from scratch.

## Controlling the fallback order

You can override the default order at the project level using `videoSourcesPipeline`:


```json
"videoSourcesPipeline": ["workspace_assets", "stock_footage", "generate_from_text"]
```

Or at the template level using `customTemplate.videoSourcesByOrder` (see [Using Templates](/guides/workflow-templates)).

**Available values:**

| Value | Description |
|  --- | --- |
| `stock_footage` | Search stock video libraries |
| `workspace_assets` | Search your uploaded workspace media |
| `generate_from_image` | Generate a still image, then animate it |
| `generate_from_text` | Generate a video clip directly from the scene description |


Omitting a source from the pipeline disables it entirely. For example, to use only your own workspace assets and generate when nothing is found:


```json
"videoSourcesPipeline": ["workspace_assets", "generate_from_text"]
```

## Providing scene videos directly

Use `customTemplate.scenes[].videosToAdd` to pin specific media to a scene:


```json
"customTemplate": {
  "id": "template_id_here",
  "scenes": [
    {
      "id": "scene_001",
      "videosToAdd": [
        {
          "url": "https://cdn.shuffll.com/.../my-clip.mp4",
          "isMaster": true,
          "stagePositionNumber": 1
        }
      ]
    }
  ]
}
```

- `url` — a public URL or an `uploadPath` from a workspace asset
- `isMaster` — if `true`, this clip drives the scene duration
- `stagePositionNumber` — the layer/position on the scene canvas (1-indexed)


## Still images in scene overlays

The same fallback concept applies to image slots in scene templates. Control the order using `imagesSourcePipeline` at the project level:


```json
"imagesSourcePipeline": ["workspace_assets", "stock_footage", "generate_from_text"]
```

**Available values:** `stock_footage`, `workspace_assets`, `generate_from_text`.

## Using your own assets

Upload media to your workspace using `POST /auth/workspace/{workspaceId}/assets`, then reference the returned `uploadPath` directly in `videosToAdd[].url`. See [Assets](/apis) in the API reference.

You can also pass `customTemplate.assets` with a list of external URLs — Shuffll will download, analyse, and intelligently map them to the most appropriate scenes. See [Using Templates](/guides/workflow-templates) for details.