Video Puppet formatting reference

This is a full reference to all the Video Puppet options and formatting, intended for users who are looking for a specific trick and already know the basics. It’s in a single huge page to make it easy to search.

For information more suited to beginners and step-by-step lessons, check out the Getting started guides instead.

Technical tips for people who want to tinker are marked with a script icon on the left, such as this paragraph. You can safely ignore these sections if you do not want to play with advanced formatting features.

Video Puppet script header is an optional section at the start of a script file that sets global video properties, such as output video size and background music. If the script file starts with the scene separator (three dashes, ---), Video Puppet treats everything until the next scene separator as the header.

Some of these properties can also be set on individual scenes, as stage directions.

---
size: 720p
voice: Sarah
---

This script has a header setting
the document size and voice

The header should list one property per line, and separate the property names and values with a colon and a space (: ).

Technically, the header is a YAML preamble. You can use all the standard YAML tags and formatting if you like.

background

The background header property allows you to set the background music for the whole video.

Your own background music

Video Puppet supports WAV, MP3 and M4A audio files. The background music will loop automatically. We recommend either using an audio file intended for seamless looping, or ensuring that the background file is long at least as the intended video duration.

---
background: jungle.mp3
---

This script plays jungle.mp3 throughout

Provided background music

Video Puppet also comes with several audio clips for background music, which you can use royalty-free, even for commercial work. Check out the Supported background music page for possible values.

---
background: ukulele-1
---

This script plays the standard background music throughout

Adjusting background music volume

To adjust the volume of the background sound, you can optionally add a volume multiplier after the audio file name or standard background music option, separated by a space. The volume should be a positive numerical value, with 1 meaning original volume. So, for example, 0.5 would be half the original volume.

---
background: jungle.mp3 0.5
---

This script plays jungle.mp3 at
half volume.

size

The size header property controls the resulting video size. You can set the size as a specific width and height, joined by x (for example 800x600), or use one of the following standard sizes:

  • 720p: (default), HD video in 16x9 aspect ratio, typical for social networks, YouTube and similar online services
  • 1080p: full HD, 16x9 aspect ratio
  • instagram: optimal format for Instagram feeds (portait)
  • instagram-square: optimal format for Instagram feeds (square)
  • instagram-story: optimal format for Instagram stories
---
size: 800x600
---

This script will create a video
800 pixels wide and 600 pixels tall

subtitles

You can use the subtitles header property to automatically generate subtitles from narration. The only supported value for now is auto which creates subtitles from individual narration paragraphs. Leave this property out of the header if you do not want automatic subtitles.

---
subtitles: auto
---

This narration will appear as a subtitle automatically

theme

The theme header property controls the theme for slide text shown over videos and images. The valid options are:

  • default: black text, useful for light backgrounds
  • light: white text, useful for dark backgrounds

transition

The transition header allows you to configure how Video Puppet switches between scenes. Without a transition, the last frame of a scene is immediately replaced with the first frame of a new scene. Transitions can help ease scene boundaries with visual effects.

At the moment, Video Puppet has very basic support for transitions (we do plan to support more options in the future). Valid transition values are currently:

  • crossfade - fade out the old scene, then fade in the new scene
  • wipe - slide the new scene horizontally over the old scene
  • none - no transition; useful to turn off transitions on a particular scene with a stage direction if transitions are activated globally

You can either specify just the transition type (giving it the default duration of 200 milliseconds), or provide the transition duration in seconds after the name.

---
transition: wipe 0.5
---

this script replace scenes using a half-second wipe

voice

The voice header property sets the default voice for the video. Check out the Available Voices page for possible values

---
voice: Brian
---

This script will be read by Brian

Scenes

To create a script file with several scenes, just separate out the scenes with a paragraph containing three dashes (---).

This is the first scene

![](image1.jpg)

---

This is the second scene

![](image2.jpg)

Images

Video Puppet supports the usual markdown syntax for images, and you can add JPG, GIF and PNG images.

![](file.jpg)

As an alternative to the markdown format, you can also add images to scenes using a stage direction - a paragraph enclosed in brackets.

(image: file.jpg)

When adding an image to a scene, Video Puppet will automatically resize it to fit the target video format. You can control resizing by adding an option to the square brackets when setting the video. For example, to shrink and pad a larger image to fit the smaller target size, use the contain option:

![contain](image.png)

Without additional options, Video Puppet will crop a large image around the center to cover the video size. If you want to show a different part of the image, specify the cropping position. For example, the following scene takes the left part of an image instead of the center:

![left](file.png)

When using the stage direction format instead of markdown, you can specify the optional size or position using subproperties, in which case you should provide the file name as the file subproperty).

(image:
  file: image.jpg
  size: cover
  position: left)

Stage directions are technically YAML, so you should indent subproperties with two spaces or a tab; you can also use any other YAML syntax, including embedding everything in a single line with curly braces.

Available sizing options

  • fit: image will be rescaled without keeping the proportions
  • contain: image will be completely visible, and padded if necessary with black bars to fit the output frame
  • cover: (default) image will be scaled so it completely covers the output frame, and cropped if necessary to keep the proportions

Available position options

  • center: (default) crop image around the vertical and horizontal middle
  • top-left: crop the image so the top-left corner aligns with the top-left of the video
  • left: crop the image so the left edge of image aligns with the left edge of the video, and center image vertically
  • right: crop the image so the right edge of image aligns with the right edge of the video, and center image vertically
  • top: crop the image so the top edge of image aligns with the top edge of the video, and center image horizontally
  • bottom: crop the image so the bottom edge of image aligns with the bottom edge of the video, and center image horizontally

Videos

Video Puppet allows you to add video clips to the scene using the usual markdown syntax for linked images. Video Puppet supports adding MOV and MP4 videos.

![](video.mp4)

Some markdown editors do not support using videos in linked images, so video puppet lets you alternatively use the video stage direction to add a video.

(video: file.mp4)

Resizing videos

When adding a video to a scene, Video Puppet will automatically resize it to fit the target video format. You can control resizing by adding an option to the square brackets when setting the video. For example, to shrink and pad a larger video to fit the smaller target size, use the contain option:

![contain](birds.mp4)

If you add a video using a stage direction, you can specify the size as a subproperty. In this case, you will also need to set the file as the file subproperty.

(video:
  file: birds.mp4
  size: contain)

Stage directions are technically YAML, so you should indent subproperties with two spaces or a tab; you can also use any other YAML syntax, including embedding everything in a single line with curly braces.

Available sizing properties

  • fit: video will be rescaled without keeping the proportions
  • contain: video will be completely visible, and padded if necessary with black bars to fit the output frame
  • cover: (default) video will be scaled so it completely covers the output frame, and cropped if necessary to keep the proportions

Extracting segments from videos

To show only part of a video in a scene, specify it as a stage direction instead of the markdown resource, and include the segment subproperty. The segment can specify the starting and ending point between a dash, either as a whole number of seconds, or in the standard time format (HH:MM:SS).

(video:
  file: stopwatch.mp4
  segment: 00:02 - 00:04)

You can also extract a still image of the start or end of a video using the special start and end segment values.

(video:
  file: stopwatch.mp4
  segment: end)

Synchronising narration and video

When specifying a video resource, you can include a synchronization option in square brackets. For example, this loops the video for the duration of the audio in the scene:

![loop](stopwatch.mp4)

Alternatively, you can provide a video stage direction, and specify the sync sub-property.

(video:
  file: stopwatch.mp4
  sync: loop)

Supported synchronisation options

Here are the available synchronisation options:

  • freeze: (default) keeps the last video frame frozen to wait for audio to finish, but does not speed up or shorten the video if longer than audio
  • match: speed up or slow down the video to match the audio track length
  • trim: keep the original video speed, but stop the scene when either the video or the audio end. This will also cut off any remaining audio if the video is shorter.
  • loop: repeat either the video or the audio to match the longer asset duration

Narration

Any text in a scene is turned into automatically generated narration.

You can separate text into paragraphs with a blank line between. This has no impact on narration, but will have an impact on automatically generated subtitles. Each paragraph will appear as a separate subtitle.

Video Puppet will read this text as narration.

This is the second paragraph.

Controlling pronunciation

You can specify a pause in narration by using the pause stage direction, and setting the number of seconds. For example, the following scene has a two second pause between the sentences.

This is the first sentence, and we'll pause for a bit after it.

(pause: 3)

This is the second sentence.

To control emphasis, speed up or slow down the speech, use SSML markup, and wrap the narration into <speak></speak> tags. For example, the following scene sets a moderate emphasis using SSML.

<speak>
  <emphasis level="moderate">
    This is an important announcement
  </emphasis>
</speak>

You can also use SSML to speed up or slow down the narration, or to read out acronyms verbatim:

<speak>
  <prosody rate="slow" pitch="-2st">
    Can you hear me now?
  </prosody>  
  <say-as interpret-as="verbatim">
    abcdefg
  </say-as>
</speak>

Controlling voices

You can use the voice stage direction to set the active voice for the subsequent narration paragraphs:

The default voice will read this.

(voice: William)

William will read this.

William will also read this.

(voice: Joanna)

Joanna will read this

Audio files

Instead of automatically generated narration, you can add your own audio files, with recorded voice, music or something else to play during a scene. To do so, just add (audio: file) in a separate paragraph. Video puppet supports WAV, MP3 and M4A files.

For example, this scene will show an image from london.jpg and play the audio from london-audio.mp3:

![](london.jpg)

(audio: london-audio.mp3)

You can add multiple files to the same scene, and they will play in sequence. You can also mix audio files with generated narration.

(voice: william)

William will read this before the recorded audio.

(audio: london-audio.mp3)

William will read this after the recorded audio.

Subtitles

Video Puppet can automatically generate subtitles from narration text, using the subtitles header.

To add subtitles to a scene without narration, or to show something else on the screen instead of the narration text, use Markdown block-quote sections (starting with >).

Video Puppet will read this

> Video Puppet will show this instead

For scenes with longer narration, or to show subtitles gradually, split the text into different block quotes.

![](audio.mp3)

> first subtitle

> second subtitle

Text slides

Video Puppet can show text on top of videos or images, which can be very useful to add a visual comment, show a code snippet or visually point out important aspects of narration.

You can use Markdown code blocks (fenced with three backticks or three tildas) to create a textual slide:

```
Hi there!
```

If there is no audio or narration in the slide, the standard duration on screen will be 1 second. To make the scene longer, add a duration stage direction.

Controlling slide visuals

In case there is also an image or a video in the same scene, Video Puppet will show the slide over the scene, with a dark backdrop shadow to create contrast between the text and the background. This works well if the image or video behind the slide is mostly in light colours.

When showing slides over darker images or videos, set the slide theme to light using the theme stage direction, to switch to lighter colors in the slide.

(theme: light)

```
Start counting!
```

![](stopwatch.mp4)

Rich text slides

You can render rich text on slides by using markdown syntax, and marking the slide as markdown content by appending md after the opening code fence:

```md
# Heading 1
## Heading 2

* bullets are left-aligned
* bullet 2
  * sub-bullet
```

Syntax highlighting

If you want to include code snippets as slides, Video Puppet will automatically support syntax highlighting as long as you specify the language after the opening code fence.

```css
.container {
  align-items: center;
  display: flex;
}
```

Controlling font size

By default, Video Puppet sets the font for slides to relatively large (50px) to show clearly on smaller screens. For slides with a lot of text, you can set the size using the font-size stage direction. Set the value to an integer number of pixels.

(font-size: 20)

```css
.container {
  align-items: center;
}
```

Comments

Video Puppet supports comment blocks starting between <!-- and --> (standard for Markdown, which inherited it from HTML). If you want to leave any notes in the Video Puppet script for readers and co-authors, you can do so within those marks.

![](image.png)

<!-- 

this is just a comment,
Video Puppet will ignore it

-->

Stage directions

Stage directions are commands to Video Puppet for how to process a scene. To specify a stage direction, add a paragraph (separated by at least one blank line from the surrounding content) enclosed in brackets.

Each stage direction has a type, followed by a colon and a space, then the direction value. For example, the following paragraph creates a small pause in narration by using the pause stage direction:

(pause: 2)

Technically, the contents within the brackets are parsed as YAML, so you can use all the standard YAML formatting if you like.

audio

The audio stage direction allows you to embed an audio file into the scene narration. For more information, check out the Audio files section.

callout

The callout stage direction allows you to visually point out an area of an image or a video in the scene (for example, to show an important part of a diagram, or to focus the viewer attention on an important menu option).

Video Puppet will gray out the rest of the background image or scene, and leave the callout area highlighted.

The standard callout is a 100 pixel wide circle. To show it, specify the center coordinates relative to the top-left corner of the video using cx and cy subproperties.

Circle highlights

You need to specify the callout sub-properties on separate lines, indented by two spaces or a tab.

![](image.png)

(callout:
  cx: 200
  cy: 250)

Controlling circle size

You can optionally specify a size property as well, to make the circle smaller or larger:

![](image.png)

(callout:
  cx: 313
  cy: 250
  size: 300)

Rectangular highlights

If you want to point to a specific rectangular area of the video, specify the type subproperty as rectangle, then provide the rectangle bounding box as top, left, right and bottom.

![](image.png)

(callout:
  type: rectangle
  left: 450
  top: 0
  right: 770
  bottom: 130)

duration

The duration stage direction controls how long an image or a slide will show in the video. It is useful to control scenes without narration or other audio elements.


(duration: 2)

font-size

The font-size stage direction allows you to control the base text size for slides. The value must be a positive integer number.

(font-size: 20)

~~~
This slide shows with slightly
smaller letters
~~~

image

The image scene direction allows you to add an image to a scene. See Scene images for more information.

pause

The pause stage direction lets you add a pause in narration. The value should be a number of seconds to pause the narration.


This is the first sentence.

(pause: 2)

This is after the two second break.

For more complex pronunciation controls, check out the Narration section.

Technically, the pause stage direction generates a silent audio of specified length. You can use it without other narration blocks to just extend the duration of a particular scene, but it’s more efficient to use duration for that.

theme

The theme scene direction allows you to set the slide text theme for a single scene. The options are the same as the theme header, but the value applies only to the current scene. You need to use this stage direction before the corresponding slide text.

(theme: light)

```
This test will show white on dark background
```

![](dark-image.png)

transition

The transition scene direction allows you to set the incoming transition for a single scene (it will define how the current scene shows over the previous scene). The options are the same as the transition header, but the setting applies only to the current scene.

You cannot use this stage direction on the first scene.

![](first-image.jpg)

---

(transition: wipe 0.5)

This scene will wipe in horizontally over the previous scene 

![](second-image.png)

video

The video scene direction allows you to add a video to a scene. See Scene videos for more information.

voice

The voice scene direction allows you to set the narration voice for a single scene. The options are the same as the voice header, but the setting applies only to the current scene. Check out the Available voices page for currently supported voices.

You need to use this stage direction before the corresponding narration blocks. You can use it several times in the same scene, and it will apply to the narration blocks which follow.

The default voice will read this.

(voice: William)

William will read this.

William will also read this.

(voice: Joanna)

Joanna will read this