ofxLtcFFmpegSync

Warning
This project is currently under active development and is not yet stable for production use.

LTC-driven multi-video sync playback addon for openFrameworks 0.12.1 on macOS.

This addon receives SMPTE LTC from audio input, decodes it with libltc, and synchronizes one or more FFmpeg video decoders against a master clock.

Status

Work in progress. Core playback and LTC sync are functional. Stability has improved significantly, but tuning is still ongoing for aggressive timeline jumps and difficult media sources.

See:

• SPEC.md
• TODO.md

Features (current)

• LTC input via ofSoundStream (device/channel selectable)
• LTC decode via libltc
• FFmpeg-based video decode (video only, no audio output)
• Multi-video synchronized playback (SyncedPlayback)
• Backward jump handling with force-seek path
• Freeze policies:
• HoldLast
• Black
• PauseClock
• Session save/load (settings + media mappings)
• On-screen diagnostics:
• targetF / nowF / totalF / source fps
• decoder health (queue size, decode fps, last decoded pts)
• seek stats (total, last reason, per-reason counters)
• frame error diagnostics (mean/max/histogram) and mini timeline
• DF/NDF guard state and source risk indicators
• Guards/checkers:
• DF/NDF mismatch guard (warning + auto-correct in non-forced modes)
• Long-GOP source risk checker (gop_size, max_b_frames)
• CSV metrics export:
• /tmp/ofxLtcFFmpegSync_metrics.csv
• Headless pseudo-LTC test mode:
• --headless-test --headless-out <path>

Requirements

• openFrameworks 0.12.1
• macOS (Apple Silicon currently expected by this workspace setup)
• FFmpeg (Homebrew):
• libavformat, libavcodec, libswscale, libavutil, etc.
• libltc 1.3.x

Homebrew example:

brew install ffmpeg libltc

Build (dev project)

The repository includes a dev app project:

• ofxLtcFFmpegSyncDev/

Build with Xcode command line:

cd ofxLtcFFmpegSyncDev
xcodebuild -configuration Debug
or
xcodebuild -configuration Release

The generated app is in:

• ofxLtcFFmpegSyncDev/bin/

Runtime Notes

• Default mapping in the sample app is offset mode (LTC 01:00:00:00 -> media 00:00:00:00) via offsetSec = -3600.0.
• If your LTC signal format does not match settings (fps/drop-frame), behavior will degrade.
• Long-GOP sources may converge slower after jumps than intra codecs.

Headless Test

Run headless pseudo-LTC scenario and emit CSV:

cd ofxLtcFFmpegSyncDev
./bin/ofxLtcFFmpegSyncDevDebug.app/Contents/MacOS/ofxLtcFFmpegSyncDevDebug \
  --headless-test \
  --headless-out /tmp/ofxLtcFFmpegSync_headless.csv

Key Files

• src/ofxLtcMasterClock. - LTC decode + master time generation
• src/ofxFFmpegVideoPlayer. - FFmpeg decode thread + sync/seek logic
• src/ofxLtcSyncedPlayback. - multi-player coordinator + session save/load
• src/ofxLtcSyncSettings. - runtime tuning and presets
• src/ofxTimecode.* - timecode/frame conversion
• ofxLtcFFmpegSyncDev/src/ofApp.cpp - sample integration and diagnostics overlay

Known Gaps

• Embedded timecode mode (MOV-first) is not implemented yet.
• Master clock model is not finalized for every edge case.
• Headless mode currently uses pseudo-LTC scenario generation, not full real-input integration.

License

MIT. See LICENSE.