Lucid Audio

Simple audio player for Unity

Overview

Lucid Audio is a library that handles audio playback in Unity. You can easily describe how to play and stop sounds, set callbacks, etc. using method chaining.

Features

Simple description method using method chaining
Advanced settings such as delays and callbacks
Play/stop timing can be linked to GameObject

Requirement

Unity 2019.4 or higher

Install

Open the Package Manager from Window > Package Manager
"+" button > Add package from git URL
Enter the following to install
- https://github.com/AnnulusGames/LucidAudio.git?path=/Assets/LucidAudio

or open Packages/manifest.json and add the following to the dependencies block.

{
    "dependencies": {
        "com.annulusgames.lucid-audio": "https://github.com/AnnulusGames/LucidAudio.git?path=/Assets/LucidAudio"
    }
}

Namespace

When using Lucid Audio, add the following line at the beginning of the file.

using AnnulusGames.LucidTools.Audio;

Basic Usage

Use LucidAudio class to play audio.

public Audioclip clip;

private void Start()
{
    // play sound effect
    LucidAudio.PlaySE(clip);
}

Use method chaining to set delays, callbacks, etc.

// After waiting for 1 second, play BGM with Volume 0.7 and display "Complete!"
LucidAudio.PlayBGM(clip)
    .SetVolume(0.7f)
    .SetDelay(1f)
    .OnComplete(() => Debug.Log("Complete!"));

These methods have an AudioPlayer class as a return value. If you want to pause the audio or change settings during playback, call AudioPlayer methods.

AudioPlayer player = LucidAudio.PlaySE(clip);

// pause/resume audio
player.Pause();
player.UnPause();

// play audio from beginning
player.Restart();

Use FadeVolume or add an argument when playing/stopping to fade the volume.

// fade the first second
AudioPlayer player = LucidAudio.PlayBGM(clip, 1f);

// Change volume to 0.7 over 1 second
player.FadeVolume(0.7f, 1f);

// stop after 2 seconds fade out
player.Stop(2f);

Constraint

AudioPlayer dispose its internal AudioSource when you call Stop, so it cannot be used again after stopping. Attempting to call Play or Restart on a stopped AudioPlayer will throw InvalidOperationException.

AudioPlayer player = LucidAudio.PlayBGM(clip);
// stop playing audio
player.Stop();

// InvalidOperationException: A stopped AudioPlayer is not allowed to play again. You need to create a new AudioPlayer.
player.Restart();

If you want to play the stopped AudioPlayer again, use Pause instead of Stop.

Also, in the default setting, Stop is automatically called at the end. By setting SetAutoStop to false, you can set the AudioPlayer to return to its pre-play state when playback ends.

AudioPlayer player = LucidAudio.PlayBGM(clip)
    .SetAutoPause(false);

// Play, UnPause, and Restart can be used even after termination
player.Play();

// Explicitly call Stop when finished, as it is not automatically disposed
player.Stop();

Callbacks

Lucid Audio makes it easy to set callbacks using methods. Below is a list of callbacks that can be set on the AudioPlayer.

OnStart

Called at the moment the audio starts playing. If a delay is set with SetDelay, it will be called when the delay ends.

OnPlay

Called every frame while audio is playing. Not called while paused.

OnPause

Called when the audio is paused.

OnComplete

Called when the audio has finished playing. It is not called if you stop playback with Stop.

OnStop

Called when the audio has stopped. Also called on completion if SetAutoStop is not set.

3D Sound

By setting the value with SetSpatialBlend, you can play audio considering the distance to the sound source.

// Set Spatial Blend to 1
LucidAudio.PlaySE(clip)
    .SetSpatialBlend(1f);

Use SetPosition to specify the position of the sound source.

// play sound effect at position (1, 2, 3)
LucidAudio.PlaySE(clip)
    .SetSpatialBlend(1f)
    .SetPosition(new Vector3(1f, 2f, 3f));

Parameters such as Rolloff Mode and Max Distance can also be set using methods.

LucidAudio.PlaySE(clip)
    .SetSpatialBlend(1f)
    .SetPosition(new Vector3(1f, 2f, 3f))
    .SetMaxDistanc(10f)
    .SetRolloffMode(AudioRolloffMode.Logarithmic);

Grouping

By setting an ID for AudioPlayer, multiple AudioPlayers can be handled collectively. Use SetID to set the ID.

// Set ID to AudioPlayer
LucidAudio.PlaySE(clip)
    .SetID("GroupName");

If you want to collectively manipulate audios with IDs, add the IDs to the arguments of the LucidAudio class methods.

// Stop all AudioPlayers whose ID is set to "GroupName"
LucidAudio.StopAll("GroupName");

Also, by using GetPlayersByID, you can get all AudioPlayers with matching IDs.

// Get all AudioPlayers whose ID is set to "GroupName"
AudioPlayer[] players = LucidAudio.GetPlayersByID("GroupName");

// Set Volume to 0.5
foreach (AudioPlayer player in players)
{
    player.SetVolume(0.5f);
}

SetLink

By using SetLink, it is possible to link the audio playback/stop timing to the state of the GameObject.

// Call Stop when gameObject is destroyed
LucidAudio.PlayBGM(clip)
    .SetLink(gameObject);

By specifying AudioLinkBehaviour as an argument, detailed behavior can be set. (Stop is called at OnDestroy regardless of which option is specified.)

// pause when inactive, play when active
LucidAudio.PlayBGM(clip)
    .SetLink(gameObject, AudioLinkBehaviour.PauseOnDisableUnPauseOnEnable);

Available options are:

StopOnDestroy
StopOnDisable
PlayOnEnable
RestartOnEnable
PauseOnDisable
PauseOnDisableUnPauseOnEnable
PauseOnDisableRestartOnEnable

Coroutines & async/await

You can also use coroutines or async/await to wait for audio to finish. To use AudioPlayer in coroutine, call WaitForCompletion.

IEnumerator Coroutine()
{
    // wait until playback ends
    yield return LucidAudio.PlaySE(clip).WaitForCompletion();
}

It is also possible to convert to Task by using WaitForCompletionAsync.

async void MethodAsync()
{
    // Convert to Task, wait until playback ends
    await LucidAudio.PlaySE(clip).WaitForCompletionAsync();
}

UniTask

LucidAudio supports UniTask. ToUniTask becomes available by introducing UniTask to the project from Package Manager.

async UniTask MethodAsync(CancellationToken token = default)
{
    try
    {
        // Convert to UniTask, wait until playback ends
        await LucidAudio.PlaySE(clip).ToUniTask(cancellationToken: token);
    }
    catch (OperationCanceledException ex)
    {
        Debug.Log("Canceled");
    }
}

Also, you can set the behavior when canceling by specifying AudioCancelBehaviour as an argument. (Stop is set by default)

async UniTask MethodAsync(CancellationToken token = default)
{
    try
    {
        // Pause AudioPlayer on cancel
        await LucidAudio.PlaySE(clip).ToUniTask(AudioCancelBehaviour.Pause, cancellationToken: token);
    }
    catch (OperationCanceledException ex)
    {
        Debug.Log("Canceled");
    }
}

ライセンス

Mit License

qemel/LucidAudio