Getting Started

Ensō was written with ease-of-use in mind. That philosophy extends to its setup, as well.

Installation

Before you can do anything, obviously, you must first download Ensō and import it into your project. You can do so from either the Unity Asset Store or on GitHub. Whichever method you choose is up to you, but you should be mindful of the pros and cons of each.

If you're more familiar with Unity's interface and prefer to manage your assets from within the editor itself, then the Unity Asset Store is recommended. If you prefer having faster access to updates, then GitHub is recommended. If you must, you can download it and then drag it into your project like any other set of assets.

Be advised that you'll only be able to use the Asset Store version if you have the latest version of Unity. That means you must either upgrade to the latest version before downloading the Asset Store version or simply use the GitHub version.

Setup

When Ensō is installed into your project, you need to put it into your scene. Select the object in your scene you want the music to come from (like, say, your main camera) and then go to Component > Audio > Ensō Music Player. When you do this, the Music Player component will be added to your object. It functions like any other Unity component, so you can reference it in your other scripts.

Looking at the component in the Inspector, you'll see a few options. Under Track Settings, you'll see a variable called Tracks. Click on the arrow at the side to expand it. Set the Size variable to the number of songs you want to have in your scene, and then track objects will be added to the list. Each one has the following fields:

• Name: The name of the track. Give each one of these a unique name, or else unexpected behavior might result.
• Track: The sound file for the track. You can use any Unity-supported file type.
• Loop Points: This contains four sub-settings:
  • Sample Loop Start and Sample Loop Length: If the track you selected has LOOPSTART and LOOPLENGTH metadata tags, as you may be familiar with if you've used the RPG Maker series of game engines, Ensō will read those automatically if these values are kept at 0. If you want to specify the starting time when the song starts to loop and how long the loop will last, respectively, you can set these to whatever you need. Note that these are in samples, not seconds.
  • Relative File Path: The path to the audio clip in your project, as well as its filename, plus extension. This is needed to read the metadata from the file at runtime. If you don't wish to use LOOPSTART and LOOPLENGTH metadata and don't need to compensate for frequency, then you can leave this blank. However, if you want to do it for an audio clip named, say, test.ogg located in the Music folder, you'd type Music/test.ogg in this field.
  • Compensate for Frequency: Check this if you're using a nonstandard audio frequency different from, say, 32 kHz or the like. Unity likes to adjust audio clips' frequencies if they're off, which can invalidate the loop points you've set. Checking this will automatically adjust the loop points for you based on the frequency changes. If you still want to set the points yourself without this calculation, then uncheck this box.

Set each object up with a unique name, a track, and loop points (if necessary; leave them at 0 if they have the aforementioned meta tags and you want to use those). Now you're ready to use Ensō in your scene!

Basic Use

When Ensō is all set up, you're ready to use it. It won't start playing your music automatically, though; you need to tell it what to play. If you want to, say, automatically play the first song in your queue, you can write a simple script to do just that (the following assumes the component is attached to the same object that Ensō is attached to):

using UnityEngine;
using EnsoMusicPlayer;

public class PlayFirst : MonoBehaviour
{
    MusicPlayer musicPlayer;

    void Start()
    {
        musicPlayer = GetComponent<MusicPlayer>();

        musicPlayer.Play(musicPlayer.Tracks[0]);
    }
}

The song will then play and then loop back to the original specified loop point after it reaches the end. That's all! Enjoy your nice, seamlessly-looping music!