Using Transition Segments
The play event also supports three other parameters — an AudioPath on which to play this Segment, a transition Segment to play prior to playing this Segment, and a PlayingSegment to play relative to (use the measure, beat, marker, etc., boundaries). We come back to the last one in the next section. But for now, let's take a quick look at transition Segments. Remember that each parameter in a call to a DirectX Audio Scripting function is separated by a comma. We just want to use the default AudioPath, so we can leave the second parameter blank or use the special keyword "nothing" to indicate that it should be ignored and use the default.
Sub StartActionMusic ActionMusic.Play (AtMeasure, nothing, RampUpAction) End Sub
…which is equivalent to:
Sub StartActionMusic ActionMusic.Play (AtMeasure, , RampUpAction) End Sub
Both versions of the routine would do the same thing — at the next measure of the primary Segment, play the RampUpAction Segment that we've authored as a transition Segment; when it finishes, play ActionMusic.
Stopping a Piece of Audio
Now our music is chugging along, but we need to be able to stop it eventually (assuming it was authored to loop for a while, or we just need to get back to authoring for a bit!). The basic stop call is similar to our basic play call:
Sub ExitRoom RoomAmbience.Stop End Sub
Again, by default, the stop occurs on the Segment's default boundary (which was probably immediate). You can use the single parameter of Segment.Stop to specify a more specific boundary or (if you are using Style-based Segments) to tack an end embellishment pattern onto the ending of the Segment. Again, see the DirectMusic Scripting Reference portion of the DirectMusic Producer help file for a complete list of options. As an example, when we exit the room, we want to stop our music at the next beat. We could create the following routine:
Sub ExitRoom RoomAmbience.Stop (AtBeat) End Sub
Global DirectMusic Parameters
Scripting also exposes a number of DirectMusic's global parameters. A script can modify the master tempo at which all content is playing, for instance. Or the script can change the master groove level (handy for dynamic music that uses Style-based playback).
Sub DoubleTime SetMasterTempo (200) End Sub Sub IncreaseIntensityLevel SetMasterGrooveLevel (GetMasterGrooveLevel + 1) End Sub
This second example actually uses two global scripting functions, SetMasterGrooveLevel and GetMasterGrooveLevel. We can find out the current groove level, increment it by one, and then set the groove level to the resulting value.
All of these "global" functions are technically operating on a DirectMusic Performance object, so in the documentation, they can be found under Performance.[Function]. But since most implementations only involve a single Performance object, you don't typically need to use one in your scripting calls. Remember that multiple performances can be created by a programmer if you need to have multiple tempos in use at the same time or multiple primary Segments; each performance is effectively its own instance of the DirectMusic playback engine.
One note with using the global functions is that you probably want to create a function that resets all of the global DirectMusic settings just so that you know you're starting off from a known state. Otherwise, after running the above script routines, we'd be playing at twice the authored tempo and at a higher groove level without having any way to get back to a regular tempo and groove level!
Sub ResetSettings SetMasterTempo (100) SetMasterGrooveLevel (0) End Sub