Overview
Requires Python 3.11+. Scripts use the `timecode` PyPI package (eoyilmaz/timecode). `extract.py` also needs ffprobe on PATH. Run scripts via `uv run`.
Recipes
Copy-paste command sequences agents can run via uv run.
Timecode to seconds (29.97 drop-frame)
uv run scripts/to_seconds.py --timecode 00:01:30;15 --fps 29.97Seconds to drop-frame timecode
uv run scripts/from_seconds.py --seconds 90.5 --fps 29.97Add a 5-second slate (wall-clock)
uv run scripts/calculate.py --timecode 01:00:00;00 --op add --offset-seconds 5 --fps 29.97Convert 24fps edit point to 29.97 DF sequence
uv run scripts/convert.py --timecode 00:10:00:00 --from-fps 24 --to-fps 29.97Convert drop-frame to non-drop-frame (same wall-clock)
uv run scripts/convert_df.py --timecode 01:00:00;00 --fps 29.97 --to non-drop-frameDetect format from a timecode string
uv run scripts/detect_format.py --timecode 01:00:00;00 --fps 29.97Analyze ffprobe or MediaInfo JSON
uv run scripts/analyze_metadata.py --input /path/to/ffprobe.jsonRead embedded timecode from a file
uv run scripts/extract.py --input /path/to/clip.movMap file seconds to embedded SMPTE (broadcast master)
uv run scripts/calculate.py --timecode 00:58:40;00 --op add --offset-seconds 80.013 --fps 30000/1001Operations
Each script returns structured JSON — see the script contract.
| Op ID | Script | Common flags |
|---|---|---|
timecode.analyze_metadata | analyze_metadata.py | --input |
timecode.calculate | calculate.py | --timecode, --fps |
timecode.convert | convert.py | --timecode |
timecode.convert_df | convert_df.py | --timecode, --fps |
timecode.detect_format | detect_format.py | --timecode, --fps |
timecode.extract | extract.py | --input |
timecode.from_seconds | from_seconds.py | --fps |
timecode.to_seconds | to_seconds.py | --timecode, --fps |
Do not use for
- Actual video trimming (convert to seconds, then use `video-transformation`)
- Legal frame-rate standards beyond SMPTE timecode display math