summerengine/summer/animated-loop

animated-loop — 5 Second Seamless Background Loop

A loop is the only video format that has to not have a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: take the shortest duration available, keep the motion ambient (no narrative, no big camera moves), use the fast model (ltx), and prompt for a composition where the first and last frames are functionally identical.

Duration is not a dial here. On ltx and kling, assets.generate_video renders only duration: 5 or duration: 10; every other value renders 5. So "drop to 3s to hide the seam" is not an option — 5s is the floor, and the seam has to be won in the prompt and the reference frame instead.

If the user wants a 5s punchy marketing shot, that's trailer-shot. If they want a 10s narrative cutscene, that's cinematic-cutscene. This skill is the one for video that has to disappear — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.

When to use

• "Looping background for the title screen."
• "Animated backdrop behind the logo on the splash."
• "Menu background — torchlit dungeon, just flicker and motes."
• "Looping ambient video for the pause screen."
• "Splash loop — fog over a forest."
• "Need a video that loops behind the level select."

When NOT to use

• Marketing shot for a trailer (5-10s with punch) — trailer-shot.
• Narrative cutscene with a beginning and end — cinematic-cutscene.
• Static splash image — generate with concept-art and use a TextureRect. A still is cheaper, lighter, and never seams.
• UI element animation (icons, button states) — those are GDScript Tween or sprite sheets, not video.
• A 10-second shot you want to "loop". That seam will be visible. Either accept a hard cut every 10s (ugly) or generate a 5s clip designed to loop.

Steps

1. Confirm the loop will be visible for a long time

Quick check — this loop will play on a screen the user might stare at for 30+ seconds. That means the loop point must be invisible. I'll take the 5s minimum and prompt for ambient motion (drift, flicker, shimmer) rather than a narrative beat. OK?

If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to cinematic-cutscene.

2. Pick the model — ltx first, always

For loops, ltx is almost always right. It takes ~30s, and short ambient motion is what it handles best. The premium models cost more credits and do not loop better.

This skill always passes imageUrl (step 3), which puts every call on the image-to-video route. kling-turbo and veo3 are text-to-video only; pairing either with an imageUrl is a 400 invalid_model, not a silent downgrade.

3. Lock the look with a reference still

The reference still doubles as the target loop frame. Generate it deliberately — the video model's first and last frames will gravitate toward the reference, which is exactly what you want for a closing seam.

assets.generate_image({
  prompt: "<subject>, ambient atmospheric scene, cinematic lighting, painterly, wide framing, balanced composition with no clear focal action",
  model: "nano-banana-2",
  aspectRatio: "16:9"
})

Set aspectRatio to the screen the loop fills (16:9, or 9:16 for a vertical mobile splash).

On the image-to-video route aspectRatio is not applied at all — the clip inherits the reference image's framing. So a vertical mobile splash needs a 9:16 reference image, and setting aspectRatio: "9:16" on the video call does nothing.

4. Prompt for loopable motion only

Loopable motion is continuous, ambient, directionless, or oscillating. Avoid anything with a beginning or end (a character entering, a sword swinging, a door closing).

Loopable verbs: drift, flicker, swirl, shimmer, sway, pulse, glow, rise, fall, wave, breathe, ripple.

Non-loopable verbs (avoid): walks, enters, appears, emerges, transforms, attacks, falls down, opens, closes.

assets.generate_video({
  prompt: "<subject from reference>, <ambient loopable motion>, slow continuous, looping, seamless, cinematic",
  model: "ltx",
  imageUrl: "<reference URL from step 3>",
  duration: 5,
  negativePrompt: "sudden movement, character action, narrative event, fade to black"
})

The phrase "looping, seamless" in the prompt biases the model toward stable first/last frames, and negativePrompt rules out narrative drift. Images have no negative prompt: put negations in the image prompt text.

aspectRatio is omitted deliberately: it is applied on the text-to-video path only, and this call passes imageUrl.

The call answers at once with { status: "running", job: { id } } and no URL. Call jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 }) until finished is true; only a done job's result holds the clip.

5. Inspect the seam

Watch the result and the seam (the cut between the last and first frame on replay). If the seam is visible:

• Most common cause: something moved across the frame and didn't return (a particle drifted off-screen, a cloud moved). Regenerate with slow continuous, returning motion, oscillating in the prompt.
• Second cause: lighting drifted. Regenerate with constant lighting, no time of day change.
• Third cause: the motion is simply too fast to close in the time available. You cannot shorten the clip — 5s is the minimum the API offers — so slow the motion in the prompt instead (very slow, barely perceptible drift).

If three regenerations don't seam-close, accept a small crossfade in the engine: set up two VideoStreamPlayer nodes and crossfade between them via a Tween. This is a fallback, not the goal.

6. Import and wire as a looping VideoStreamPlayer

Import the `.mp4` as it is; the import converts it. Summer Engine plays video only as Ogg Theora (.ogv) — there is no MP4 or WebM loader in the build — so every Summer import tool converts a video on the way in: summer_import_from_url, its batch, summer_import_asset_by_id and summer_import_asset. A clip Summer generated or stores converts on Summer's media host; any other video converts with ffmpeg on this computer when it has Theora, else on summerengine.com. The .ogv lands at the path you asked for with the extension swapped, and the answer names it in videoConversions and note:

summer_import_asset_by_id(assetId="<the clip's asset id>", path="res://assets/video/loops/title_screen_bg.mp4")
→ importedTo: res://assets/video/loops/title_screen_bg.ogv

Load the .ogv path from the answer, never the .mp4.

Then wire it in one script. scenePath is the exact scene to change:

summer_run_script(scenePath="res://ui/title_screen.tscn", source="""
func run(ctx):
    var loop_player = ctx.add_node("VideoStreamPlayer", "BackgroundLoop", null, {
        "stream": load("res://assets/video/loops/title_screen_bg.ogv"),
        "autoplay": true,
        "loop": true,
        "expand": true,
    })
    loop_player.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)   # the loop fills the menu
    ctx.get_scene_root().move_child(loop_player, 0)   # drawn first: the menu draws on top
    ctx.save_scene()
""")

Controls draw in tree order and later siblings render on top, so the logo and menu buttons come after the VideoStreamPlayer in the tree.

7. Mute the audio track

Loops should never have a baked audio track that loops with them — the audio seam will be even more obvious than the visual one. The video models don't generate audio anyway, but if you ever import a clip that has audio, mute it:

summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="volume_db", value=-80)

Score the menu separately with music-track.

Reference card — prompts that work

Pattern: <subject> + <ambient loopable motion> + <constant lighting> + "looping, seamless" + <stylistic anchor>. Keep under 40 words. Always pair with imageUrl.

Bad prompts and why

Anti-patterns

• Asking the model for a 10s loop. Past ~6s, identity drifts and the seam shows. duration=5 is both the floor and the right answer; 10 is the only other value the API accepts.
• Treating `assets.generate_video` as finished. It answers { status: "running", job } and no URL. Wait with jobs.wait before claiming a clip exists.
• Using `kling` for a loop. ltx is almost always right; short ambient motion is what it does best.
• Prompting narrative motion. "Hero draws sword" doesn't loop. Use ambient verbs.
• Forgetting `loop=true` on the `VideoStreamPlayer`. The clip will play once and freeze on the last frame.
• Forgetting to mute baked audio. If audio is on, the loop point becomes audible even if it's invisible.
• Expecting `aspectRatio` to reframe an image-to-video call. It is applied on the text-to-video path only. A portrait splash needs a portrait reference image — the argument does nothing here.
• Loading the `.mp4` path after an import. The import converted the clip to .ogv and saved it under that name; load() the .ogv path the answer names.
• Converting by hand. The import tools convert; a hand-made ffmpeg command also fails on builds without libtheora (Homebrew's default ffmpeg has none).

Edge cases