Formatting reference

This is a full reference to all the Narakeet 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.

Header
Scenes
Stage directions

Sections in this guide that are specific to creating videos from slides (PowerPoint files) are marked with a presentation icon on the left, such as this paragraph.

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.

Narakeet 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, ---), Narakeet treats everything until the next scene separator as the header.

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

When creating videos from a presentation (PowerPoint slides), you can set all these properties in the “Edit settings” screen. You cannot use the script header. However, you can modify most of these properties for a particular slide using 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

For videos made from presentations, you can the resizing option directly in the ‘Edit settings’ dialog, if you select a size different from the presentation size.

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

Narakeet supports WAV, MP3, WMA, 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

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

To use CSS colors, enclose the value in quote marks. Here is an example:

---
size: 800x600
canvas: "#00FF76"
---

![contain](image.jpg)

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

narration-language

The narration-language header allows you to specify the language for the text for voices that support multiple languages. Most Narakeet voices are trained for a single primary language (for example, Swedish voices can only read Swedish language text), but some voices can read more than one language. When you want to use a multi-lingual voice to read out text that is not in its primary language, this header is useful to specify the active language for the narration.

In the example below, Gertrud (primarily a German voice) will read out French text:

---
narration-language: fr-FR
voice: gertrud
---

Bonjour!

For more information on valid language codes to use with the narration-language header, check out the narration-language stage direction.

poster-time

Narakeet automatically creates a poster/cover image for your video from the first frame. You can select a different frame using the poster-time header. Valid options are:

start - selects the first frame
end - selects the last frame
a percentage (eg: 30%) selects a frame at a specific percentage of the final duration
a number of seconds (eg: 33) selects a frame at a specific timestamp
a timecode (eg 01:30) selects a frame at a specific timestamp

The default value is the middle frame of the video (50% duration).

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)
1440p: 1440p (Quad HD) (2560 x 1440 pixels)
4x3: 4:3 (for VGA projectors) (800 x 600 pixels)
720p-portrait: 720p portrait (720 x 1280 pixels)
1080p-portait: 1080p portrait (1080 x 1920 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)
tiktok: TikTok video (1080 x 1920 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 closed captions/subtitles from narration. Narakeet can either generate a subtitle track, or overlay the subtitles onto the video.

Overlaying subtitles (also called “burning”) puts the text directly into the video. This method works for all video players, but it permanently hides a part of the video content - users cannot turn the subtitles on or off.

Embedding subtitle tracks adds a MP4 subtitle track to the resulting video, and also generates external subtitle files (SubRip/SRT and Web Video Text Tracks/VTT) that allow users more flexibility. Video players that support subtitle tracks will allow users to turn the text on or off and customise the display. Most online video hosting platforms support importing either SRT or VTT files as subtitles, so this option also lets you use the native subtitle/closed caption function in YouTube, LinkedIn, Facebook and many other video sharing systems.

To configure the subtitles, specify the subtitle mode directly. The following values are supported:

external: generate SRT and VTT files as separate downloads. Useful for uploading to video hosting platforms (YouTube/Vimeo) and social media.
embed: create an embedded MPEG subtitle track in the result video, and generate SRT and VTT files as separate downloads. Users can turn on/off subtitles in the video player, but a video player must support subtitles to show them.
overlay: burn the subtitles onto the video (permanently shown). Users cannot turn off these subtitles, but they work in all video players.
overlay-background: burn the subtitles onto the video, with a semi-transparent black background.
tiktok: TikTok-style closed captions, with huge font in the middle of the video frame.
none: do not include any subtitles

Note that the previously supported value (auto) has been deprecated. It will still work in old scripts, but you should use the overlay value instead for new videos.

Here is an example:

---
subtitles: overlay-background
---

This narration will appear as a subtitle automatically

For examples, check out the Customising subtitle font and colors guide.

customising subtitles

You can also customise subtitle timing, by specifying a list of properties instead of just the mode. The following properties are supported:

Important note: the header section is specified as YAML, which uses # for a comment. If you want to specify a hex value with any of the color properties, make sure you enclose it into quotes, to prevent YAML ignoring it as a comment.

mode: embed or overlay (required)
break: maximum number of characters to show at a time on the screen, used to break long subtitle text into multiple subtitles.
scale: (only for overlay subtitles) number, specifying relative font size (use 1 for regular size, 0.5 for half-size, 2 for double-size and so on)
size: (only for overlay subtitles) integer, specifying font size in pixels. Generally, we recommend using the scale property to set the font size, as it will automatically choose the appropriate scale based on the video frame size. you can alternatively use the size property to specify an exact font in pixels
color: (only for overlay subtitles): the primary color of the subtitles (white by default). You can either specify a web color name (such as aqua or white), or specify a hex RGB/A value (eg "#FF0000" for red, and "#FF000099" for semi-transparent red).
outline: (only for overlay subtitles): the outline/shadow color of the subtitles (white by default). You can either specify a web color name (such as black or white), or specify a hex RGB/A value (eg "#000000" for black, and "#FF000099" for semi-transparent black).
background: (only for overlay subtitles): the background color of the subtitles (white by default). You can either specify a web color name (such as black or white), or specify a hex RGB/A value (eg "#000000" for red, and "#00000099" for semi-transparent black).
font: (only for overlay subtitles) - the name of a TrueType Font file (.TTF) file to use for the font overlay
position: (only for overlay subtitles) - where to place the subtitles/captions in the video frame. Options are top, middle and bottom (default).

Here is an example that shows red subtitles on a semi-transparent white background, breaking long subtitles into sections no longer than 80 characters:

---
subtitles:
  mode: overlay
  background: "#FFFFFF77"
  color: red
  break: 80
---

This narration will appear as a subtitle automatically

Here an example, setting the size to standard TikTok video frame, and setting the font position, size and choosing a custom font file to create an effect similar to how closed captions are used in popular TikTok videos.

---
size: 1080x1920
subtitles:
  mode: overlay
  break: 25
  size: 40
  font: CarterOne-Regular.ttf
  position: middle
---

This narration will appear as a subtitle automatically

For examples, check out the Customising subtitle font and colors guide.

target

Use the target header property to optimize video encoding and compression/quality and MOOV atom metadata storage for different use cases. This allows you to save bandwidth by creating smaller files for self-hosting, for example. Valid options are:

offline: (default) For professional use cases such as including into movies or video post-processing offline. Large files, very high quality and very low compression. Video metadata wil be stored at the end of the file.
online: For uploading to online sharing platforms, such as YouTube, Vimeo, Instagram and other social networks. Files will be slightly smaller and more compressed than the offline use case, so you can upload them faster, while still retaining very high quality, allowing video hosting platforms to transcode them effectively. The video metadata is stored at the start of the file, so processing can start faster.
self-hosted: For serving from your web site using HTML5 or including into mobile applications. Smaller files to save you on bandwidth and data management costs. The video metadata is stored at the start of the file for faster playback.

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, Narakeet 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 Narakeet 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, Narakeet 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-right - show the new scene over the old one, moving horizontally in from left to right
wipe - alias for wipe-right
wipe-left - show the new scene over the old one, moving horizontally in from right to left
wipe-up - show the new scene over the old one, moving vertically in from bottom to top
wipe-down - show the new scene over the old one, moving vertically in from top to
slide-right - push out the old scene, moving horizontally in from right to left
slide-left - push out the old scene, moving vertically in from bottom to top
slide-up - push out the old scene, moving vertically in from bottom to top
slide-down - push out the old scene, moving vertically in from bottom to top
fade-right - similar to wipe-right, but with a small fade effect
fade-left - similar to wipe-left, but with a small fade effect
fade-up - similar to wipe-up, but with a small fade effect
fade-down - similar to fade-down, but with a small fade effect
fade-circle - fade the new scene in growing from the center, with a small fade effect
slice-right - similar to wipe-right, but with progressive cut-outs instead of a single line
slice-left - similar to wipe-left, but with progressive cut-outs instead of a single line
slice-up - similar to wipe-up, but with progressive cut-outs instead of a single line
slice-down - similar to wipe-down, but with progressive cut-outs instead of a single line
dissolve - fine-grained dot effect
pixelize - coarse-grained dot effect
pixelise - alias for pixelize
radial - show the new scene over the old one, revealing as a clockwise wipe from the center
circle - shrink the old scene into the center, then grow the new scene, using a circle shape
rect - shrink the old scene into the center, then grow the new scene, using a rectangular
reveal - partial reveal
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-pitch

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

low
normal (default)
high
x-low (very low)
x-high (very high)
a numerical value between -150 and 150; negative values make pitch lower, positive make the pitch higher.

---
voice: Victoria
voice-pitch: high
---

This script will be read by Victoria in a high pitch.

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

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:

x-loud (extra loud)
loud
standard (default for each voice)
soft
x-soft (extra quiet)
normalized (EBU R128 normalization)

The standard value applies no volume adjustment, and uses the default value for each specific voice in the script. Note that different voices may have a different standard value. Previously, the normal value was used instead of standard, but it’s now deprecated to avoid confusion with normalized. The value normal still plays the voice at default volume, but we recommend using standard instead.

The normalized value will process each voice sample and adjust the volume according to the EBU R128 standard, making them loudness sound perceptually the same across multiple voices.

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

When creating videos from a presentation (PowerPoint slides), each slide is a separate scene. You do not normally need to create individual scenes. You can, however, use the scene separator in the speaker notes to split a single slide into several scenes.

This is the first scene

![](image1.jpg)

---

This is the second scene

![](image2.jpg)

Images

When creating video from a PowerPoint presentation, Narakeet automatically adds the current PowerPoint slide as the image for the scene. You do not need to add images manually.

Narakeet 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, Narakeet 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, Narakeet 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)

You can add multiple (non-animated) images into the same scene, and Narakeet will show them in a sequence, with each image visible approximately for the same duration. For example:

This scene has two images, showing in sequence

![left](file-1.png)

![left](file-2.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

When an image is larger than the video frame, you can either resize or animate it using the size property.

The following three size values will produce a static image:

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

The following five size values will produce a slight animation:

zoom - zoom gradually in, the animation starts at full cover size
pan - cover the video frame with the image, and then animate slightly moving to the specified position (requires the position property to be set)
panzoom - combine pan and zoom at the same time (requires the position property to be set).
zoomout - zoom gradually out, so that the animation starts zoomed in, and ends at full cover size
panzoomout - combine zoom out and panning (requires the position property to be set)

The Combined Pan/Zoom is often called the “Ken Burns effect”. Animating an image can make static frames more interesting for the viewers. For example, the following sequence produces a nice animated slideshow with the Ken Burns effect.

This scene has four images, showing in sequence with slight animations

![left panzoom](file-1.png)

![right pan](file-2.png)

![top zoom](file-3.png)

![bottom panzoomout](file-4.png)

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

When creating videos from PowerPoint presentations, just add a video file to your slide and it will be used automatically. If a slide contains a video, that video will automatically be used instead of the slide image. The rest of this section does not apply to videos created from presentations. Do not add a video reference to speaker notes, Narakeet will do this automatically – just embed a video into a slide.

Narakeet allows you to add video clips to the scene using the usual markdown syntax for linked images. Narakeet supports adding MP4, QuickTime MOV, M4V, WMV, AVI and MPEG videos.

![](video.mp4)

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

(video: file.mp4)

Resizing videos

When adding a video to a scene, Narakeet 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)

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

You can specify the segment either as a short-hand property within the square brackets in the ![]() syntax, or as a subproperty of a video stage direction.

Here is an example of using the shorthand property (note that there must be no blanks between the timecode segments):

![00:02-00:04](stopwatch.mp4)

Here is the same example, as a stage direction. In this case, you can also use spaces between the timecode boundaries to make them easier to read.

(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, or providing a single timecode.

![start](stopwatch.mp4)

---

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

---

![01:20](stopwatch.mp4)

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

For videos from PowerPoint presentations, speaker notes are used as scene narration. All the instructions from this section are valid for videos created from presentations. Just remember to type your text into speaker notes for a slide.

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.

Narakeet 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

There are several ways you can tweak the pronunciation of a phrase or a group of words. This section outlines the major options:

Inline Emphasis

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

This is the same as using the voice-emphasis stage direction, but simpler for short bits of text.

Using Narration Spans

Narration spans allow you to set the narration style or the narration language easily inside a sentence.

Enclose a word or a phrase in square brackets, followed by the properties in curly braces, to modify the pronunciation for that section. The properties can be any supported narration style or narration language.

For example, the following snippet uses the literal narration style for the first word.

[control]{literal} is the way to spell control

Changing the narration style

Narration styles control how a word is pronounced. The supported styles are:

normal - just reads the word out as usual
ipa - uses the IPA phonetic alphabet to specify pronunciation
x-sampa - uses the X-SAMPA phonetic alphabet to specify pronunciation
literal - reads out the letters instead of the word

For example, the following snippet mixes the American and the British pronunciation of the word “tomato” in the same voice:

(voice: victoria)

Is it [təˈmeɪ.toʊ]{ipa} or [tʰə̥ˈmɑːtʰəʊ]{ipa}?

Note that individual voices support only certain styles. Most support literal pronunciation, some support IPA, and very few support X-SAMPA. Check the Narration Styles reference to learn which style are supported by your preferred voices

IPA and X-SAMPA support is very experimental at this phase and individual voices support only certain phonemes. Make sure to test with your chosen voice if it can pronounce the IPA or X-SAMPA phonemes correctly.

Changing the narration language

List a two-letter ISO code of a supported language in the narration span properties to temporarily change the language for reading.

(voice: mike)

The german word *[See]{de}* and the English word *See* have the same spelling: `see`

Note that most voices are trained on only one language, and the support for secondary languages is experimental. Make sure to test with your chosen voice if the secondary language phrases are pronounced correctly.

For more information on valid language codes, check out the narration-language stage direction.

Spelling out words

For the literal narration style (spelling out words), you can also use backticks.

Enclose a phrase between two back-ticks (`), and Narakeet 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`.

Adding pauses between sentences or words

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 three 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 also make the narrator wait for a specific timestamp, using the pause-until stage direction. This is useful to synchronise the audio with a screencast or a video. For example, in the following block, the second sentence will start exactly 10 seconds after the scene begins, regardless of how long the first sentence takes (as long as it is shorter than 10 seconds).

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

(pause-until: 10)

This is the second sentence.

The pause-until stage direction cannot be used to play audio clips in parallel. In the previous example, if the preceding block ends after the 10th second, the second sentence will play immediately after it.

Additional tips

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

When creating a video from a PowerPoint presentation, just embed an audio file to a slide to use your own voice or professionally recorded audio for narration. The rest of this section does not apply to videos created from presentations. Do not set the audio scene direction manually inside the speaker notes, Narakeet will do that automatically for you.

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. Narakeet supports WAV, MP3, WMA, 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

Narakeet 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 >).

Narakeet will read this

> Narakeet will show this instead

You can use this feature in videos created from PowerPoint slides by typing the subtitles in the speaker notes, similarly to the narration text. Just make sure to start subtitles with >.

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

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

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

![](image.png)

<!-- 

this is just a comment,
Narakeet will ignore it

-->

Stage directions

Stage directions are commands to Narakeet 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)

You can use stage directions in videos created from PowerPoint slides by entering them the speaker notes, similarly to the narration text. Just make sure to enclose them in brackets, and leave a blank line before and after.

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

Narakeet will gray out the rest of the background image or scene, and leave the callout area highlighted. You can optionally control the intensity of the shading.

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

You can use the Callout Designer to visually position and create script for callouts.

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 the radius as a size property, 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)

Controlling background shading

To make the highlighted area stand out, a callout applies a transparent shade over the remaining part of the background. You can control the intensity of the shading (and by implication the contrast between the highlighted and non-highlighted part of the image or video) using the alpha property. This is available for all types of callouts. Alpha is the value of the alpha channel (opacity) of the shading, between 0 and 1. 1 is completely opaque, and 0 is completely transparent. The default value is 0.5.

For example, this callout provides more contrast than the default one:

![](image.png)

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

Masking an area instead of highlighting it

You can also use callouts to hide or mask a part of a video or image, instead of highlighting it. For example, to paint a dark opaque rectangle over a password or credit card field. To to that, add a style property to the callout, and use mask as the value. For example, the following callout paints a black rectangle over an area:

![](image.png)

(callout:
  type: rectangle
  style: mask
  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. See the header entry for valid values.

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.

image-size

The image-size scene direction sets the default for the image size for the assets that follow in the same scene. This can be useful to set the image resizing options for a single slide in PowerPoint presentations, or when you want to apply a single size property to multiple images in the same scene. See Scene images for more information on available sizing options and valid values for this stage direction.

(image-size: panzoom)

![](image.png)

image-position

The image-position scene direction sets the default value for the image position for the assets that follow in the same scene. This can be useful to set the image resizing options for a single slide in PowerPoint presentations, or when you want to apply a single position property to multiple images in the same scene. See Scene images for more information on available position options and valid values for this stage direction.

(image-position: top)

![](image.png)

narration-mode

The narration-mode stage direction lets you control the pause at the end of a narration block. Normally, Narakeet adds a small narrative break, akin to ending a paragraph, at the end of each block of text. This is great for most use cases, but it is not good if you want to split a single sentence across multiple scenes or slides.

Setting the narration-mode lets you control the audio flow.

If you want to show multiple scenes during a single sentence, revealing the second image precisely for a given word, set the narration-mode to fragment before the fragmented sentence part. For example:

(narration-mode: fragment)

the correct answer is

---

twenty!

If you want to show multiple scenes during a single sentence, but you don’t care about showing the images at a specific time, set the narration-mode to merge, and put the entire narration in the first block. Then switch the narration mode back to normal at the end of the sequence. For example:

(narration-mode: merge)

Time flies when you're having fun

![](image1.png)

---

![](image2.png)

---

![](image3.png)

(narration-mode: normal)

Valid values for narration-mode are:

fragment - reduces the pause at the end of the following narration blocks to sound more like a break between words in a sentence.
merge - records the narration of merged slides together (so it flows continuously) and shows each scene image for a proportion of the time in a continuous slideshow.
normal - uses a pause at the end of narration blocks that sounds like a pause between paragraphs. Use this to turn off merged narration in the last scene of the sequence.

The big difference between merge and fragment is the synchronisation point. With fragment, each scene is synchronised with its own audio, and the transition just has a smaller audio break. With merge, the whole sequence of images is synchronised with a single audio block. Use the fragment mode to control synchronisation precisely, and the merge block to have uninterrupted audio spanning several images.

The merge narration mode is mostly useful for marking sequences of presentation slides. If you’re composing a video from a script, just add multiple images into the same scene. This has the same effect, and it is simpler.

narration-language

The narration-language stage direction sets the pronunciation language, without changing the voice. This is useful to temporarily switch to a different language, but keep the narration consistent. A typical case is including a foreign word or phrase. Note that the narration voices are trained in a specific language, so this does not create native-speaker experience. Instead, it sounds as if a foreign person speaks the target language. (For example, if the active voice is ‘Helmut’ and you switch the narration language to English, it will sound as if someone speaks English with a German accent).

Here is an example that temporarily switches to German for a single word.

German word 

(narration-language: de)
See 

(narration-language: default)
and English word See have the same spelling: `see`

Valid values for narration-language are:

default: switches back to the default language for the active voice
an ISO 639-1 alpha-2 code (for example, en or de for English or German)
an ISO 639-1 alpha-2 code followed by a dash, and a ISO 3166-1 alpha-2 region code (for example, fr-CA for Canadian French).

Only the language/region combinations currently supported by Narakeet are valid. Not all voices can pronounce all the language combinations, so make sure to test language switching with a preview before building the whole video.

Note that you can also use the shorthand inline syntax [phrase]{language} to switch language inside a sentence, without using this stage direction. Here is an example:

German word *[See]{de}* and English word *See* have the same spelling: `see`

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.

pause-until

The pause-until stage direction waits until a specific time since the start of the current scene. This is useful to synchronize audio with an existing video resource, or a screencast, allowing you to easily start sections of voiceover at specific times. The value should be a number of seconds, or a timecode.

This is the first sentence.

(pause-until: 6)

This will start at 6 seconds from the beginning of the scene.

In a multi-scene script, pause-until works from the beginning of the current scene. (For example, if you embed a video in a powerpoint slide to create a scene, the timecodes would be synchronized with that video, regardless of previous slides and scenes).

The maximum delay you can create with a pause-until stage direction is 10 minutes.

The pause-until stage direction cannot be used to move an audio segment before the end of the previous one (you cannot use it to play audio segments in parallel). If the previous segment ends after the requested timecode, there will be no pause and the current segment will just play immediately after the previous one.

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-pitch

The voice-pitch stage direction controls the pitch of the subsequent narration in the same scene. The options are the same as the voice-pitch 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-pitch: high)

I can sound excited with a high pitch

(voice-speed: low)

Or disappointed with a low pitch

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.

Formatting reference

Header

asset-resize

background

Your own background music

Provided background music

Adjusting background music volume

Fade background music in or out

canvas

narration-language

poster-time

size

subtitles

customising subtitles

target

theme

Customising slide themes using CSS

Changing fonts

Adding a background

Managing the image backdrop

transition

voice

voice-pitch

voice-speed

voice-volume

Scenes

Images

Available sizing options

Available position options

Using animated GIFs

Supported synchronisation options

Videos

Resizing videos

Available sizing properties

Extracting segments from videos

Synchronising narration and video

Supported synchronisation options

Manipulating video volume

Narration

Controlling voices

Controlling pronunciation

Inline Emphasis

Using Narration Spans

Changing the narration style

Changing the narration language

Spelling out words

Adding pauses between sentences or words

Additional tips

Using SSML

Audio files

Subtitles

Text slides

Controlling slide visuals

Rich text slides

Syntax highlighting

Controlling font size

Comments

Stage directions

audio

callout

Circle highlights

Controlling circle size

Rectangular highlights

Controlling background shading

Masking an area instead of highlighting it

canvas

duration

font-size

image

image-size

image-position

narration-mode

narration-language

pause

pause-until

theme

transition

video

voice

voice-emphasis