Triggering Audio With Code!

After you have some Sound Groups and Playlists set up, let's see how to trigger them from code. You can usually trigger them without coding however.

 
Note: This is only a partial listing of the most commonly used code methods. For a full reference, refer to the Master Audio API website. Instructions for code are C# only. For UnityScript usage, please consult Unity forums.
 

There are several sections of code functionality (and basics), listed below. Click on the links below to read more about each.

 

Your Class Files

There are a couple basics you should know about when writing a class file that will use the Master Audio API.
     
  1. Namespace: When using the API, at the top of the code file, add the following:
     
    using DarkTonic.MasterAudio;
    2.  
  2. Property Drawers: For your own code classes you may write, you can use these Property Drawers.
       
    • SoundGroupAttribute: use this to decorate public strings that are Sound Groups in your Inspectors like this:
       
      [SoundGroupAttribute] public string laserSound;
       
      This will show the familiar Sound Group dropdowns used on all the Master Audio Inspectors in your script's Inspector!
      •  
       
    • MasterCustomEventAttribute: use this to decorate public strings that are Custom Events in your Inspectors like this:
       
      [MasterCustomEventAttribute] public string laserCustomEvent;
       
      This will show a dropdown of Custom Events in your Inspector!
      •  
       
    • PlaylistAttribute: use this to decorate public strings that are Playlists in your Inspectors like this:
       
      [PlaylistAttribute] public string playlist;
       
      This will show a dropdown of Playlists in your Inspector!
 

Playing Sounds

The following API commands are available for playing sounds:
     
  1. If you need to trigger any Sound Groups during times other than those provided by the included scripts, you can use the following line of code:
     
    MasterAudio.PlaySound(string soundGroupName, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
     
    This plays the sound from the position of the Master Audio game object (usually only used for 2D audio for this reason). All parameters after the 1st are optional.
    • volumePercentage: This lets you play a lower volume version (0-1 is the range, 1 is default).
    • pitch: If specified, let you override the chosen Variation's pitch and random pitch and use the pitch parameter instead (default is 1).
    • variationname: If specified, lets you play a specific Variation (or its clones created from Voices > 1) by name.
    • delaySoundTime: Lets you schedule a sound to be played X seconds from now.
    2.  
  2. Other variants of the PlaySound method for playing at specific positions and optional following. See Intelli-sense, code comments or API website for explanation of each parameter. These are the same as PlaySound, but you are additionally passing in a Transform object or Vector3 so that the sound will trigger from its position. If you use the FollowTransform methods, the chosen Sound Group's Variation will follow the caller until it is done playing.
       
    1. MasterAudio.PlaySoundAndForget(string sType, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Same as PlaySound, but does not return a PlaySoundResult object so it has 0 bytes of GC Allocation.
      2.  
    2. MasterAudio.PlaySound3DAtVector3(string sType, Vector3 sourcePosition, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Plays a sound at a specific Vector3 you pass in. Using the AtVector3 methods is useful for 2D games where the Z of the object making the sound might not want to be used. You can alter is and use this.
      3.  
    3. MasterAudio.PlaySound3DAtVector3AndForget(string sType, Vector3 sourcePosition, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Same as PlaySound3DAtVector3 but does not return a PlaySoundResult object.
      4.  
    4. MasterAudio.PlaySound3DAtTransform(string sType, Transform sourceTrans, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Plays a sound at the position of a Transform you pass in.
      5.  
    5. MasterAudio.PlaySound3DAtTransformAndForget(string sType, Transform sourceTrans, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Same as PlaySound3DAtTransform but does not return a PlaySoundResult object.
      6.  
    6. MasterAudio.PlaySound3DFollowTransform(string sType, Transform sourceTrans, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Same as PlaySound3DAtTransform but the Transform position is followed as long as the sound is playing.
      7.  
    7. MasterAudio.PlaySound3DFollowTransformAndForget(string sType, Transform sourceTrans, float volumePercentage, float? pitch, float delaySoundTime, string variationName);
       
      Same as PlaySound3DFollowTransform but does not return a PlaySoundResult object.
 

The PlaySoundResult object

Note: The AndForget methods above do not return a PlaySoundResult, and the rest do. It's used to subscribe to events and manipulate the sound after it has been started playing. If you don't need it, it is better for performance to not generate it (0 bytes GC Allocation without it). A PlaySoundResult object has the following properties:
     
  1. SoundPlayed (boolean): True unless the sound was scheduled (below) or failed to play because all Variations were busy, Bus voice limit reached, etc.
    2.  
  2. SoundScheduled (boolean): False unless you scheduled a sound with the delaySoundTime field.
    3.  
  3. ActingVariation (SoundGroupVariation): This will give you access to the actual Variation used, if a sound was played. You can use ActingVariation.audio to access the properties of the Audio Source for the Variation used. You should *never* set volume this way though, as it will not take into account all the other Master Audio calculations for volume (Sound Group / Bus / Variation / Master Mixer Volume). If you do, it will appear that Master Audio is not working correctly. Instead, use ActingVariation.AdjustVolume for this so the calculations will be correct.
 
The PlaySoundResult object can be used to do some useful things:
     
  1. Get notified of when a sound is finished playing so you can do something, like this (always check if it's null first!):
     
     
    Note: You do not need to worry about unsubscribing from the event because all subscribers are cleared out every time the Variation is played.
    2.  
  2. The PlaySoundResult can also be used to fade a clip out early, like this:
     
     
    If you do not specify the fadeTime parameter, it will use the Variation's Custom Fade Out Time value from the Inspector.
 

Chaining Sounds Together

You can also write a Coroutine to "chain" several sounds together, like this:
 
 
 

Controlling Sound Effects

There are dozens of control methods for Sound Groups. Here's a few:
     
  1. MasterAudio.StopAllOfSound(string soundGroupName);
     
    This will stop all Variations of the of the selected Sound Group instantly.
    2.  
  2. MasterAudio.FadeOutAllOfSound(string soundGroupName, float fadeTime);
     
    This will fade out all Variations of the specified Sound Group over X seconds.
    3.  
  3. MasterAudio.MasterVolumeLevel
     
    This property can be read or set. The value is between 0 and 1. This controls Master Mixer Volume.
    4.  
  4. MasterAudio.GetGroupVolume(string soundType);
     
    Returns a float representing the volume of the chosen Sound Group.
    5.  
  5. MasterAudio.SetGroupVolume(string soundType, float volume);
     
    Sets the volume of the chosen Sound Group.
    6.  
  6. MasterAudio.MuteGroup(string soundType);
     
    This mutes the chosen Sound Group.
    7.  
  7. MasterAudio.UnmuteGroup(string soundType);
     
    This unmutes the chosen Sound Group.
    8.  
  8. MasterAudio.SoloGroup(string soundType);
     
    This solos (and unmutes) the chosen Sound Group.
    9.  
  9. MasterAudio.UnsoloGroup(string soundType);
     
    This unsolos the chosen Sound Group.
    10.  
  10. MasterAudio.GrabGroup(string soundType);
     
    Use this to grab the Sound Group if you want to read or manipulate other properties of the Sound Group such as Retrigger Percentage settings.
    11.  
  11. MasterAudio.SetBusVolumeByName(float volume, string busName);
     
    This changes the volume of a Bus.
    12.  
  12. MasterAudio.GrabBusByName(string busName);
     
    Use this to grab the Bus object to read or change its properties.
 
Note: There are also methods to pause or fade to a specified volume (over X seconds) a Bus, Sound Group or a Variation. Playmaker Custom Actions exist for these as well.
 

Controlling Playlists

There are many control methods for Playlist Controllers. Here's a few:
     
  1. MasterAudio.TriggerPlaylistClip(string clipName);
     
    This will play a song by name (or Alias) from the current Playlist in your Playlist Controller.
    2.  
  2. MasterAudio.ChangePlaylistByName(string playlistName, bool playFirstClip);
     
    This will change the Playlist in your PlaylistController to one with the name you specify. Optionally can start playing the first song in the Playlist as well.
    3.  
  3. MasterAudio.StartPlaylist(string playlistName);
     
    This will start the Playlist playing whether it's currently loaded in the Playlist Controller or not.
    4.  
  4. MasterAudio.StopPlaylist();
     
    Stops playing the current song. The song will not fade out, but stop instantly. If you want a fade out, there is a FadeToVolume command on the PlaylistController class.
    5.  
  5. MasterAudio.QueuePlaylistClip(string clipName);
     
    This will play the specified song (by name or Alias) after the current song. Requires Auto Advance to be on and it will turn looping off for the current song.
    6.  
  6. MasterAudio.GrabPlaylist(string playlistName);
     
    This will grab a Playlist object by name. This scans the Master Audio game object for Playlists.
 
Note: The above methods (except GrabPlaylist) work if you only have a single Playlist Controller in the Scene. If you have more than one, there are overloaded methods of each method that take the Playlist Controller name as a parameter as well. Some have an "all Playlist Controllers" method as well, so you can "pause all music" etc.
 

Playlist Controller Events

You can subscribe to the events in the Playlist Controller through code. These are a some of the supported events:
     
  1. SongChanged: This event in the Playlist Controller class can notify you when the song changes (when crossfading starts if using crossfading). Sample code looks like this:
     
     
    Note: The first line grabs a Playlist Controller by game object name.
    2.  
  2. SongEnded: This event can be hooked up to with the same type of code and notifies you when a song stops playing (different that SongChanged when using crossfading).
There are many Playlist Commands as well. Check the API website!
 
  • PlaylistFade: You can execute a method when a gradual fade you asked for is completed as well. That code looks like this: