# Audio Sync Containers

This is an example project for Visionaire Studio 5 that demonstrates how to use Visionaire’s Audio Containers to play seamless music variations based on in-game events.

The project includes two examples showing how different musical layers or versions can transition smoothly during gameplay, similar in spirit to LucasArts’ famous iMUSE system used in their classic adventure games.

## How to use the file

The project doesn't contain a game you can run, but it contains the required audio containers which you can test.

Proceed as follows:

1. Open the file `audio_sync_containers.ved` in Visionaire Studio 5.
2. Go to the "Audio" section

You'll find two Sync containers, named sync_switch_container and sync_transitions_and_markers. These two demonstrate two different approaches, which we'll look at in detail. 

### sync_switch_container

This is a Sync Container that contains a Switch Container that contains the 4 audio parts. These audio parts are child Sounds (`test_1_drums`, `test_2_drums-bass`, `test_3_drums-bass-rhodes`, `test_4_full`) of the Switch Container. The timeline contains the Switch container, as well as a Tempo marker that defines tempo and beat measure. Notice the Switch Container also has a Value named `sync_switch_track_index`.

This is the same approach as in the "bgm_sync_new" example you mentioned.

#### Using sync_switch_container

- Select container `sync_switch_container`
- Click the large Play button at the right of the Switch Container's settings
- No music will be heard. Again, that's intended behavior.

- Under the Play button, `sync_switch_track_index` has appeared along with a value input. Change it to `1`.
- You'll hear the drums fade in.
- Try the other values `2`, `3`, and `4`. On value change, you'll hear how the respective audio part fades in.
- Set `sync_switch_track_index` back to `0`, and the music cuts out.

#### How does it work

`sync_switch_track_index` simply controls which of the audio parts is played by the Switch Container. The set crossfade time makes for a soft fade between the audio parts on value change. The parent Sync Container makes sure everything stays synchronized.

Imagine the audio parts are all continuously running in sync, and you're using the Switch Container to crossfade between them, like a DJ.

### sync_transitions_and_markers

This is a Sync Container with a timeline containing the 4 audio parts. The timeline also contains a number of Transitions, TransitionAreas, and Markers, which we'll explore in a second. Notice the Sync Container also has a Value named `sync_marker_index`.

#### Using sync_transitions_and_markers

- Select container `sync_transitions_and_markers`
- Click the large Play button in the section right beneath the timeline
- You'll see the play head move, but hear nothing. That's intended behavior.

- Under the Play button, `sync_marker_index` has appeared along with a value input. Change it to `1`.
- You'll hear drums. And you'll see that the play head now loops between bars 9 and 17.
- Change `sync_marker_index` to `2`.
- At first, nothing will change. But once the drums have completed their current loop, the play head then loops between bars 17 and 25. And hey, there's a bass now, accompanying the drums.
- Change `sync_marker_index` to `3`.
- Again, it takes until the current loop is completed to switch to the next loop. Now, there's a Rhodes playing along, too. The play head is now looping bars 25 to 33.
- Change `sync_marker_index` to `4`.
- And there we have the guitar, too. Play head loops bars 33 to 41.
- Change `sync_marker_index` to any value between `1` and `4`.
- Observe how the current loop is nicely finished, and the play head then jumps to the appropriate part.
- Change `sync_marker_index` to `0`.
- Instant silence. Play head loops bars `1` to `9`.

#### How does it work?

The markers `p0`, `p1`, `p2`, `p3`, and `p4` act as jump marks or anchors. The Transitions and TransitionAreas address these markers and make the play head jump there.

In the `p0` section, there are 4 TransitionAreas. Each of them checks for the value of `sync_marker_index` and then sets the play head to the respective marker when the __next beat__ is reached. Thus, if `sync_marker_index` is set to any value between 1 and 4, the respective part of the song is started.

The sections `p1`, `p2`, `p3`, and `p4` each have 4 short TransitionAreas at their end. These TransitionAreas slightly extend into the next section (just to make sure they're not missed). Again, each of these TransitionAreas checks for the value of `sync_marker_index` and then sets the play head to the respective marker when the __next measure__ starts. Thus, the desired section is played when needed without breaking the song's timing.

At the end of section `p4`, there are 4 Transitions. Each of them checks, you guessed it, for `sync_marker_index` and sets the play head to the respective marker. This time, we don't need fancy TransitionAreas, because the transition must happen immediately at the end of section 4.

At the bottom, there's one looooong TransitionArea. It checks `sync_marker_index` for the value `0` and __instantly__ sets the play head to marker `p0`. That way, setting `sync_marker_index` to `0` will instantly end the music, without waiting for the next beat, measure, or loop end.

#### What else to say?

There's also a Tempo marker. Make sure you set it to the correct beat measure and tempo!

You'll notice that the loooong TransitionArea at the bottom starts slightly early (before bar 9). That's because otherwise we'd hear a short pop of music before the play head is reset to `p0` if `sync_marker_index` is `0`.

## How to integrate it in the game

Simply link the Sync Container in a scene's properties. then use `Set Value` action parts to set the the index value (`sync_switch_track_index` or `sync_marker_index` ) accordingly, effectively "queuing" the next audio part to play.

## Summary

Both methods shown are quite different in what they can do, and how much work it is to set them up.

### The sync_switch_container approach

This method is very simple to set up. No Markers, no Transitions or TransitionAreas.

You get soft transitions between the audio parts. However, all audio parts must be the exact same length. Also, during the crossfade, you might hear a short phasing effect while both audio parts are audible.

This solution might be appropriate e.g. if you have subtle ambient tracks, or a simple song structure without distinctive parts, and if you only want to swap different "versions" of the song.

### The sync_transitions_and_markers approach

This solution requires a substantial amount of Markers, Transitions, and TransitionAreas to work.

This method allows for complex timed transitions at defined points in the song. This is the most powerful solution, as you have precise control over when exactly a transition happens. Additionally, it works with audio parts of different lengths.

This solution might be appropriate e.g. if you have a more complex song structure which you don't want to break. For example, if your song features a guitar solo, you would use this solution to avoid cutting to the guitar solo part while the solo is already being played.

## Copyright & license

### The music

The included musical samples have been played by me and therefore are my intellectual property. You must not use them in any of your projects, and you must not sell them or use them in any other way than their original purpose: As illustrative example music in this Visionaire Studio project.

### The project file

MIT License

Copyright (c) 2026 Frank Willeke (https://www.frankwilleke.de)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.