Understanding SeiON
- The 2 Types of SeiON objects
- The 3 Layers of SeiON
- Seion
- SeionGroup
- SeionInstance
- SoundTransform
- Autodisposable
- SeionSample vs SeionClip
SeiON is a pure Actionscript 3 Sound Engine. Generically, it's an extra layer of "complexity" over the Flash Sound() object that does the following:
- Makes sure one doesn't go over Flash's 32 SoundChannel limit by rationing allocations
- Groups sounds into SeionGroups so you can mass-control sounds by category
- Allows auto disposing sounds which you don't ever have to hold a reference to
EDIT: This is worded rather differently from the README, should it be the same?
All SeiON objects can be generically classed under 2 types of objects: ISeionControl and ISeionInstance.
ISeionControl introduces members such as volume & panning, pause() & resume(). ISeionInstance extends both ISeionControl and IEventDispatcher. It adds in new properties such as repeat, autodispose, manager, isPlaying, length; there are also new methods such as dispose(), play(), stop().
Of note is SeionInstance, which implements ISeionInstance. It acts as an Abstract class by implementing functionality from ISeionInstance that is likely to be similar across the classes that need to implement ISeionInstance.
SeiON control comes in 3 layers, the first of which is the Seion class (no capitalisations). It is the root control of all SeiON's sound objects, and keeper of all 32 allocations. SeionGroups register under it, while SeionInstances register under SeionGroups.
Caution: Seion is a static global object with static and instance methods. Use Seion._this to access its instance methods instead of invoking the constructor.
SeionGroups are created using Seion's static factory method createSeionGroup(). When SeionGroups are created, the user allocates a specific number of allocations to it, which is subsequently deducted from Seion's 32. SeionGroups are free to create as many sound instances (SeionInstances) as they like, as long as they stay within their individual instances.
When a SeionGroup needs to create more sound instances, it finds more allocations using a variety of methods, according to the following sequence:
- Borrowing
- If Seion still has any allocations that aren't distributed to SeionGroups yet, these spare allocations can be borrowed.
- Cannibalisation
- Since Seion does not have any to spare, the SeionGroup will check itself for any autodisposable sounds. An autodisposable sound will be randomly deleted to make space for the new sound instance.
- Force Seion
- If there are no autodisposable sounds to cannibalise, the SeionGroup will ask Seion to force allocate a slot for it.
- Seion will go thru its list of all SeionGroups, and randomly select an autodisposable sound, if any, to delete.
- With a slot freed up, Seion can now donate this slot to the requesting SeionGroup.
If all the above methods failed, then the sound instance will simply no play. As such, it is very important to decide beforehand how many allocations do each SeionGroup need. Whether a sound instance is auto-disposable or not will also make a huge difference whether Seion will run out of allocations to play sounds, as to be mentioned in the following section.
There are 2 main types of SeionInstances: SeionClip and SeionSample. While there might be more variants in the com.SeiON.Extras package, those variants are not as commonly used in sound-playing scenarios and often have a very specific scope of functionality.
SeionClip, SeionSample and subclasses of SeionInstances [now referenced as seion sounds] often have a static constructor in the form of SeionClip.create(...). This is how seion sounds should be instantiated, instead of using the public constructor which throws an ArgumentError. This was done to ensure they hold a reference towards their SeionGroup supervisors, as exposed in the variable ISeionInstance.manager.
This native SoundTransform would then be controlled be another exposed volume/panning control for the individual seion sound. This combination of transforms would next be affected by the SeionGroup's volume/panning, and further on, by Seion's global volume/panning as well.
This makes it ideal for situations where you need to assign volumes to individual sounds, control all volumes of all UI sounds via a UI SeionGroup, and further more control the sound of the whole game using Seion's volume/panning.
SeionInstances can be created as autodiposable, or non-autodisposable sounds. Autodisposable sounds have the following properties:
- During instantiation, you will receive no handle/reference to the sound.
- They self dispose when they finish playing.
- If your SeionGroup is running out of allocations, your SeionGroup will dispose your autodisposable sounds prematurely to make room for more seion sounds.
- If your SeionGroup is still out of allocations, Seion will lent you allocations, but only to autodisposable sounds.
- Thus by the previous point, allocating an autodisposable sound is more likely to succeed, but more vulnerable to being disposed.
Of course, that means non-autodisposable sounds simply behave the other way:
- Non-autodisposable sounds will never get auto disposed.
- However, if you forget to dispose it, it will hog up its allocation forever.
- Thus, non-autodisposable sounds are harder to allocate for, but once allocated, are very secure.
The recommendation is that long-running, important sounds are made non-autodisposable, while fickle sounds like UI effects and Game SFX effects are autodisposable.
These two types of seion objects are detailed more in the article "Gapless MP3 Looping", but here's a brief overview for now.
SeionClips:
- Have Offset/Truncate parameters
- Are less taxing on the Flash Player
SeionSample:
- Enable gapless MP3 looping