$(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 minutes and seconds (MM:SS), even when both hours and minutes are zero
showHours	Always display hours, minutes and seconds (HH:MM:SS), even when the duration is under an hour

tip

Use showHours for an on-screen clock or countdown. The width stays the same when the time crosses the one-hour mark.

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:00
90	$(formatDuration 90 showHours)	00: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