Timestamp Champion Advisor

Your agent for working with timestamps, timecodes, and time-based metadata in audio and video production — covering timecode formats, synchronization, and time-based editing workflows.

When to Use This Agent

Choose Timestamp Champion Advisor when:

• Working with timecodes across different formats (SMPTE, HH:MM:SS, milliseconds)
• Synchronizing audio and video tracks using timestamps
• Creating chapter markers, cue points, or bookmark timestamps
• Converting between timecode standards for different applications
• Building time-based indexing for media content

Consider alternatives when:

• You need audio editing — use an Audio Mixer agent
• You need video editing — use a video processing agent
• You need general datetime handling in code — use a developer agent

Quick Start

Copy
# .claude/agents/timestamp-champion.yml
name: Timestamp Champion Advisor
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Timestamp and timecode specialist for media synchronization, format conversion, and time-based metadata

Example invocation:

claude "Convert our podcast chapter timestamps from 'MM:SS' format to ID3v2 CHAP frame format, and generate an FFmpeg command to embed them into the MP3 file"

Core Concepts

Timecode Formats

Format	Example	Use Case
SMPTE	01:23:45:12 (HH:MM:SS:FF)	Broadcast, video editing
SRT/VTT	01:23:45,123 (HH:MM:SS,ms)	Subtitles
FFmpeg	01:23:45.123 (HH:MM:SS.ms)	FFmpeg commands
Milliseconds	5025123	Programmatic processing
Seconds	5025.123	Simple calculations
ISO 8601	PT1H23M45S	Duration metadata

Timecode Conversion

Copy
# Convert HH:MM:SS to seconds
echo "01:23:45" | awk -F: '{print $1*3600 + $2*60 + $3}'
# Output: 5025

# Convert seconds to HH:MM:SS
echo 5025 | awk '{h=int($1/3600); m=int(($1%3600)/60); s=$1%60; printf "%02d:%02d:%02d\n", h, m, s}'
# Output: 01:23:45

# FFmpeg: Extract segment by timestamp
ffmpeg -i input.mp4 -ss 00:01:30.000 -to 00:02:45.500 -c copy segment.mp4

Configuration

Parameter	Description	Default
input_format	Source timecode format	auto-detect
output_format	Target timecode format	smpte
frame_rate	Video frame rate for SMPTE	29.97
drop_frame	Use drop-frame timecode	false
precision	Timestamp precision (seconds, ms, frames)	ms

Best Practices

1. Use millisecond precision for all internal processing. Store timestamps as milliseconds internally and convert to display formats only for output. This eliminates rounding errors that accumulate when converting between formats repeatedly.

2. Account for frame rate when converting SMPTE timecodes. SMPTE timecode at 29.97fps uses drop-frame notation (semicolons instead of colons) to maintain sync with real-time. Ignoring this causes drift of ~3.6 seconds per hour.

3. Validate timestamp ordering in chapter and cue point lists. Chapters must be sequential with no overlaps. Validate that each start time is after the previous end time, and that no timestamp exceeds the total duration of the media file.

4. Use FFmpeg's -ss before -i for fast seeking. Placing -ss before the input file triggers fast seeking (keyframe-based). Placing it after -i triggers slow seeking (decodes every frame from the start). For clip extraction, fast seeking is usually sufficient.

5. Store original timestamps alongside converted values. When converting between formats, keep the original value for reference. This allows re-conversion if the target format requirements change.

Common Issues

Subtitle timestamps are off by a few seconds after clip extraction. When cutting a clip starting at 00:10:00, subtitle timestamps must be shifted back by 10 minutes. Use FFmpeg's subtitle filter with a timing offset, or adjust the SRT file timestamps programmatically.

SMPTE timecode doesn't match wall-clock time at 29.97fps. 29.97fps video runs slightly slower than 30fps, causing timecode drift. Drop-frame timecode (DF) compensates by skipping frame numbers periodically. Use DF for broadcast content that needs real-time accuracy.

Timestamps from different sources don't align. Camera timecodes, audio recorder timecodes, and screen captures may use different starting points. Establish a common sync point (slate clap, timecode jam) and offset all sources relative to it.