Understanding Video Timestamps: Formats, Trends, and Best Practices

TL;DR

HH:MM:SS and MM:SS: Still widely used, great for humans.
HH:MM:SS.mmm and SS.mmm: Modern standard, precise, trendy.
NNNms and NNNus: Useful for programmatic and high-precision cases.
Avoid frames-based timestamps or ambiguous formats.
APIs should support multiple formats for flexibility and developer convenience.

When working with video APIs, timestamps are everything. They define where your video starts, stops, or jumps to, and they ensure smooth playback, precise editing, and accurate analytics. Over the years, different styles of timestamps have emerged. Some are classic, others are trending, and a few are slowly becoming outdated. Let’s break down what’s supported today and what you should use in 2025.

Common Timestamp Formats

Here’s a quick overview of the timestamp formats that modern video APIs—like ours—support:

Format	Example	Notes
HH:MM:SS	01:20:10	Classic format. Ideal for longer videos. Still widely used.
MM:SS	04:03	Simpler, good for short videos or clips. Still relevant.
HH:MM:SS.mmm	07:02:05.100	Adds millisecond precision. Increasingly preferred for detailed editing.
SS	120	Seconds-only format. Quick and readable for scripts or automation.
SS.mmm	120.2	Seconds with milliseconds. Perfect for high-precision playback control.
NNNms	1200ms	Explicit millisecond format. Often used in low-level APIs or programmatic control.
NNNus	1300us	Microsecond precision. Rare, mostly for testing or specialized processing.

Outdated Formats

Some timestamp notations are falling out of favor, mostly because they lack precision or clarity:

Frames-based timestamps (e.g., 1234f for frame number) are less common now. Modern APIs focus on time-based formats, as frame rates can vary.
Colon-separated decimals like 01:20:10.2 are still supported, but the move toward HH:MM:SS.mmm provides more explicit millisecond control.

In general, anything that mixes units or relies on implicit frame rates is considered legacy and should be avoided in new projects.

Current Trends

Millisecond Precision as Default:
HH:MM:SS.mmm and SS.mmm are now the go-to formats for APIs that require accurate trimming, seeking, or analytics.
Programmatic Simplicity:
Plain seconds (SS or SS.mmm) are popular in code and automation because they remove parsing headaches and are language-agnostic.
Microsecond Usage for Specialized APIs:
Microseconds (NNNus) are emerging in high-performance video processing and analytics tools but are not necessary for standard playback or editing.
Consistency Across APIs:
Developers increasingly expect all video endpoints to support multiple formats, so flexibility is key. Your APIs should allow developers to pick the format that suits their workflow without forcing conversion.

Best Practices

Default to HH:MM:SS.mmm for editing or detailed playback control.
Use plain seconds for scripting or automated workflows—easier to calculate, easier to parse.
Avoid frames unless absolutely necessary—they tie your logic to a specific framerate.
Document supported formats clearly in your API reference; developers should never have to guess.
Be explicit with units (ms or us) if you need precision. Ambiguity is the fastest route to bugs.

Quick Conversion Tips

Sometimes you’ll need to convert between formats:

HH:MM:SS → seconds → (hours * 3600) + (minutes * 60) + seconds
SS → HH:MM:SS → hours = floor(seconds / 3600), then minutes and leftover seconds.
Milliseconds (NNNms) → seconds → divide by 1000.

These conversions are simple but essential for automation scripts, analytics, and playback logic.

Video timestamps may seem like a small detail, but they’re the backbone of reliable playback, editing, and analytics. Using the right format can save headaches, reduce bugs, and make your API a pleasure to use.