> ## 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.

# Text Animations & Future Words

> Animate captions with entry and exit effects and control upcoming word visibility using the futureWords parameter in the Pictory API.

Text animations add entry and exit effects to your video captions, enhancing visual engagement. The `futureWords` parameter, available with `fade` and `blur` animations, controls how upcoming words appear on screen before they are spoken. This combination is particularly effective for creating engaging, word-synchronized captions for social media content.

## What You Will Learn

<CardGroup cols={2}>
  <Card title="Text Animations" icon="wand-magic-sparkles">
    Apply entry and exit animation effects to scene captions
  </Card>

  <Card title="Future Words" icon="eye">
    Control the visibility of upcoming unspoken words on screen
  </Card>

  <Card title="Animation Types" icon="film">
    Select from fade, blur, drift, wipe, text reveal, elastic, and typewriter effects
  </Card>

  <Card title="Social Media Ready" icon="hashtag">
    Produce scroll-stopping content for TikTok, Reels, and Shorts
  </Card>
</CardGroup>

## Prerequisites

Ensure you have the following before proceeding:

* A Pictory API key ([get one here](https://app.pictory.ai/api-access))
* Familiarity with [Dynamic Captions](/guides/captions/dynamic-captions) fundamentals
* AI voiceover enabled for word-level caption synchronization with audio

## Available Animations

### Entry Animations

| Animation     | `futureWords` Support | Direction                     | Description                                  |
| ------------- | --------------------- | ----------------------------- | -------------------------------------------- |
| `fade`        | Yes                   | -                             | Words fade in smoothly as they are spoken    |
| `blur`        | Yes                   | -                             | Words transition from blurred to sharp focus |
| `drift`       | No                    | `up`, `down`, `left`, `right` | Words slide in from the specified direction  |
| `wipe`        | No                    | `left`, `right`, `up`, `down` | Words are revealed with a sweeping motion    |
| `text reveal` | No                    | -                             | Words uncover progressively                  |
| `elastic`     | No                    | -                             | Words bounce in with a spring effect         |
| `typewriter`  | No                    | -                             | Words appear one letter at a time            |

### Exit Animations

| Animation     | Direction                     | Description                                |
| ------------- | ----------------------------- | ------------------------------------------ |
| `fade`        | -                             | Words fade out smoothly                    |
| `blur`        | -                             | Words blur out of focus                    |
| `drift`       | `up`, `down`, `left`, `right` | Words slide out in the specified direction |
| `wipe`        | `left`, `right`, `up`, `down` | Words are swept away                       |
| `text reveal` | -                             | Words are progressively hidden             |

<Note>
  `elastic` and `typewriter` are entry-only animations. They do not have exit variants.
</Note>

## The futureWords Parameter

The `futureWords` parameter controls the on-screen appearance of words that have not yet been spoken. This parameter is available exclusively with `fade` and `blur` entry animations.

| Value         | Appearance                                    | Effect                                                                        | Recommended For                              |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------- |
| `"hidden"`    | Upcoming words are invisible                  | Words appear only when spoken, creating a maximum reveal effect               | TikTok, Instagram Reels, high-energy content |
| `"subtle"`    | Upcoming words are faintly visible            | Viewers can preview upcoming text while attention remains on the current word | YouTube Shorts, educational content          |
| `"prominent"` | Upcoming words are clearly visible but dimmed | Full text is readable with the spoken word highlighted                        | Professional videos, presentations           |

### Visual Comparison

**`futureWords: "hidden"`** (words revealed as spoken)

```
Timeline:  "The future of AI is here"
t=0.0s:    [The] ______ __ __ __ ____        (only "The" visible)
t=0.3s:    The [future] __ __ __ ____         ("future" appears as spoken)
t=0.7s:    The future [of] __ __ ____         (words reveal one by one)
t=0.9s:    The future of [AI] __ ____
t=1.1s:    The future of AI [is] ____
t=1.3s:    The future of AI is [here]
```

**`futureWords: "subtle"`** (soft preview of upcoming text)

```
Timeline:  "The future of AI is here"
t=0.0s:    [The] future of AI is here         ("The" bright, rest faint)
t=0.3s:    The [future] of AI is here         ("future" brightens)
t=0.7s:    The future [of] AI is here         (spoken words remain bright)
```

**`futureWords: "prominent"`** (full text with active word highlighted)

```
Timeline:  "The future of AI is here"
t=0.0s:    [The] future of AI is here         ("The" highlighted, rest dimmed)
t=0.3s:    The [future] of AI is here         ("future" now highlighted)
t=0.7s:    The future [of] AI is here         (highlight follows the voiceover)
```

## 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";

  async function createAnimatedCaptionsVideo() {
    try {
      console.log("Creating video with animated captions...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "animated_captions_demo",
          videoWidth: 1080,
          videoHeight: 1920,
          quality: "high",

          voiceOver: {
            enabled: true,
            aiVoices: [{ speaker: "Rachel", speed: 100 }],
          },

          scenes: [
            {
              story:
                "Five tips to grow your social media following this year. Number one, post consistently at least three times per week.",
              maxSubtitleLines: 1,
              subtitleStyle: {
                animations: [
                  {
                    name: "fade",
                    type: "entry",
                    speed: "fast",
                    futureWords: "hidden",
                  },
                  { name: "fade", type: "exit", speed: "fast" },
                ],
              },
            },
            {
              story:
                "Number two, engage with your audience by replying to every comment within the first hour of posting.",
              maxSubtitleLines: 1,
              subtitleStyle: {
                animations: [
                  {
                    name: "blur",
                    type: "entry",
                    speed: "medium",
                    futureWords: "subtle",
                  },
                  { name: "blur", type: "exit", speed: "fast" },
                ],
              },
            },
            {
              story:
                "Number three, use trending audio and hashtags to reach new audiences organically.",
              maxSubtitleLines: 2,
              subtitleStyle: {
                animations: [
                  {
                    name: "fade",
                    type: "entry",
                    speed: "medium",
                    futureWords: "prominent",
                  },
                  { name: "fade", type: "exit", speed: "medium" },
                ],
              },
            },
          ],
        },
        {
          headers: {
            "Content-Type": "application/json",
            Authorization: API_KEY,
          },
        }
      );

      const jobId = response.data.data.jobId;
      console.log("Video creation started! Job ID:", jobId);
    } catch (error) {
      console.error("Error:", error.response?.data || error.message);
    }
  }

  createAnimatedCaptionsVideo();
  ```

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

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

  def create_animated_captions_video():
      try:
          print("Creating video with animated captions...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'animated_captions_demo',
                  'videoWidth': 1080,
                  'videoHeight': 1920,
                  'quality': 'high',

                  'voiceOver': {
                      'enabled': True,
                      'aiVoices': [{'speaker': 'Rachel', 'speed': 100}]
                  },

                  'scenes': [
                      {
                          'story': 'Five tips to grow your social media following this year. Number one, post consistently at least three times per week.',
                          'maxSubtitleLines': 1,
                          'subtitleStyle': {
                              'animations': [
                                  {
                                      'name': 'fade',
                                      'type': 'entry',
                                      'speed': 'fast',
                                      'futureWords': 'hidden'
                                  },
                                  {'name': 'fade', 'type': 'exit', 'speed': 'fast'}
                              ]
                          }
                      },
                      {
                          'story': 'Number two, engage with your audience by replying to every comment within the first hour of posting.',
                          'maxSubtitleLines': 1,
                          'subtitleStyle': {
                              'animations': [
                                  {
                                      'name': 'blur',
                                      'type': 'entry',
                                      'speed': 'medium',
                                      'futureWords': 'subtle'
                                  },
                                  {'name': 'blur', 'type': 'exit', 'speed': 'fast'}
                              ]
                          }
                      },
                      {
                          'story': 'Number three, use trending audio and hashtags to reach new audiences organically.',
                          'maxSubtitleLines': 2,
                          'subtitleStyle': {
                              'animations': [
                                  {
                                      'name': 'fade',
                                      'type': 'entry',
                                      'speed': 'medium',
                                      'futureWords': 'prominent'
                                  },
                                  {'name': 'fade', 'type': 'exit', 'speed': 'medium'}
                              ]
                          }
                      }
                  ]
              },
              headers={
                  'Content-Type': 'application/json',
                  'Authorization': API_KEY
              }
          )
          response.raise_for_status()

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

      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")

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

## Animation Examples

### Fade with Hidden Future Words

Words appear only when spoken. Ideal for short-form social media content:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "fade", type: "entry", speed: "fast", futureWords: "hidden" },
      { name: "fade", type: "exit", speed: "fast" }
    ]
  }
}
```

### Blur with Subtle Future Words

Words transition from blurred to sharp focus. Upcoming words are faintly visible:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "blur", type: "entry", speed: "medium", futureWords: "subtle" },
      { name: "blur", type: "exit", speed: "fast" }
    ]
  }
}
```

### Drift Animation

Words slide in from a specified direction:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "drift", type: "entry", speed: "medium", direction: "up" },
      { name: "drift", type: "exit", speed: "medium", direction: "down" }
    ]
  }
}
```

### Wipe Animation

Words are revealed with a sweeping motion:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "wipe", type: "entry", speed: "medium", direction: "left" },
      { name: "wipe", type: "exit", speed: "medium", direction: "right" }
    ]
  }
}
```

### Typewriter Animation

Words appear one letter at a time:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "typewriter", type: "entry", speed: "fast" }
    ]
  }
}
```

### Elastic Animation

Words bounce in with a spring effect:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "elastic", type: "entry", speed: "medium" }
    ]
  }
}
```

### Text Reveal Animation

Words uncover progressively:

```javascript theme={null}
{
  subtitleStyle: {
    animations: [
      { name: "text reveal", type: "entry", speed: "medium" },
      { name: "text reveal", type: "exit", speed: "fast" }
    ]
  }
}
```

## Platform Recommendations

| Platform       | Aspect Ratio | Recommended Animation | futureWords   | maxSubtitleLines |
| -------------- | ------------ | --------------------- | ------------- | ---------------- |
| TikTok / Reels | 9:16         | `fade`                | `"hidden"`    | 1                |
| YouTube Shorts | 9:16         | `blur`                | `"subtle"`    | 1-2              |
| YouTube        | 16:9         | `fade`                | `"prominent"` | 2                |
| LinkedIn       | 16:9         | `fade`                | `"prominent"` | 2                |
| Instagram Feed | 4:5          | `blur`                | `"subtle"`    | 2                |

## Animation Parameters Reference

| Parameter          | Type   | Required                     | Values                                                                                | Description                                                                               |
| ------------------ | ------ | ---------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `name`             | string | Yes                          | `"fade"`, `"blur"`, `"drift"`, `"wipe"`, `"text reveal"`, `"elastic"`, `"typewriter"` | The animation type to apply                                                               |
| `type`             | string | Yes                          | `"entry"`, `"exit"`                                                                   | Specifies when the animation plays                                                        |
| `speed`            | string | Yes                          | `"slow"`, `"medium"`, `"fast"`, `"custom"`                                            | The animation playback speed                                                              |
| `customSpeedValue` | number | When speed is `"custom"`     | Minimum 0.5                                                                           | Custom speed multiplier                                                                   |
| `futureWords`      | string | No                           | `"hidden"`, `"subtle"`, `"prominent"`                                                 | Controls upcoming word visibility. Available only with `fade` and `blur` entry animations |
| `direction`        | string | When using `drift` or `wipe` | `"up"`, `"down"`, `"left"`, `"right"`                                                 | The direction of the animation movement                                                   |

<Warning>
  **Constraints:**

  * The `futureWords` parameter is available only with `fade` and `blur` entry animations
  * Each scene supports a maximum of 2 animations (1 entry + 1 exit)
  * `elastic` and `typewriter` are entry-only animations with no exit variant
  * When AI voiceover is enabled, `futureWords` synchronizes word highlighting with the spoken audio
  * The `futureWords` parameter must be specified on the `entry` animation, not the `exit` animation
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Select futureWords Based on Platform">
    * **TikTok / Reels:** `"hidden"` for maximum engagement through word reveal
    * **YouTube Shorts:** `"subtle"` to provide a preview of upcoming words
    * **YouTube / LinkedIn:** `"prominent"` for professional, fully readable captions
    * **Instagram Feed:** `"subtle"` for a balance between engagement and readability
  </Accordion>

  <Accordion title="Match Animation Speed to Voiceover Pace">
    Select an animation speed that complements the voiceover delivery:

    * `"fast"` for quick-paced speakers and short-form content
    * `"medium"` for a balanced pace suitable for most content
    * `"slow"` for dramatic pauses and emphasis
    * `"custom"` with `customSpeedValue` for precise control
  </Accordion>

  <Accordion title="Use Low maxSubtitleLines with futureWords">
    For the most effective animated caption experience:

    * `maxSubtitleLines: 1` delivers the strongest impact for short-form content
    * `maxSubtitleLines: 2` provides a good balance for most platforms
    * Higher values display more text simultaneously, which can reduce the visual impact of word-level animations
  </Accordion>

  <Accordion title="Vary Animations Across Scenes">
    Different animations can be applied to individual scenes for visual variety:

    ```javascript theme={null}
    scenes: [
      { story: "...", subtitleStyle: { animations: [{ name: "fade", ... }] } },
      { story: "...", subtitleStyle: { animations: [{ name: "blur", ... }] } },
      { story: "...", subtitleStyle: { animations: [{ name: "drift", ... }] } }
    ]
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Words Not Highlighting in Sync With Audio">
    **Cause:** Captions appear but words do not highlight at the correct time relative to the voiceover.

    **Resolution:**

    1. Verify that `futureWords` is set on the entry animation, not the exit animation
    2. Confirm that `type` is set to `"entry"` on the animation containing `futureWords`
    3. Ensure AI voiceover is enabled for automatic word-level timing synchronization
    4. Verify that the animation `name` is either `"fade"` or `"blur"`, as these are the only types that support `futureWords`
  </Accordion>

  <Accordion title="futureWords Parameter Rejected by API">
    **Cause:** The API returns an error when `futureWords` is included in the request.

    **Resolution:**

    1. Confirm the animation `name` is `"fade"` or `"blur"`. Other animation types do not support `futureWords`
    2. Remove `futureWords` from any `drift`, `wipe`, `text reveal`, `elastic`, or `typewriter` animation configurations
  </Accordion>

  <Accordion title="All Words Appear Simultaneously Despite Hidden Setting">
    **Cause:** Setting `futureWords: "hidden"` does not produce the expected word reveal behavior.

    **Resolution:**

    1. Confirm that `futureWords` is specified on the `entry` animation, not the `exit` animation
    2. Verify that `maxSubtitleLines` is set at the scene level
    3. Enable AI voiceover to synchronize word appearance with the spoken audio
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Dynamic Captions" icon="closed-captioning" href="/guides/captions/dynamic-captions">
    Learn the fundamentals of dynamic captions and the maxSubtitleLines parameter
  </Card>

  <Card title="Custom Subtitle Style" icon="font" href="/guides/branding-customization/custom-subtitle-style">
    Customize font, color, and background of your captions
  </Card>

  <Card title="Highlight Keywords" icon="highlighter" href="/guides/branding-customization/highlight-keywords">
    Emphasize important words within captions
  </Card>

  <Card title="AI Voiceover Guide" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Configure AI voices for your videos
  </Card>
</CardGroup>