Voice-Over

The Voice Over Presenter plays a recorded audio clip for each line. It doesn’t show any text, so most games use it alongside a Line Presenter, which shows the line as a subtitle while the clip plays.

Adding a Voice Over Presenter

1. Add a GameObject to your scene, such as a child of your Dialogue System. Click Add Component in the Inspector, and search for Voice Over Presenter.
2. Select the Dialogue Runner, and add the GameObject to its Dialogue Presenters list, next to your Line Presenter.
3. Put your audio clips in a folder, named after each line’s ID, and set that folder as your Yarn Project’s Assets Folder. See Naming your audio files.

The Voice Over Presenter plays clips through the Audio Source in its Audio Source setting. When you add a Voice Over Presenter, it picks up an Audio Source on the same GameObject or one of its children, if there is one. If Audio Source is still empty when the game runs, the Voice Over Presenter adds its own, with Spatial Blend set to 2D.

Using your own Audio Source lets you choose its settings. Set its Output to send voice-over to its own Audio Mixer Group, with its own volume. For sound that comes from somewhere in your game world, put the Audio Source on a GameObject at that spot, and set its Spatial Blend towards 3D.

Naming your audio files

The Voice Over Presenter doesn’t look for clips itself. It plays the asset that the Dialogue Runner’s Line Provider finds for each line, and the Line Provider finds it by the line’s ID. Give every line an ID with a #line: tag:

Tom: Uh.. hello? #line:tutorial-tom-01
Tom: Is anyone there? #line:tutorial-tom-02
Anne: Hi there! #line:tutorial-anne-01

To add IDs to every line that doesn’t have one, select your Yarn Project, and click Add Line Tags to Yarn Scripts in the Inspector. See Yarn Projects.

Name each clip after its line ID, without the line: part, and put the clips in one folder:

Assets/Dialogue/Audio-en/tutorial-tom-01.wav
Assets/Dialogue/Audio-en/tutorial-tom-02.wav
Assets/Dialogue/Audio-en/tutorial-anne-01.wav

Then tell the Yarn Project where the folder is:

1. Select your Yarn Project, and find the Localisation section in the Inspector.
2. Find the entry for your base language. If there isn’t one, click Add Localisation, which adds one for the base language.
3. Drag the folder into the entry’s Assets Folder field, and click Apply.

When the Yarn Project imports, Yarn Spinner looks through the folder, and its subfolders, for a file named after each line ID. Case doesn’t matter. If no file has exactly that name, it uses a file whose name contains the line ID, so tutorial-tom-01-de.wav works too. When you add or change a file in the folder, the Yarn Project imports again and picks it up.

The Dialogue Runner’s Line Provider then hands each line’s clip to your Presenters along with its text. If your Dialogue Runner has no Line Provider set, it uses a Built-in Localised Line Provider, which gets clips from the Yarn Project like this. See Line and Asset Providers.

Audio in more than one language

If your game has voice-over in more than one language, give each language its own folder of clips, and its own entry in the Yarn Project’s Localisation section, with Assets Folder set to that folder.

The Built-in Localised Line Provider has two language settings: Text Locale Code, for the language of the text, and Asset Locale Code, for the language of the clips. You can show text in one language and play audio in another. To fall back to another language when a line has no clip in the chosen one, turn on Use Fallback, and set Fallback Locale Code.

If you use Unity’s Localization package, use a Unity Localised Line Provider instead. It gets clips from the asset table in its Asset Table setting. To fill the table from your folders of clips, choose Window›Yarn Spinner›Add Assets to Table Collection. It matches file names to line IDs in the same way.

See Localising Your Game for the text side of translation.

Assets that aren’t audio clips

A line’s asset doesn’t have to be an AudioClip. If it’s another kind of asset that implements IAssetProvider, the Voice Over Presenter asks it for an AudioClip and plays that. This lets one asset hold a line’s audio along with other data that other Presenters use. The Voice Over sample does this, with an asset that holds each line’s audio and the timings to move the character’s mouth.

When the line ends

By default, when a line’s clip finishes, the Voice Over Presenter ends the line, and the dialogue moves on without the player pressing anything.

To make the player continue each line themselves, turn off End Line When Voiceover Complete. The Line Presenter then waits for the player, as usual.

Either way, if the player continues before the clip has finished, the clip fades out over Fade Out Time On Line Finish seconds, 0.05 by default, and the next line starts.

To leave a gap around each clip, use Wait Time Before Line Start, the seconds to wait before the clip starts, and Wait Time After Line Complete, the seconds to wait after it finishes before ending the line.

Settings

Samples

The Voice Over sample has voice-over in four languages and text in five, and characters whose mouths move as they speak. It has two scenes that differ only in how they’re localised: one uses Yarn Spinner’s built-in localisation, and the other uses Unity’s Localization package. To add it to your project, see Samples.