$(formatDuration)
$(formatDuration [duration] <format>)
Formats a duration (time in seconds) into a human-readable time string. The output uses colon-separated components (e.g. MM:SS or HH:MM:SS), with each component zero-padded to 2 digits.
By default, only the necessary components are shown — hours are omitted when zero, and minutes are omitted when both hours and minutes are zero.
Format Flags
You can append optional flags after the duration value to control which components are always displayed:
| Flag | Effect |
|---|---|
showMinutes | Always display the minutes component, even when both hours and minutes are zero |
showHours | Always display the minutes and seconds components, even when they would normally be hidden |
note
These flags ensure the minimum displayed components. Hours will still only appear when the duration is 1 hour or more.
Examples
Basic Usage
| Input (seconds) | Expression | Output |
|---|---|---|
| 45 | $(formatDuration 45) | 45 |
| 90 | $(formatDuration 90) | 01:30 |
| 3661 | $(formatDuration 3661) | 01:01:01 |
| 0 | $(formatDuration 0) | (empty) |
With Format Flags
| Input (seconds) | Expression | Output |
|---|---|---|
| 45 | $(formatDuration 45 showMinutes) | 00:45 |
| 0 | $(formatDuration 0 showHours) | 00:00 |
| 90 | $(formatDuration 90 showHours) | 01:30 |
With Special Variables
The most common use case is formatting duration-based special variables:
Stream uptime timer:
$(formatDuration {{stream_uptime}} showHours)
→ 02:34:12
Ad break countdown:
$(formatDuration {{ad_duration_remaining}} showMinutes)
→ 01:30
Time until next ad:
$(formatDuration {{next_ad}} showMinutes)
→ 12:45
Preroll-free time remaining:
$(formatDuration {{preroll_free_time}} showMinutes)
→ 05:00