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.

asset-resize

The asset-resize header property controls the default resizing policy for assets (such as images or videos) that are not in the same aspect ratio as the output video. Video Puppet can automatically clip, stretch or rescale assets to fit the video format.

Valid values are:

  • fit: embedded asset will be rescaled without keeping the proportions to fit the whole video frame
  • contain: embedded will be completely visible, in the original proportions and padded if necessary to fit the output frame.
  • cover: (default) embedded asset will be scaled so it completely covers the output frame, and cropped if necessary to keep the proportions

For the contain option, the embedded asset will be padded with black bars by default. You can set a custom color using the canvas header and stage direction.

Note that you can set this property on individual assets as well. Check out the reference for images and videos.

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, AAC 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.

Fade background music in or out

Playing background audio at full volume when the video ends might make the ending sound abrupt. To prevent that, add a fade-out property to the background header, and Video Puppet will automatically reduce the volume during the last scene. Similarly, you can ease in the music during the first scene, by adding a fade-in property.

---
background: jungle.mp3 0.5 fade-out fade-in
---

During the first scene the music increases gradually
because of the 'fade-in' property

---

During the middle scenes the music plays
at the requested volume (0.5) in this script.

---

During the last scene the music volume will be 
gradually reduced because of the 'fade-out' property

canvas

The canvas header property sets the padding color for images and videos that need to be resized and cannot fit the whole video area, and the default background color for slides. You can set it to an English language name for common colors (for example white or black) or a CSS hex RGB value starting with ‘#’ (for example #AA00AA). RGBA values are not acceptable since this sets the background color, and videos cannot be transparent.

For example, the following script will use blue bars around the resized image to fill up the space.

---
size: 800x600
canvas: blue
---

![contain](image.jpg)

You can also set this value as a stage direction for individual scenes.

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: 16:9, 720p (for YouTube) (1280 x 720 pixels)

  • 1080p: 1080p (Full HD) (1920 x 1080 pixels)

  • 4x3: 4:3 (for VGA projectors) (800 x 600 pixels)

  • 720p-portrait: 720p portrait (720 x 1280 pixels)

  • instagram: Instagram portrait (1080 x 1350 pixels)

  • instagram-square: Instagram square (1080 x 1080 pixels)

  • instagram-story: Instagram story (1080 x 1920 pixels)

  • pinterest-square: Pinterest square (1080 x 1080 pixels)

  • pinterest-vertical: Pinterest vertical 9:16 (720 x 1280 pixels)

  • pinterest-2x3: Pinterest vertical 2:3 (720 x 1080 pixels)

  • linkedin: LinkedIn (1728 x 720 pixels)

  • linkedin-vertical: LinkedIn vertical (720 x 1728 pixels)

  • twitter: Twitter (1280 x 720 pixels)

  • twitter-square: Twitter square (720 x 720 pixels)

  • facebook: Facebook (1280 x 720 pixels)

  • facebook-square: Facebook Square (1080 x 1080 pixels)

  • facebook-carousel: Facebook Carousel (1080 x 1080 pixels)

Set the size using a preset like in the example below:

---
size: 720p
---

This script will create a video in the 720p format for YouTube

You can manually set the size like in the example below:

---
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. The valid options are:

  • default: black text on white without images, white text on backdrop over images, useful for light backgrounds
  • light: white text on black without images, white text without backdrop over images, useful for dark backgrounds
  • a project CSS file name (must end with .css). See below for CSS theme examples.

You can apply the theme to an individual scene using the theme stage direction instead of using the header property.

Customising slide themes using CSS

You can customise slide visuals fully using CSS, for example to apply your corporate brand colors or fonts. To do so, just include a CSS file in your project, and then use the file name as the theme.

---
theme: custom.css
---

```md
# this slide uses a custom css theme
```

See below for some common tricks you can do with CSS:

Changing fonts

Apply fonts, colors or other styles directly to the body. For example, the following CSS file will change the heading font. (Note that you also need to add the font file to your project).

@font-face {
  font-family: 'Waltograph UI';
  src: url('waltographUI.ttf') format('truetype');
  font-weight: bold;
  font-style: normal;
}

h1, h2 {
  font-family: 'Waltograph UI';
  color: #839751;
  text-decoration: underline;
}
Adding a background

You can change the slide background color, or even insert a background pattern:

body {
  background: radial-gradient(#975c51 2px, transparent 3px), radial-gradient(#975c51 2px, transparent 3px), #fff;
  background-position: 0 0, 20px 20px;
  background-size: 40px 40px;
}

Note that the background colors are ignored if a slide is painted on top of an image or a video.

Managing the image backdrop

When you add a slide on top of an image, Video Puppet will apply an optional backdrop effect. In the default theme, it will gray out the image a bit and provide a light shadow over it, to create contrast. You can set any CSS backdrop filter in custom themes by applying them to the .backdrop class:

.backdrop {
  backdrop-filter: blur(20px);
}

Note that the backdrop is applied only to images. For slides on top of videos, backdrops are not yet supported.

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

voice-speed

The voice-speed header property sets the overall narration speed for the whole video. The possible values are:

  • fast
  • normal (default)
  • slow
  • a numerical value between 0.3 and 2 (inclusive)

Numerical values allow you to set the speed on a scale, as a multiplier of the standard speed. The value 1 corresponds to the usual reading speed for the voice (so 0.5 is half-speed and 1.25 is 25% faster than normal).

---
voice: Brian
voice-speed: slow
---

This script will be read by Brian, slowly.

You can also use the voice-speed stage direction to set the narration speed for a specific scene or paragraph.

voice-volume

The voice-volume header property sets the overall narration volume for the whole video. The possible values are:

  • loud
  • medium
  • normal (default)
  • soft
---
voice: Brian
voice-volume: loud
---

This script will be read by Brian, loudly

You can also use the voice-volume stage direction to set the volume for a specific scene or paragraph.

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 (see the asset-resize header property for more information).

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

Same as the asset-resize header.

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

Using animated GIFs

Including an animated GIF without any options will loop it to match the scene audio duration. If you want to play just one cycle of the GIF animation and then keep the last frame on screen until the narration runs out, use the freeze tag:

![freeze](image.gif)

Alternatively, use the stage direction syntax and include freeze as the sync sub-property.

(image:
  file: image.gif
  sync: freeze
)
Supported synchronisation options

Here are the available synchronisation options for animated GIFs:

  • freeze: 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 animation to match the audio track length
  • trim: keep the original animation speed, but stop the scene when either the animation or the audio end. This will also cut off any remaining audio if the animation is shorter.
  • loop: (default) repeat the video to match the audio duration, but don’t repeat the audio if the video is longer
  • loop-audio: repeat the audio to match the video duration, but don’t repeat the video if the audio is longer.

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 (see the asset-resize header property for more information).

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

Same as the asset-resize header.

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 the video to match the audio duration, but don’t repeat the audio if the video is longer
  • loop-audio: repeat the audio to match the video duration, but don’t repeat the video if the audio is longer.

Manipulating video volume

If the included video has an audio track, it will play at the same time as the narration (and optionally the background music). To make it easy to compose scenes, Video Puppet can also adjust the volume of the video. To change it, just add a volume property to the video stage direction:

(video:
  file: stopwatch.mp4
  volume: 0.5)

The volume should be a numerical value, specifying the multiplier to apply to the original audio volume (so 0.5 is half the original volume, and 3 would be three times louder than the original).

To completely turn off the audio track from an embedded video, use the value 0. You can also use a special value mute instead of 0. This is particularly useful as you can use it in the markdown link syntax as a shorthand property:

![mute](video.mp4)

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 voices

You can use the voice stage direction to set the active voice for the subsequent narration paragraphs. Check out the Available Voices page for possible values.

The default voice will read this.

(voice: William)

William will read this.

William will also read this.

(voice: Joanna)

Joanna will read this

Controlling pronunciation

You can provide hints for the voice using markdown emphasis and strikeouts. Enclosing a bit of text with single underscore (_) or asterisk (*) adds a moderate emphasis, enclosing with two underscores (__) or two asterisks (**) creates a strong emphasis, and enclosing into two tildas (~~) creates a reduced voice.

For best results, enclose entire sentences into emphasis blocks. Using emphasis on parts of sentences might create weird pauses in the narration.

This is my usual voice.
_This is more important._
**This is really important.**
~~This is not so much.~~

Enclose a phrase between two back-ticks (`), and Video Puppet will spell it out. You can use this trick to read out an acronym or instruct students how to write a complex word:

The word Sacrilegious is spelled `Sacrilegious`.

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.

You can control various other aspects of the narration using stage directions such as voice-emphasis, voice-volume and voice-speed. For example, the following scene makes the second paragraph louder than the first one:

This is my normal voice.

(voice-volume: loud)

This is very important.

Using SSML

You can also use SSML markup, and wrap the narration into <speak></speak> tags.

Note that you must to wrap entire paragraphs into <speak></speak>, mixing SSML with normal text is not supported.

For example, the following scene uses SSML to slow down the narration, and 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>

Different voices have different SSML support, so not all tags will work with all voices. Experiment for best results.

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, AAC 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

You can control the slide visuals by setting a theme in the header for the whole video, or as a stage direction for just a single scene. Check out the theme header for more information and an example.

(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)

canvas

The canvas stage direction sets the background color for slides and padding color for images or videos that cannot fill up the whole video canvas. For example, the following scene will use a blue background color for resized images.

(canvas: blue)

![contain](image.png)

You can also set this value globally for the whole video using the canvas header.

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. For example, the following scene keeps an image in view for two seconds.

(duration: 2)

![](image.png)

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 text with no backdrop
```

![](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

voice-emphasis

The voice-emphasis stage direction allows you to request a voice variant for the following paragraphs. 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 in the same scene.

Different voices support different emphasis styles, so experiment for best results.

Allowed valid values are:

  • strong
  • moderate
  • none (default)
  • reduced
This is my normal voice.

(voice-emphasis: moderate)

This is important.

You can also set the emphasis using the usual Markdown emphasis syntax. For more information, check out the reference on Controlling Pronunciation.

voice-speed

The voice-speed stage direction allows you to set the speed for the subsequent narration in the same scene. The options are the same as the voice-speed header, but the setting only applies to the current scene. 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.

(voice-speed: slow)

I'm usually slow in the mornings.

(voice-speed: normal)

After a coffee I speak normally.

voice-volume

The voice-volume stage direction allows you to set the volume for the subsequent narration in the same scene. The options are the same as the voice-volume header, but the setting only applies to the current scene. 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.

(voice-volume: loud)

I sometimes get angry!

(voice-volume: normal)

Then I calm down.