Audio

To add, edit or remove background music (BGM) and sound effect (SFX) resources, open the Naninovel -> Configuration -> Audio editor menu and click the "Manage BGM Resources" or "Manage SFX Resources" button to access the corresponding resources manager. You can use any audio formats supported by Unity ↗.

TIP

Choose file formats that are most comfortable for your development workflow. When building the project, Unity will automatically convert all the source resources (textures, audio, video, etc) to the formats most suitable for the target platform, so it won't make a difference in which format you originally store the resources in the project. Find more information on how Unity manages project assets in the official documentation ↗.

In case you have a lot of audio files and it's inconvenient to assign them via the editor menu, it's possible to just drop them in the Resources/Naninovel/BGM (music) and Resources/Naninovel/SFX (sound effects) folders, and they'll automatically be available in the scripts. You can additionally organize them with subfolders, if you wish; in this case use forward slashes (/) when referencing them in scenario scripts. Eg, an audio clip stored as Resources/Naninovel/BGM/Ambient/Noise002.wav can be referenced in scripts as Ambient/Noise002.

It's also possible to use the Addressable Asset System to manually expose the resources. To expose an asset, assign an address equal to the path you'd use to expose it via the method described above, except omit the "Resources/" part. Eg, to expose a "MainTheme.wav" BGM, assign the clip asset the following address: Naninovel/BGM/MainTheme. Be aware that while in the editor, a special "Editor" resource provider is always used first; the addressable provider is only tried for the resources that are not assigned via the editor menus.

WARNING

Audio assets not assigned via the resources manager won't be available in various editor dropdowns, such as the one used to select Message Sound for a character actor.

Audio playback behaviour can be configured using the Naninovel -> Configuration -> Audio editor menu; for available options, see the configuration guide.

Background Music

Use the @bgm command followed by the clip name to control the music playback in scenario scripts:

; Start playing a music track with the name "Sanctuary" in a loop.
@bgm Sanctuary

; Same as above, but fade in the volume over 10 seconds and play only once.
@bgm Sanctuary fade:10 !loop

; Change the volume of all the played music tracks to 50% over 2.5 seconds
; and make them play in a loop.
@bgm volume:0.5 loop! fade:2.5

Music tracks are looped by default. When a music track name is not specified in the @bgm command, all currently played tracks will be affected. When invoked for a track that is already playing, the track won't restart, but the specified parameters (volume and whether the track is looped) will be applied.

It's possible to play an intro followed by a loop with the intro parameter, eg:

; Play "BattleThemeIntro" once and then "BattleThemeMain" in a loop.
@bgm BattleThemeMain intro:BattleThemeIntro

To stop a playing music track, use the @stopBgm command followed by the clip name. When a clip name is not specified, the command will stop all currently played tracks.

; Fade out the "Promenade" music track over 10 seconds and stop the playback.
@stopBgm Promenade fade:10

; Stop all the currently played music tracks.
@stopBgm

Sound Effects

Use the @sfx and @stopSfx commands followed by the clip name to control playback of sound effects in scenario scripts:

; Play an SFX with the name "Explosion" once.
@sfx Explosion

; Play an SFX with the name "Rain" in a loop.
@sfx Rain loop!

; Change the volume of all the played SFX tracks to 75% over 2.5
; seconds and disable looping for all of them.
@sfx volume:0.75 !loop fade:2.5

Sound effect tracks are not looped by default. When an SFX track name is not specified in the @sfx command, all currently played tracks will be affected. When invoked for a track that is already playing, the track won't restart, but the specified parameters (volume and whether the track is looped) will be applied.

To stop a playing sound effect (looped or not), use the @stopSfx command followed by the clip name. When a clip name is not specified, the command will stop all currently played SFX tracks.

; Stop playing an SFX with the name "Rain", fading out for 15 seconds.
@stopSfx Rain fade:15

; Stop all the currently played sound effect tracks.
@stopSfx

Spatial Audio

All audio commands support pos and wpos parameters, which, when specified, enable spatial mode — aka "3D audio" — where the associated audio source will be configured to respond to its position relative to the audio listener. Use pos to place the source relative to the scene borders in percent (0,0 is the bottom left and 100,100 is the top right) or wpos to place it in world space.

; Play "Explosion" slightly above and behind the listener in world space.
@sfx Explosion wpos:0,1,-3

It's possible to animate the position like any other parameter:

; Pan "Rain" position right-left-right in scene space until stopped.
@async Rainpan loop!
    @sfx Rain pos:100,50 fade:10
    @wait 10
    @sfx Rain pos:0,50 fade:10
    @wait 10

...

@stop Rainpan

The default audio listener position is at x0 y0 z-1, which is slightly behind the scene origin, so you won't always have to offset the audio position along the Z-axis to achieve a more natural sound position.

Audio Mixer

Naninovel uses an audio mixer ↗ asset when playing the audio to separate BGM, SFX and voice channels.

It's possible to assign a custom mixer asset, change groups used for each audio channel and change volume control handles (exposed parameter names) in the audio configuration menu. When no custom mixer asset is assigned, a default one will be used.

To play audio via a custom mixer group, specify a group path with the group parameter available in @bgm, @sfx and @voice commands.

; Play "Noise" audio resource in a loop via "Master/Ambient" mixer group.
@sfx Noise loop! group:Master/Ambient

; Play "ScaryVoice" voice resource via "Master/Reverb" mixer group.
@voice ScaryVoice group:Master/Reverb

Groups are retrieved with the FindMatchingGroups(groupPath) method of the currently assigned audio mixer asset; see the Unity documentation ↗ for more information on the expected path format. In case multiple groups are associated with the provided path, the first one will be used to play the audio.

Custom Audio Backend

Unity allows replacing its built-in audio backend with custom solutions, such as FMOD ↗ and Wwise ↗. To support this, we've ensured that Naninovel's IAudioManager interface doesn't depend on the default audio backend (for example, it doesn't reference AudioClip, AudioSource, etc). This allows you to override the service and use a custom audio backend without modifying the engine's source code.

Below is a minimal example of such an override for FMOD.

[InitializeAtRuntime(@override: typeof(AudioManager))]
public class FMODAudioManager : IAudioManager
{
    // Assuming FMOD resource loading is managed externally.
    public IResourceLoader SfxLoader { get; } = new NullResourceLoader();

    // Assuming FMOD's lifecycle is managed externally.
    public Awaitable InitializeService () => Async.Completed;
    public void DestroyService () { }

    public Awaitable PlaySfx (string path, ...)
    {
        // Resolve the FMOD event reference from the path and play it.
    }

    public AudioMixerGroup GetGroup (string groupPath)
    {
        // It's OK to return null or otherwise ignore unsupported features.
        return null;
    }

    // Other APIs...
}