Sound Instance

API Reference

Description

Sound Instance is a single playing audio source. Most sound instances are managed by the Sound Manager and should not be used directly.

However, this class is useful for custom mixing logic and manual playback. There are four main use cases:

1. Playing looped sounds
2. Changing sounds at runtime
3. Changing volume and pitch at runtime
4. Attaching to another game object

Playing looped sounds

Use the Stem.SoundInstance.Looped flag to play looped sound.

using UnityEngine;

public class TVNoise : MonoBehaviour
{
	[Stem.SoundID]
	public Stem.ID soundID = Stem.ID.None;

	private Stem.SoundInstance soundInstance = null;

	private void OnEnable()
	{
		if (soundInstance != null)
			return;

		// Will do a lookup for sound with the mathcing ID in all sound banks
		// and return a reference to a sound instance from the sound pool.
		soundInstance = Stem.SoundManager.GrabSound(soundID);

		if (soundInstance != null)
		{
			// Play looped
			soundInstance.Looped = true;
			soundInstance.Play();
		}
	}

	private void OnDisable()
	{
		// Return the instance to the sound pool
		Stem.SoundManager.ReleaseSound(soundInstance);
		soundInstance = null;
	}
}

Changing sounds at runtime

Use the Stem.SoundInstance.Sound property to play different sounds.

using UnityEngine;

public class Draggable : MonoBehaviour
{
	[Stem.SoundID]
	public Stem.ID dragStartSoundID = Stem.ID.None;

	[Stem.SoundID]
	public Stem.ID dragEndSoundID = Stem.ID.None;

	[Stem.SoundID]
	public Stem.ID dragLoopSoundID = Stem.ID.None;

	private Stem.SoundInstance soundInstance = null;
	private Stem.Sound dragStart = null;
	private Stem.Sound dragEnd = null;
	private Stem.Sound dragLoop = null;
	private bool dragging = false;

	private void Awake()
	{
		// Grab an empty sound instance from the sound pool.
		soundInstance = Stem.SoundManager.GrabSound();

		dragStart = Stem.SoundManager.GetSound(dragStartSoundID);
		dragEnd = Stem.SoundManager.GetSound(dragEndSoundID);
		dragLoop = Stem.SoundManager.GetSound(dragLoopSoundID);
	}

	private void OnDestroy()
	{
		// Return the instance to the sound pool
		Stem.SoundManager.ReleaseSound(soundInstance);
		soundInstance = null;
	}

	private void Update()
	{
		if (dragging && soundInstance.Sound == dragStart && !soundInstance.Playing)
		{
			// Play looped
			soundInstance.Sound = dragLoop;
			soundInstance.Looped = true;
			soundInstance.Play();
		}
	}

	public void StartDrag()
	{
		// Play one-shot
		soundInstance.Sound = dragStart;
		soundInstance.Looped = false;
		soundInstance.Play();

		dragging = true;
	}

	public void EndDrag()
	{
		// Play one-shot
		soundInstance.Sound = dragEnd;
		soundInstance.Looped = false;
		soundInstance.Play();

		dragging = false;
	}
}

Changing volume and pitch at runtime

Use Stem.SoundInstance.Volume and Stem.SoundInstance.Pitch properties to change parameters during playback.

using UnityEngine;

public class Siren : MonoBehaviour
{
	[Stem.SoundID]
	public Stem.ID sirenSoundID = Stem.ID.None;

	public float frequency = 440.0f;

	public float baseVolume = 0.8f;
	public float additionalVolume = 0.2f;

	public float basePitch = 1.0f;
	public float additionalPitch = 0.2f;

	private Stem.SoundInstance soundInstance = null;

	private void Awake()
	{
		// Will do a lookup for sound with the matching ID in all sound banks
		// and return a reference to a sound instance from the sound pool.
		soundInstance = Stem.SoundManager.GrabSound(sirenSoundID);

		if (soundInstance != null)
		{
			// Play looped
			soundInstance.Looped = true;
			soundInstance.Play();
		}
	}

	private void OnDestroy()
	{
		// Return the instance to the sound pool
		Stem.SoundManager.ReleaseSound(soundInstance);
		soundInstance = null;
	}

	private void Update()
	{
		// Calculate current sine wave sample
		float timeNow = Time.realtimeSinceStartup;
		float sample = Mathf.Sin(timeNow * frequency);

		// Modulate pitch and volume
		soundInstance.Volume = baseVolume + additionalVolume * sample;
		soundInstance.Pitch = basePitch + additionalPitch * sample;
	}
}

Attaching to another game object

Use the Stem.SoundInstance.Target property to attach sound instance to another game object.

using UnityEngine;

public class Rocket : MonoBehaviour
{
	[Stem.SoundID]
	public Stem.ID engineSoundID = Stem.ID.None;

	private Stem.SoundInstance soundInstance = null;

	private void Awake()
	{
		// Will do a lookup for sound with the matching ID in all sound banks
		// and return a reference to a sound instance from the sound pool.
		soundInstance = Stem.SoundManager.GrabSound(engineSoundID);

		if (soundInstance != null)
		{
			// Play looped
			soundInstance.Looped = true;
			soundInstance.Play();

			// Attach to the game object
			soundInstance.Target = transform;
		}
	}

	private void OnDestroy()
	{
		// Return the instance to the sound pool
		Stem.SoundManager.ReleaseSound(soundInstance);
		soundInstance = null;
	}
}