How Does repeatCount Repeat Elements in SMIL?

The repeatCount attribute in Synchronized Multimedia Integration Language (SMIL) defines the number of times a media element or temporal container plays its simple duration. By accepting numeric values, fractional counts, or the keyword indefinite, repeatCount allows authors to precisely control playback loops across standalone media files, animation elements, and complex timing containers such as <seq> and <par>.

Understanding the repeatCount Syntax and Values

The repeatCount attribute specifies the iteration count for the active duration of an element. It accepts two primary types of values:

• Numeric Values (N or N.n): A positive decimal value representing how many times the element cycles through its simple duration (dur). An integer value like 3 loops the playback three complete times. A fractional value like 2.5 plays two complete iterations followed by the first half of the element's duration before stopping.
• The indefinite Keyword: Sets the element to repeat continuously without a predetermined stop time. The element will loop until an external event, an explicit end condition, or a parent container forces it to terminate.

Repeating Individual Media and Animation Elements

When applied to basic media elements (such as <video>, <audio>, or <img>) or SVG animation elements (such as <animate> or <animateTransform>), repeatCount determines how many times the media payload or animation track runs from start to finish.

<!-- Plays a 4-second audio clip 3 full times (Total active duration: 12 seconds) -->
<audio src="chime.mp3" dur="4s" repeatCount="3" />

<!-- Loops an SVG rotation animation continuously -->
<animateTransform attributeName="transform"
                  type="rotate"
                  from="0 50 50"
                  to="360 50 50"
                  dur="2s"
                  repeatCount="indefinite" />

For media elements with a natural intrinsic duration, defining repeatCount without an explicit dur will repeat the intrinsic timeline of the media file. If dur is explicitly defined, each iteration uses the defined dur rather than the media file's natural length.

Repeating Container Elements: <seq>, <par>, and <excl>

SMIL timing containers manage groups of elements, and applying repeatCount to a container repeats the entire group structure as a single cohesive unit:

• Sequential Containers (<seq>): Each iteration plays all child elements in order from first to last. Once the final child finishes, the entire sequence restarts at the first child until the repeatCount threshold is satisfied.
• Parallel Containers (<par>): All child elements start simultaneously. Once the container reaches the end of its active duration—determined by container rules or child durations—the entire parallel group restarts in unison.

<!-- Repeats the sequence of two slides twice (Total active duration: 20 seconds) -->
<seq repeatCount="2">
  <img src="slide1.jpg" dur="5s" />
  <img src="slide2.jpg" dur="5s" />
</seq>

At the start of each iteration, all child elements reset to their initial state, restarting any nested timelines or visual transformations.

Calculating Active Duration with repeatCount

The total active duration of an element with repeatCount is calculated using the formula:

\[\text{Active Duration} = \text{dur} \times \text{repeatCount}\]

If a 5-second video uses repeatCount="1.5", the element plays for a total of 7.5 seconds, cutting off midway through the second playback loop.

Interactions with Other SMIL Timing Attributes

SMIL provides additional timing controls that can modify or constrain how repeatCount behaves:

• repeatDur vs. repeatCount: While repeatCount specifies the iteration count, repeatDur specifies the total duration of the repeated playback (e.g., repeatDur="30s"). If both are specified on the same element, the loop terminates whichever limit is reached first.
• min and max Constraints: Setting a max attribute places a strict ceiling on the element's total active duration. If dur="5s" and repeatCount="10" would produce a 50-second runtime, but max="20s" is present, playback halts after 20 seconds (4 iterations).
• fill Attribute: When repeatCount finishes, the fill attribute determines the final presentation state. Using fill="freeze" holds the element at its final rendered frame of the last iteration, while fill="remove" removes the element from the display immediately upon completion.