> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scene Transitions

> Add smooth transition effects between scenes to create professional, polished videos with visual continuity

This guide shows you how to add transition effects between scenes in your videos. Transitions provide smooth visual changes when moving from one scene to another, creating professional polish and visual flow that keeps viewers engaged.

## What You'll Learn

<CardGroup cols={2}>
  <Card title="Transition Types" icon="right-left">
    Choose from 10+ professional transition effects
  </Card>

  <Card title="Per-Scene Control" icon="sliders">
    Set different transitions for each scene
  </Card>

  <Card title="Visual Continuity" icon="film">
    Create smooth flow between scenes
  </Card>

  <Card title="Professional Polish" icon="sparkles">
    Enhance videos with polished transitions
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Multiple scenes in your video (transitions connect scenes)
* Basic understanding of scene configuration in Pictory API

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## How Scene Transitions Work

When you add transitions to your video:

1. **Transition Selection** - You specify a transition type for each scene
2. **Scene Boundary Detection** - System identifies where scenes connect
3. **Transition Placement** - Transition is applied at the end of each scene
4. **Effect Application** - Visual effect is rendered between scenes
5. **Duration Calculation** - Transition duration is automatically optimized
6. **Scene Stitching** - Scenes are seamlessly connected with transitions
7. **Video Rendering** - Final video includes all transitions between scenes

<Note>
  Each scene's `sceneTransition` parameter defines the transition effect that plays **when moving TO the next scene**. The last scene's transition is typically not used since there is no scene after it.
</Note>

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  const STORY_TEXT_1 =
    "AI is poised to significantly impact educators and course creators on social media.";
  const STORY_TEXT_2 =
    "By automating tasks like content generation, visual design, and video editing.";
  const STORY_TEXT_3 =
    "AI will save time and enhance consistency for content creators everywhere.";

  async function createVideoWithTransitions() {
    try {
      console.log("Creating video with scene transitions...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "video_with_scene_transitions",

          scenes: [
            // SCENE 1: Fade transition to Scene 2
            {
              story: STORY_TEXT_1,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              sceneTransition: "fade",           // Classic fade effect
            },

            // SCENE 2: Wipe right transition to Scene 3
            {
              story: STORY_TEXT_2,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              sceneTransition: "wiperight",      // Wipe moving right
            },

            // SCENE 3: No transition (last scene)
            {
              story: STORY_TEXT_3,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              sceneTransition: "none",           // Hard cut (or omit)
            },
          ],
        },
        {
          headers: {
            "Content-Type": "application/json",
            Authorization: API_KEY,
          },
        }
      );

      const jobId = response.data.data.jobId;
      console.log("✓ Video creation started!");
      console.log("Job ID:", jobId);

      // Monitor progress
      console.log("\nMonitoring video creation...");
      let jobCompleted = false;
      let jobResult = null;

      while (!jobCompleted) {
        const statusResponse = await axios.get(
          `${API_BASE_URL}/v1/jobs/${jobId}`,
          {
            headers: { Authorization: API_KEY },
          }
        );

        const status = statusResponse.data.data.status;
        console.log("Status:", status);

        if (status === "completed") {
          jobCompleted = true;
          jobResult = statusResponse.data;
          console.log("\n✓ Video with scene transitions is ready!");
          console.log("Video URL:", jobResult.data.videoURL);
        } else if (status === "failed") {
          throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
      }

      return jobResult;
    } catch (error) {
      console.error("Error:", error.response?.data || error.message);
      throw error;
    }
  }

  createVideoWithTransitions();
  ```

  ```python Python theme={null}
  import requests
  import time
  import json

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  STORY_TEXT_1 = (
      "AI is poised to significantly impact educators and course creators on social media."
  )
  STORY_TEXT_2 = (
      "By automating tasks like content generation, visual design, and video editing."
  )
  STORY_TEXT_3 = (
      "AI will save time and enhance consistency for content creators everywhere."
  )

  def create_video_with_transitions():
      try:
          print("Creating video with scene transitions...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'video_with_scene_transitions',

                  'scenes': [
                      # SCENE 1: Fade transition to Scene 2
                      {
                          'story': STORY_TEXT_1,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,
                          'sceneTransition': 'fade'           # Classic fade effect
                      },

                      # SCENE 2: Wipe right transition to Scene 3
                      {
                          'story': STORY_TEXT_2,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,
                          'sceneTransition': 'wiperight'      # Wipe moving right
                      },

                      # SCENE 3: No transition (last scene)
                      {
                          'story': STORY_TEXT_3,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,
                          'sceneTransition': 'none'           # Hard cut (or omit)
                      }
                  ]
              },
              headers={
                  'Content-Type': 'application/json',
                  'Authorization': API_KEY
              }
          )
          response.raise_for_status()

          job_id = response.json()['data']['jobId']
          print("✓ Video creation started!")
          print(f"Job ID: {job_id}")

          # Monitor progress
          print("\nMonitoring video creation...")
          job_completed = False
          job_result = None

          while not job_completed:
              status_response = requests.get(
                  f'{API_BASE_URL}/v1/jobs/{job_id}',
                  headers={'Authorization': API_KEY}
              )
              status_response.raise_for_status()

              status = status_response.json()['data']['status']
              print(f"Status: {status}")

              if status == 'completed':
                  job_completed = True
                  job_result = status_response.json()
                  print("\n✓ Video with scene transitions is ready!")
                  print(f"Video URL: {job_result['data']['videoURL']}")
              elif status == 'failed':
                  raise Exception(f"Video creation failed: {status_response.json()}")

              time.sleep(5)

          return job_result

      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")
          if hasattr(error, 'response') and error.response is not None:
              print(f"Response: {error.response.text}")
          raise

  if __name__ == '__main__':
      create_video_with_transitions()
  ```
</CodeGroup>

## Understanding the Parameters

### Scene Transition Configuration

| Parameter         | Type   | Required | Description                                                                               |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `sceneTransition` | string | No       | Transition effect applied when moving to the next scene. See available transitions below. |

<Warning>
  **Transition Direction:** The `sceneTransition` on Scene 1 defines the transition FROM Scene 1 TO Scene 2. The transition is placed at the END of the scene, not the beginning. The last scene's transition is not used.
</Warning>

## Available Transitions

### Basic Transitions

| Transition | Effect Description          | Visual Result          | Best Used For                          |
| ---------- | --------------------------- | ---------------------- | -------------------------------------- |
| `none`     | No transition, direct cut   | Immediate scene change | Fast-paced content, news, tutorials    |
| `fade`     | Classic fade to black/white | Gradual fade out/in    | Professional videos, all content types |

### Directional Wipe Transitions

| Transition  | Effect Description       | Visual Result                 | Best Used For                         |
| ----------- | ------------------------ | ----------------------------- | ------------------------------------- |
| `wipeup`    | Scene wipes upward       | New scene reveals from bottom | Uplifting content, positive messages  |
| `wipedown`  | Scene wipes downward     | New scene reveals from top    | Serious topics, transitions to detail |
| `wipeleft`  | Scene wipes to the left  | New scene pushes from right   | Forward progression, next steps       |
| `wiperight` | Scene wipes to the right | New scene pushes from left    | Going back, flashbacks, recaps        |

### Smooth Slide Transitions

| Transition    | Effect Description        | Visual Result                | Best Used For                           |
| ------------- | ------------------------- | ---------------------------- | --------------------------------------- |
| `smoothleft`  | Smooth slide to the left  | Seamless horizontal movement | Sequential content, step-by-step guides |
| `smoothright` | Smooth slide to the right | Seamless horizontal movement | Navigation, menu-style presentations    |

### Special Effect Transitions

| Transition   | Effect Description               | Visual Result                 | Best Used For                           |
| ------------ | -------------------------------- | ----------------------------- | --------------------------------------- |
| `radial`     | Radial/circular wipe from center | Expanding circle reveal       | Focus points, reveals, dramatic moments |
| `circlecrop` | Circle crop effect               | Circular mask transition      | Spotlight content, modern aesthetics    |
| `hblur`      | Horizontal motion blur           | Blurred horizontal transition | Dynamic content, modern/stylish videos  |

## Transition Selection Guide

Choose transitions based on your content type and brand style:

| Content Type               | Recommended Transitions             | Reasoning                                    |
| -------------------------- | ----------------------------------- | -------------------------------------------- |
| **Professional/Corporate** | `fade`, `none`                      | Clean, conservative, universally appropriate |
| **Educational/Tutorial**   | `fade`, `smoothright`, `none`       | Clear, non-distracting, maintains focus      |
| **Marketing/Sales**        | `wiperight`, `fade`, `radial`       | Dynamic, engaging, draws attention           |
| **Social Media**           | `hblur`, `wiperight`, `circlecrop`  | Modern, energetic, eye-catching              |
| **News/Information**       | `none`, `fade`                      | Fast-paced, professional, straightforward    |
| **Storytelling/Narrative** | `fade`, `smoothleft`, `smoothright` | Smooth flow, maintains narrative continuity  |
| **Product Demos**          | `wiperight`, `smoothright`, `fade`  | Shows progression, highlights features       |
| **Testimonials**           | `fade`, `none`                      | Professional, focuses on speaker             |

## Transition Patterns

### Pattern 1: Consistent Transitions Throughout

Use the same transition for all scenes for cohesive feel.

```javascript theme={null}
{
  scenes: [
    { story: "Scene 1 content...", sceneTransition: "fade" },
    { story: "Scene 2 content...", sceneTransition: "fade" },
    { story: "Scene 3 content...", sceneTransition: "fade" },
    { story: "Scene 4 content...", sceneTransition: "fade" }
  ]
}
```

**Result:** Consistent, professional feel with uniform transitions throughout.

### Pattern 2: Varied Transitions for Energy

Mix different transitions to create dynamic pacing.

```javascript theme={null}
{
  scenes: [
    { story: "Introduction...", sceneTransition: "fade" },
    { story: "Key point 1...", sceneTransition: "wiperight" },
    { story: "Key point 2...", sceneTransition: "smoothleft" },
    { story: "Conclusion...", sceneTransition: "fade" }
  ]
}
```

**Result:** Dynamic video with varied visual interest.

### Pattern 3: No Transitions Except Section Breaks

Use transitions only between major sections.

```javascript theme={null}
{
  scenes: [
    { story: "Intro scene 1...", sceneTransition: "none" },
    { story: "Intro scene 2...", sceneTransition: "fade" },      // Section break
    { story: "Content scene 1...", sceneTransition: "none" },
    { story: "Content scene 2...", sceneTransition: "none" },
    { story: "Content scene 3...", sceneTransition: "fade" },    // Section break
    { story: "Conclusion...", sceneTransition: "none" }
  ]
}
```

**Result:** Fast-paced content with transitions only marking major section changes.

### Pattern 4: Directional Storytelling

Use directional transitions to show progression or flow.

```javascript theme={null}
{
  scenes: [
    { story: "Step 1...", sceneTransition: "wiperight" },        // Move forward
    { story: "Step 2...", sceneTransition: "wiperight" },        // Move forward
    { story: "Step 3...", sceneTransition: "wiperight" },        // Move forward
    { story: "Review...", sceneTransition: "wipeleft" },         // Go back
    { story: "Conclusion...", sceneTransition: "fade" }
  ]
}
```

**Result:** Visual flow showing forward progression, then reflection.

## Common Use Cases

### Professional Presentations

```javascript theme={null}
{
  scenes: [
    { story: "Company overview and introduction...", sceneTransition: "fade" },
    { story: "Our services and capabilities...", sceneTransition: "fade" },
    { story: "Client success stories...", sceneTransition: "fade" },
    { story: "Contact us for more information...", sceneTransition: "none" }
  ]
}
```

**Result:** Clean, professional presentation with classic fade transitions.

### Social Media Content

```javascript theme={null}
{
  scenes: [
    { story: "Hook: Did you know this fact?", sceneTransition: "hblur" },
    { story: "Main content and explanation...", sceneTransition: "wiperight" },
    { story: "Call to action: Follow for more!", sceneTransition: "circlecrop" }
  ]
}
```

**Result:** Dynamic, modern social media video with engaging transitions.

### Step-by-Step Tutorial

```javascript theme={null}
{
  scenes: [
    { story: "Step 1: First, do this...", sceneTransition: "smoothright" },
    { story: "Step 2: Then, do that...", sceneTransition: "smoothright" },
    { story: "Step 3: Next, complete this...", sceneTransition: "smoothright" },
    { story: "Final result: You're done!", sceneTransition: "fade" }
  ]
}
```

**Result:** Clear progression through steps with smooth directional transitions.

### Product Showcase

```javascript theme={null}
{
  scenes: [
    { story: "Introducing our new product...", sceneTransition: "radial" },
    { story: "Feature 1: Advanced technology...", sceneTransition: "wiperight" },
    { story: "Feature 2: Easy to use...", sceneTransition: "wiperight" },
    { story: "Available now! Order today!", sceneTransition: "fade" }
  ]
}
```

**Result:** Engaging product showcase with attention-grabbing transitions.

## Best Practices

<AccordionGroup>
  <Accordion title="Match Transitions to Content Mood">
    Choose transitions that complement your content style:

    * **Professional/Serious**: Stick to `fade` and `none` for conservative feel
    * **Energetic/Dynamic**: Use `wiperight`, `hblur`, `radial` for movement
    * **Modern/Stylish**: Try `circlecrop`, `hblur`, `smoothleft`
    * **Traditional/Classic**: Use `fade` exclusively for timeless look
    * **Educational**: Prefer subtle transitions (`fade`, `smoothright`) that do not distract
    * **Brand Alignment**: Ensure transitions match your brand personality
  </Accordion>

  <Accordion title="Use Consistent Transitions for Cohesion">
    Create visual consistency throughout your video:

    * **Same Transition**: Use one transition type for unified feel
    * **Transition Family**: If varying, stick to one family (all wipes, all smooth, etc.)
    * **Predictable Pattern**: Establish a pattern viewers can follow
    * **Section Markers**: Use special transitions only for major section changes
    * **Avoid Randomness**: Do not randomly mix transitions without purpose
    * **Test Consistency**: Preview to ensure transitions feel cohesive
  </Accordion>

  <Accordion title="Do Not Overuse Dramatic Transitions">
    Exercise restraint with flashy effects:

    * **Less is More**: Dramatic transitions lose impact if overused
    * **Strategic Placement**: Save dramatic transitions for key moments
    * **Viewer Fatigue**: Too many effects can tire viewers
    * **Content Focus**: Transitions should enhance, not overshadow content
    * **Professional Standard**: Corporate content should favor subtle transitions
    * **Test Audience**: Check if transitions distract from message
  </Accordion>

  <Accordion title="Consider Transition Duration and Pacing">
    Ensure transitions fit your video pacing:

    * **Scene Length**: Very short scenes with transitions may feel rushed
    * **Content Type**: Fast-paced content works with quick transitions (none, fade)
    * **Viewer Comfort**: Give viewers time to process each scene change
    * **Music Sync**: Consider how transitions work with background music
    * **Natural Breaks**: Place transitions at natural content breaks
    * **Flow Testing**: Preview to ensure pacing feels natural
  </Accordion>

  <Accordion title="Optimize for Platform and Audience">
    Choose transitions based on where and to whom you are publishing:

    * **YouTube**: `fade` and `wiperight` work well for most content
    * **Instagram/TikTok**: Modern transitions (`hblur`, `circlecrop`) for younger audience
    * **LinkedIn**: Conservative transitions (`fade`, `none`) for professional network
    * **Corporate**: Stick to `fade` for internal/external business videos
    * **Educational**: Subtle transitions that do not distract learners
    * **Platform Trends**: Research what is popular on your target platform
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transition not appearing between scenes">
    **Problem:** Expected transition effect does not show between scenes.

    **Solution:**

    * Verify you set `sceneTransition` on the FIRST scene (not the second)
    * Remember: Scene 1's transition goes TO Scene 2
    * Check spelling of transition name (case-sensitive)
    * Valid transitions: `fade`, `none`, `wipeup`, `wipedown`, `wipeleft`, `wiperight`, `smoothleft`, `smoothright`, `radial`, `circlecrop`, `hblur`
    * Ensure you have at least 2 scenes (transitions connect scenes)
    * Last scene's transition typically is not used (no scene after it)
  </Accordion>

  <Accordion title="Transition appears in wrong location">
    **Problem:** Transition effect shows up between unexpected scenes.

    **Solution:**

    * Review which scene has the `sceneTransition` parameter
    * Transition is placed at the END of the scene that defines it
    * If Scene 2 has `sceneTransition: "fade"`, it affects Scene 2 → Scene 3
    * Check your scene array order matches your intended flow
    * Verify you didn't accidentally add transition to wrong scene
    * Use comments in code to label which transition goes where
  </Accordion>

  <Accordion title="All transitions look the same">
    **Problem:** Different transition types look very similar in output.

    **Solution:**

    * Some transitions are subtle (fade vs. none can be quick)
    * Preview the video carefully to see transition effects
    * Very short scenes may not show full transition effect
    * Try dramatically different transitions to test (`fade` vs `radial`)
    * Ensure scenes are long enough for transition to be visible
    * Check that browser/player supports transition rendering
  </Accordion>

  <Accordion title="Transitions look choppy or abrupt">
    **Problem:** Transitions do not look smooth, appear jarring.

    **Solution:**

    * This is typically expected behavior - transitions have standard duration
    * Scene content may create visual discord (very different scenes)
    * Try using `fade` for smoother, more universal transitions
    * Ensure scenes have sufficient length before/after transition
    * Consider if scene content naturally flows together
    * Very short scenes (under 2 seconds) may feel rushed with transitions
  </Accordion>

  <Accordion title="Invalid transition value error">
    **Problem:** API returns error about invalid transition value.

    **Solution:**

    * Check spelling of transition name exactly as documented
    * Transition names are case-sensitive (use lowercase)
    * Valid values: `fade`, `none`, `wipeup`, `wipedown`, `wipeleft`, `wiperight`, `smoothleft`, `smoothright`, `radial`, `circlecrop`, `hblur`
    * Ensure no extra spaces or special characters
    * Verify you are passing a string, not an object or number
    * Example correct usage: `sceneTransition: "fade"`
  </Accordion>

  <Accordion title="Want to control transition duration">
    **Problem:** Transition duration seems too fast or too slow.

    **Solution:**

    * Transition duration is automatically optimized by the API
    * You cannot manually control transition duration
    * All transitions use standard, pre-defined durations
    * To work around:
      * Choose different transition types (some feel longer/shorter)
      * Adjust scene durations to affect overall pacing
      * Use `none` for instant cuts if transitions feel too slow
    * This is a current limitation of the transition system
  </Accordion>

  <Accordion title="First scene has unexpected transition">
    **Problem:** Video starts with a transition effect.

    **Solution:**

    * First scene's transition applies when moving TO the second scene
    * There should be no transition at the very start of the video
    * If you see an effect at video start, it may be:
      * An intro scene with its own transition
      * Video player fade-in (not part of your video)
      * Check that first scene's transition is not being misapplied
    * The transition at video start should typically be instant (no effect)
  </Accordion>
</AccordionGroup>

## Transition Behavior Examples

Understanding exactly when transitions occur:

### Example 1: Three Scenes with Different Transitions

```javascript theme={null}
{
  scenes: [
    { story: "Scene A", sceneTransition: "fade" },       // Fade when going A → B
    { story: "Scene B", sceneTransition: "wiperight" },  // Wipe when going B → C
    { story: "Scene C", sceneTransition: "none" }        // Not used (last scene)
  ]
}
```

**Result:**

* Video starts → Scene A (no transition)
* Scene A ends → FADE → Scene B begins
* Scene B ends → WIPE RIGHT → Scene C begins
* Scene C ends → Video ends (no transition)

### Example 2: All Scenes Use Same Transition

```javascript theme={null}
{
  scenes: [
    { story: "Scene 1", sceneTransition: "fade" },
    { story: "Scene 2", sceneTransition: "fade" },
    { story: "Scene 3", sceneTransition: "fade" },
    { story: "Scene 4", sceneTransition: "fade" }
  ]
}
```

**Result:** Fade transition between every scene for consistent flow.

### Example 3: No Transitions (Fast Cuts)

```javascript theme={null}
{
  scenes: [
    { story: "Scene 1", sceneTransition: "none" },
    { story: "Scene 2", sceneTransition: "none" },
    { story: "Scene 3", sceneTransition: "none" }
  ]
}
```

**Result:** Instant cuts between all scenes, no transition effects.

## Next Steps

Enhance your videos with these complementary features:

<CardGroup cols={2}>
  <Card title="Intro/Outro Scenes" icon="clapperboard" href="/guides/advanced-features/intro-outro">
    Add professional intro and outro with transitions
  </Card>

  <Card title="Scene-Level Music Control" icon="sliders" href="/guides/advanced-features/scene-music">
    Control music per scene with transitions
  </Card>

  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add music that flows with transitions
  </Card>

  <Card title="Custom Subtitle Styling" icon="closed-captioning" href="/guides/branding-customization/custom-subtitle-style">
    Style subtitles to complement transitions
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full API specification including scene configuration
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and get video URLs