Ranges reference
Range properties, stage changes, saved and local ranges, and the errors that clients raise.
This page lists the properties of a range, how each stage change sets its times, and what local ranges cannot do.
Properties
keyUUIDThe unique ID of the range. Synnax makes one when you leave it out. Create with an existing key to update that range.
namestringRequiredThe name of the range, at least one character. Names do not have to be unique.
time_rangeTimeRangeRequiredThe interval of the range. It includes the start and excludes the end. The start cannot be after the end, and neither can be zero.
colorstringA hex color such as
"#FF0000". The client returns it as a color object. An empty string clears it. Line plots show only ranges that have a color. The Console cannot set it. An Arc automation can.parentRangeThe parent range. Set it when you create the range.
retrieve_if_name_existsbooleanPython only. Returns an existing range with the same name instead of creating a new one. See create ranges.
Labels and metadata are not properties of the create call. See metadata and labels.
Stages
The Console computes the stage of a range from its times and the current time:
Each stage change in the Console sets a time:
On the timeline, Unschedule clears the start and the end, and Remove end clears the end. When you move the start past the end, the end moves with it and the range keeps its length. The same is true when you move the end before the start.
Saved and local ranges
Save to Core stores a range in the Synnax Core, where every user sees it. Save locally keeps it only in this Console, marked with an L in the ranges toolbar.
A local range keeps only its name and its time range. It cannot:
- Open a range overview, or have child ranges, labels, or metadata.
- Be deleted with Delete. Select Unfavorite to remove it.
- Have channel aliases or snapshots.
- Be shared with a link.
To keep a local range, right-click it in the ranges toolbar and select Save to Core.