Voiceover
Preface supports per-step audio narration. You can write a script and generate it using AI, or upload your own MP3. Voiceover plays automatically when a viewer reaches each step.
A screenshot of the voiceover editor panel on the right-hand side will go here.
ElevenLabs API key required
AI voiceover generation is powered by ElevenLabs. To use it, you need an ElevenLabs account and API key — this is separate from your Preface subscription and is billed directly by ElevenLabs.
To set up your API key:
- Create an account at elevenlabs.io if you don't have one
- Go to elevenlabs.io/app/api/api-keys and create a new key
- When configuring the key's permissions, enable the following:
| Endpoint | Permission required |
|---|---|
| Text to Speech | Access |
| Voices | Read |
All other endpoints can be left at No Access.
- Copy the key and paste it into Workspace Settings → ElevenLabs API key
Once saved, the Generate Audio button in the voiceover editor will become active.
Uploading your own MP3 does not require an ElevenLabs account.
Anthropic API key required for AI Improve
AI Improve is powered by Anthropic. It improves the written script for a single step before you generate audio.
To use it, an owner must add an Anthropic API key in Workspace Settings → Anthropic API key. If no workspace key is set, Preface uses the server-level ANTHROPIC_API_KEY if one is configured.
AI Improve changes script text only. It does not generate audio. Use Generate Audio after applying and saving an improved script.
Writing a script
In the right-hand panel of the editor, you'll find the Voiceover section. Type your narration for the current step in the script field.
A good voiceover script:
- Is written as you'd speak it, not as you'd write it
- Is concise — aim for 10–20 seconds per step
- Tells the viewer what to notice, not just what they can already see
Improving a script with AI
Click AI Improve to ask Preface to rewrite the current step's script using:
- The current script text
- The current step screenshot
- Persistent context from the other steps in the demo
Preface may need to analyse other steps first, especially the first time you use AI Improve on a demo or after step content changes. While this runs, the editor shows progress for the context analysis and final rewrite.
When the suggestion is ready, it appears as a preview:
- Apply — copies the suggestion into the script editor and marks the script as changed
- Dismiss — closes the suggestion without changing the script
Applying a suggestion does not save it automatically. Click Save to persist the improved script, or Generate Audio to save it and create new voiceover audio.
AI Improve is designed to expand short drafts into more polished narration. Start with a basic description of what the step should communicate, then use the suggestion as a stronger first pass.
How AI Improve handles annotation tags
Voiceover scripts can contain timed annotation tags such as [HIGHLIGHT:...], [TOOLTIP:...], and [SCROLL:...]. AI Improve protects these tags.
Before sending text to Anthropic, Preface splits the script into text chunks around the annotation tags. Anthropic only receives the text chunks. Preface then reassembles the improved script with the original tags inserted back in the same order.
This means AI Improve:
- Does not add new annotation tags
- Does not edit existing annotation tag coordinates, colours, or text
- Does not remove or reorder existing annotation tags
- Improves only the narration around the tags
For example:
Before:
Open the report [HIGHLIGHT:120,340,200,40,#ef4444] and review the trend.
After:
Start by opening the report [HIGHLIGHT:120,340,200,40,#ef4444] so viewers can focus on the trend that matters most.
Saving a script
The script editor has three main action buttons:
- AI Improve — suggests a stronger version of the current script. Applying the suggestion updates the editor but does not save automatically.
- Save — persists the current script text without generating audio. Useful when you want to save your work and come back to generate later. Disabled until you make a change.
- Generate Audio — saves the script and immediately generates audio from it. Enabled when there is no audio yet, or when the script has been edited since the last generation.
Generating audio with AI
Once you've written your script, click Generate Audio. Preface saves your script and uses AI voice synthesis to convert it into a natural-sounding narration.
A screenshot showing the Generate Audio button and the audio player after generation will go here.
Generation takes a few seconds. Once complete, an audio player appears so you can preview the result before your viewers hear it.
If the generated voice doesn't sound quite right, try adjusting your script. Shorter sentences with clear punctuation tend to produce the best results. You can regenerate as many times as you like.
Uploading a custom MP3
Prefer your own voice or a professional recording? Click Upload MP3 to upload any MP3 file. This replaces any existing generated audio for that step.
Accepted formats: MP3, MP4 audio, OGG, WAV, WebM.
Removing audio
Click Remove audio beneath the audio player to delete the voiceover for that step. Viewers will not hear anything on steps without audio.
Highlight markers
Highlight markers let you draw the viewer's attention to a specific area of the screenshot in sync with the voiceover. As the audio plays, coloured rectangles pulse into view at the times you specify.
Adding a highlight
Click inside the script textarea to focus it, then click Highlight in the Add annotation bar that appears below. This opens the highlight picker:
- Click and drag over the area of the screenshot you want to highlight
- Choose a colour from the palette
- Click Insert — a marker tag is inserted into your script at the current cursor position
The marker looks like this in your script:
[HIGHLIGHT:x,y,width,height,color]
You don't need to edit this manually — the picker handles it for you.
How it works
When the audio plays and reaches the timestamp where the highlight tag appears, the coloured rectangle fades in over that area of the screenshot. This draws the viewer's eye without interrupting the narration.
A screenshot showing a highlight marker active during playback will go here.
Previewing a highlight
While editing your script, click anywhere inside a [HIGHLIGHT:...] tag to see a live preview of the rectangle overlaid on the step image. The preview clears when you move the cursor outside the tag.
Highlight markers only work with AI-generated audio. If you've uploaded a custom MP3, the timing information needed to sync highlights is not available.
Clearing a highlight
To remove an active highlight mid-narration, insert a bare [HIGHLIGHT] tag (no parameters) at the point in the script where it should disappear:
...and here you can see the export options. [HIGHLIGHT:120,340,200,40,blue] Click Export to download your report. [HIGHLIGHT] The file will appear in your downloads folder.
When playback reaches the bare [HIGHLIGHT], the rectangle fades out.
Tooltip markers
Tooltip markers display a small text callout over a specific point on the screenshot, synced to the audio. Use them to label UI elements or add short contextual notes without needing a full highlight box.
Adding a tooltip
Click inside the script textarea to focus it, then click Tooltip in the Add annotation bar. This opens the tooltip picker:
- Click anywhere on the screenshot to position the tooltip anchor
- Type the tooltip text in the field below the image — line breaks are supported and will be preserved
- Click Insert — a marker tag is inserted into your script at the current cursor position
You can re-click the image to reposition before inserting. A live preview of the tooltip bubble appears on the image as you type.
Syntax
The tag inserted into your script looks like this:
[TOOLTIP:x,y,label text]
- x, y — pixel coordinates on the screenshot (top-left origin)
- label text — the text shown in the tooltip; may contain commas; use
\nfor line breaks
Example:
Click the Settings icon [TOOLTIP:840,52,Settings icon] to open the configuration panel.
When the audio reaches that point, a small dark pill appears at the specified coordinates with the label text.
Clearing a tooltip
Insert a bare [TOOLTIP] tag to remove the active tooltip:
Click the Settings icon [TOOLTIP:840,52,Settings icon] to open the panel. [TOOLTIP] From here you can manage your account.
Previewing a tooltip
While editing your script, click anywhere inside a [TOOLTIP:...] tag to see a live preview of the tooltip at the specified coordinates on the step image.
Like highlight markers, tooltips only work with AI-generated audio. Timing information is not available for uploaded MP3s.
Scroll markers
Scroll markers move a scrollable screenshot to a specific vertical position in sync with the generated voiceover. Use them on steps captured as a full page or hovered scroll panel.
Adding a scroll marker
- Scroll the screenshot in the editor to the position you want viewers to see
- Click inside the script textarea where the scroll should happen
- Click Scroll in the Add annotation bar
Preface inserts a marker like this:
[SCROLL:y]
The y value is the current vertical scroll depth in the captured screenshot. You normally do not need to edit it manually.
How it works
When playback reaches the marker, the player smoothly scrolls the captured page or panel to that position. During the movement, Preface shows an artificial scrollbar so viewers understand that the demo is simulating a scroll action.
Annotations inside the scrollable region move with the screenshot content as it scrolls. Annotations outside the scrollable region stay fixed.
Previewing a scroll marker
While editing your script, click anywhere inside a [SCROLL:...] tag to move the editor screenshot to that scroll position.
Scroll markers only work with AI-generated audio. If you've uploaded a custom MP3, the timing information needed to sync scrolling is not available.
Auto-advance
When Auto advance is enabled, the demo moves to the next step automatically 3 seconds after the audio finishes — without the viewer needing to click.
Toggle the Auto advance switch in the voiceover panel (visible when audio is present on the step).
This is ideal for:
- Fully automated demo flows
- Embedded demos where you want zero interaction required
UI click simulation
If you want to simulate a click interaction as part of the auto-advance, you can set a UI click position. This shows an animated mouse cursor moving to a point on the screenshot and making a click, as if a real user is interacting with the product.
A screenshot or GIF showing the cursor animation and click effect will go here.
To set a UI click:
- Enable Auto advance on a step with audio
- Click Set UI click
- In the picker, click the exact spot on the screenshot where the click should occur
- Click Confirm position
Timing during playback:
- The cursor appears and moves to the target position
- At 2 seconds after audio ends, the click animation and sound play
- At 3 seconds, the demo advances to the next step
The cursor position is remembered from step to step. On consecutive steps with UI clicks, the cursor travels from the previous click position to the new one, creating a realistic sense of a user navigating through your product.
Click Edit UI click to reposition, or Clear to remove it.