There are several ways to loop audio content in Atom Craft. At the Material level, you can either keep the looping information from the original wave file or set the Material’s properties to loop. This is useful when the Material is always expected to be played as a loop or if it is the only Material referenced by a Cue.

For multi-track Cues that may trigger other events while a Material is looped, it is recommended to insert a Sequence Loop Marker in the Cue instead. This makes it easier to create repeating patterns within a Cue.

If your loop is tied to the duration of a Waveform Region, the start and end points of the Loop Marker must be set manually, which can be cumbersome and error-prone on larger projects. However, the Robot API can be used to automatically set up the marker around the selected Waveform Region.
 

User Variable

Another advantage of using Sequence Loop Markers is that the number of loops can be set in case the Cue should not repeat itself indefinitely. We can prompt the user to enter the number and assign it to a Robot API’s user variable, which can then be accessed directly from the Atom Craft’s script editor.

From the code side, after importing all the required modules, the user variable can be set as follows:

import sys
import os
import cri.atomcraft.debug as acdebug
import cri.atomcraft.project as acproject

# --BeginUserVariable
"""
LOOP_COUNT:
	type:number
	comment:Number of Loops (0 for infinite)
"""
LOOP_COUNT = 0
# --EndUserVariable

For more information about User Variables check our previous tutorial where we explain how to use them in detail.

The LOOP_COUNT user variable should now appear inside the right panel of the script editor. The Loop Count property of the Sequence Loop Marker accepts a number starting from 1; if the user enters 0, we will set the property to infinite.

Scripting

Since we want to create the Loop Marker based on a Waveform Region, we need to retrieve information about the selected Waveform, determine the Material it references, and find out the Cue it is associated with.

• We use get_selected_objects to retrieve the ID of the selected Waveform Region.
• Then, the get_parent function is called to get the Cue to which the Waveform Region belongs.
• To get the Material, we simply use the get_value function on the LinkMaterial property of the Waveform Region.

# Get selected Waveform Regions
selected_waveforms = acproject.get_selected_objects("WaveformRegion")["data"]
if not selected_waveforms:
	acdebug.warning("Please select a Waveform Region")
	sys.exit()

# Get the Cue in which the Waveform Region is located
cue = acproject.get_parent(selected_waveforms[0], "Cue")["data"]

# Get the Material referenced by the Waveform Region
material = acproject.get_value(selected_waveforms[0], "LinkMaterial")["data"]

To retrieve the start and end times of the selected Waveform Region:

• We call get_value on the DelayTimeMS property to know where the Waveform is starting in the Cue.
• For the end time, we need to look at the Material associated with the Waveform. Based on the sample rate and the number of samples used by the Material, we can easily calculate the duration in milliseconds. This value is then added to the start time of the waveform to get the precise time at which it ends in the Cue.

# Get the start time of the Waveform Region in the Sequence
waveform_start = acproject.get_value(selected_waveforms[0], "DelayTimeMS")["data"]

# Get the length of the Waveform Region by calculating the duration of the Material
material_sample_rate = acproject.get_value(material, "SamplingRate")["data"]
material_samples = acproject.get_value(material, "SampleFrames")["data"]
material_duration = (1000 * float(material_samples)) / float(material_sample_rate)

# Calculate the end time in ms of the Waveform Region in the Sequence
waveform_end = (float(waveform_start) + material_duration)

We now have all the required information to create the Sequence Loop Marker:

• Create the Loop Marker at the Cue level by using the create_object function.
• Test if the InfinityLoopFlag property must be set to True (when the LOOP_COUNT User Variable is lesser than 1). Otherwise, use the number stored in LOOP_COUNT to set the value of the LoopCount property.
• Finally use the waveform_end and waveform_start variables to set the MarkerEndTime and MarkerStartTime properties, respectively.

# Create the Sequence Loop Marker
marker = acproject.create_object(cue, "LoopMarker", "My Loop")["data"]

# Set the number of loops, loop start, and loop end
if LOOP_COUNT < 1:
	acproject.set_value(marker, "InfinityLoopFlag", "True")
else:
	acproject.set_value(marker, "LoopCount", LOOP_COUNT)
acproject.set_value(marker, "MarkerEndTime", waveform_end)
acproject.set_value(marker, "MarkerStartTime", waveform_start)

This is all we need! You can download the full script below and test it. Simply select a Waveform Region in a Cue, and run the script. A Sequence Loop Marker matching the length of the Waveform will be automatically created.

Script_RobotAPI_CreateLoopMarker