Why Do Multi-Scene AI Videos Feel Like a Stack of Slides Instead of One Continuous Shot?

The Disjointed Video Problem: When Your AI Agent's Output Feels Like a Slideshow

You've built an AI agent that can generate video content. It can create individual scenes, add text overlays, and even animate elements. But when you stitch these scenes together, the final product feels... off. The eye's momentum dies at every cut. One scene slides in from the left, the next zooms in from the center, and a third fades in with a gentle wobble. Each transition feels like a hard reset, breaking the viewer's immersion. The video doesn't feel like a continuous, intentional camera move; it feels like a stack of independently-animated PowerPoint slides.

This is a common pain point for developers building AI agents that produce video or complex animations. The problem isn't a lack of technical capability for individual scenes. The issue is a lack of a unifying motion grammar. When scenes are authored in isolation—perhaps by different sub-agents or at different times—they follow no shared rules for how they enter, exit, or relate to each other spatially and temporally. The result is visual cacophony.

Why Does This Happen?

1. Isolated Authoring: Each scene is a self-contained unit. The exit animation of Scene A is designed without considering the entry animation of Scene B. There's no shared "vector ledger" dictating that if A exits moving left, B must enter moving left at a matching speed.
2. Default Animations: Animation libraries offer easy defaults like "grow-from-small" or "fade-in." These are convenient but create a mismatch. If Scene A exits by shrinking (a pull-back on the Z-axis), but Scene B enters by growing (a push-forward), you've created a mirrored vector—a jarring visual contradiction.
3. Idle Filler: When a scene has time to spare before its exit cue, the common solution is to add a gentle, looping "breathe" or "float" animation. This idle wobble reads as the video waiting, not performing. It's motion for motion's sake, not narrative motion.
4. No Causal Chain: Motions happen sequentially but not causally. An element might fly in, then suddenly a text box appears. There's no visible cause-and-effect chain (e.g., the flying element impacts a surface, causing the text to spring out).

What a Good Solution Should Change

A proper solution wouldn't just offer more animation presets. It would provide a high-level motion doctrine—a set of inviolable laws that govern all motion across a multi-scene composition. It would enforce:

• Continuity: A single, dominant direction (the "current") that carries the viewer's eye forward.
• Vector Matching: Strict rules that the exit vector of one scene determines the entry vector of the next (same axis, direction, and matched speed).
• Performance Over Idle: Every moment of motion must serve a purpose—advancing the story, reacting to a cause, or building toward a climax. No idle wobble.
• Seam Verification: A way to automatically check that these rules are followed before the final render, catching mismatches early.

This is where the motion-doctrine skill enters the picture. It's not an animation library. It's the rulebook that sits above all animation libraries, designed specifically to solve this disjointed video problem for AI agent workflows.

Introducing motion-doctrine: The High-Level Motion Law

The motion-doctrine skill is a gateway skill for the HyperFrames framework. Think of it as the constitution for your video's motion. You load it first, before composing any animation. Its purpose is to make a multi-scene video feel like one continuous camera move instead of a stack of slides.

It's important to understand what this skill is not. It is not a low-level animation toolkit. It doesn't provide functions like animateIn() or createKeyframe(). Instead, it provides the laws that dictate what those functions must do at every scene boundary (the "seam") and how every scene must perform between its entry and exit.

Core Principles of the Doctrine

The skill's documentation outlines several key laws. Here are the most critical ones for solving the disjointed video problem:

1. The Vector Law: This is the cornerstone. It states: How Scene A exits determines how Scene B enters.

   • Axis Consistency: If A exits on the X-axis, B must enter on the X-axis. No trading axes.
   • Direction Matching: Never mirror. If A exits by moving left (negative X), B must enter by moving left. A common violation is having A exit by shrinking (Z-axis pull-back) and B enter by growing (Z-axis push-forward). The doctrine's Z scale-sign rule forbids this.
   • Speed Matching: The entry's initial velocity should match the exit's final velocity. This is achieved through mirrored easing functions (e.g., exit with power4.in, enter with power4.out).
   • Mid-Motion Cut: The cut between scenes must happen while both are still moving. A scene that settles to rest before the cut, or starts from rest after it, is a "dead beat" that kills momentum.

2. The Current: Every film picks ONE dominant direction (the default is LEFT). This is the neutral "next beat" direction for forward progress. Other directions (Up, Z-forward, Z-backward) are reserved and must be justified by a narrative cause (a reveal, an arrival, a deeper push into a thought). You cannot run consecutive seams in opposing directions—that reads as a ping-pong error.

3. The Ban on Idle Wobble: This is a direct attack on the "breathe" animation problem. The doctrine states that motion must perform, not breathe. If a scene has time between its entry and exit, that time must be filled with one of several defined "sustained-motion routes" (e.g., a causal chain, a narrative beat). Idle sine loops are banned.

4. Causal Motion: Motion should be chained so each move is visibly launched by the last. A click causes a squash, which causes a spring release, which causes a flight, which causes an impact. Effects must start on the same frame as their cause.

5. The Seam Gate: This is the enforcement mechanism. The skill includes scripts (seam-stamp.mjs and seam-gate.mjs) that act as a build gate. You first create a vector ledger (ledger.json) that plans every seam. Then you run the stamp script to generate the master timeline. Finally, you run the verifier script. It checks for ledger consistency, vector matching, speed matching, zero overlap (no dissolves), and the Z-sign rule. If it doesn't exit with code 0, the seam is not done.

Evaluating if motion-doctrine Fits Your Workflow

This skill is a powerful but opinionated tool. It's not for every project. Here’s how to decide if it’s worth inspecting.

Best Use Cases

• Multi-Scene Narrative Videos: Explainer videos, product launches, tutorials, or any content where scenes must flow logically and visually.
• AI Agents Generating Video: If your agent's output pipeline involves composing multiple animated scenes or segments, this doctrine can enforce consistency.
• Teams Needing Visual Consistency: When multiple people or sub-agents are authoring scenes for a single video, the vector ledger acts as a single source of truth.
• Projects Using HyperFrames: This is a core part of the HyperFrames ecosystem. If you're already using that framework, this is a foundational skill.

When Not to Use It

• Single-Scene Animations: If your agent only ever produces one self-contained animation, the seam laws are irrelevant.
• Prototyping or Exploratory Work: The doctrine adds planning overhead (the ledger). For quick, throwaway prototypes, it might be overkill.
• Projects with No Animation: Obviously, if your agent outputs static images or text, this doesn't apply.
• When You Need Full Creative Freedom: The rules are strict. If your use case requires unconventional, "rule-breaking" motion for artistic effect, this doctrine will fight you.

What to Inspect Before Using

1. The Repository and Community: The skill is part of the heygen-com/hyperframes repository, which has significant community traction (36k+ stars). This suggests active development and a user base. Check the Issues and Discussions for common problems.
2. The License: It uses the permissive Apache-2.0 license, which is suitable for most commercial and non-commercial projects.
3. The Setup Context: This is a backend-api category skill. It's not a simple frontend component. It involves Node.js scripts (seam-stamp.mjs, seam-gate.mjs) and a specific authoring workflow (ledger → stamp → verify). Ensure your agent's build environment can accommodate this.
4. The Skill's Dependencies: The doctrine routes to other low-level technique skills like cut-the-curve (for the actual easing catalog) and oversized-cursor. You may need to load those as well for full implementation. The skill landing page has the route map.
5. Safety and Security: The security level is marked as "Low." The scripts are for authoring and verification, not for executing arbitrary code from untrusted sources. However, always review the scripts in the repository to understand what they do, especially if integrating into a CI/CD pipeline.

Practical Implementation: A Simplified Workflow

Let's outline how you might integrate this into an AI agent's video generation pipeline.

1. Planning Phase (The Ledger): Your agent (or a human planner) must first decide the narrative flow. For each transition (seam), it creates an entry in ledger.json:

   {
     "seam": 1,
     "cut_time": 5.2,
     "exit": { "axis": "x", "direction": "-1", "selector": "#scene1-container" },
     "entry": { "axis": "x", "direction": "-1", "selector": "#scene2-container" },
     "technique": "cut-the-curve:power4.in-out"
   }
   

   This encodes the vector law: both exit and entry use the X-axis, direction -1 (left), with a specific easing technique.

2. Generation Phase (Stamping): The agent runs the stamp script: node <skill_dir>/scripts/seam-stamp.mjs --ledger ledger.json --write index.html. This injects the master timeline and seam logic into the HTML file.

3. Authoring Phase (Performance): For each scene, the agent must now author animations that obey the doctrine. Between entry and exit, it must use a sustained-motion route, not idle wobble. It must chain motions causally.

4. Verification Phase (The Gate): Before rendering the final video, the agent runs the verifier: node <skill_dir>/scripts/seam-gate.mjs verify --ledger ledger.json --project .. If it fails, the agent must debug the scenes or the ledger until it passes.

5. Rendering: Only after passing the gate does the agent proceed to render the final video (e.g., using Puppeteer or FFmpeg, as suggested by the repository topics).

Conclusion: From Disjointed Slides to Continuous Motion

The feeling of a "stack of slides" in AI-generated videos stems from a lack of a governing motion grammar. The motion-doctrine skill provides that grammar. It's a set of high-level laws—vector matching, the current, performance over idle, causal chaining—that, when followed, create the illusion of a single, continuous camera move.

It introduces a planning step (the vector ledger) and a verification step (the seam gate), which adds rigor to the workflow. This makes it best suited for narrative, multi-scene video production where visual consistency and flow are critical. If your AI agent's output suffers from jarring cuts and inconsistent motion, inspecting this doctrine could provide the foundational rules needed to transform a slideshow into a film.