Skip to content
/
Video Generation and the...
Last updated

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:

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

Or at the template level using customTemplate.videoSourcesByOrder (see Using Templates).

Available values:

ValueDescription
stock_footageSearch stock video libraries
workspace_assetsSearch your uploaded workspace media
generate_from_imageGenerate a still image, then animate it
generate_from_textGenerate 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:

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

Providing scene videos directly

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

"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:

"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 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 for details.

Previous page
Next page