# oximedia-timecode TODO
## Current Status
- 35 source files covering SMPTE 12M timecode reading and writing
- Core: Timecode struct with hours/minutes/seconds/frames, FrameRate enum (23.976 to 60fps), FrameRateInfo, drop frame support, user bits
- LTC: ltc module (decoder/encoder), ltc_encoder, ltc_parser for audio-based timecode
- VITC: vitc module (decoder/encoder) for video line-based timecode
- Utilities: tc_calculator, tc_compare, tc_convert, tc_drift, tc_interpolate, tc_math, tc_metadata, tc_range, tc_smpte_ranges, tc_validator, timecode_calculator, timecode_format, timecode_range
- Other: burn_in, continuity, drop_frame, duration, frame_offset, frame_rate, midi_timecode, reader, sync, sync_map
- Traits: TimecodeReader, TimecodeWriter
- Dependencies: oximedia-core, oximedia-audio, serde
## Enhancements
- [x] Implement `std::ops::Add` and `std::ops::Sub` for `Timecode` to enable `tc1 + tc2` arithmetic directly (verified 2026-05-16; src/lib.rs:569 impl std::ops::Add for Timecode, :591 impl std::ops::Sub)
- [x] Add `Timecode::from_string` parser that accepts "HH:MM:SS:FF" and "HH:MM:SS;FF" (drop frame semicolon) (verified 2026-05-16; src/lib.rs:351 fn from_string)
- [ ] Extend `FrameRate` to support 47.952 fps (used in some cinema workflows) and 120 fps (verified-open 2026-05-16: no 47.952 or 120fps variants in frame_rate.rs)
- [x] Add `Timecode::to_seconds_f64` convenience method for quick floating-point time conversion (verified 2026-05-16; src/lib.rs:423 fn to_seconds_f64)
- [x] Implement `Ord` and `PartialOrd` for `Timecode` based on total frame count (verified 2026-05-16; src/lib.rs:252 impl PartialOrd, :258 impl Ord)
- [ ] Extend `tc_validator` to detect and report non-monotonic timecode sequences in streams (verified-open 2026-05-16: no non_monotonic detection in tc_validator.rs)
- [ ] Add SMPTE 309M support in `vitc` encoder for HD VITC (ATC/LTC embedded in HD-SDI ancillary data) (verified-open 2026-05-16: no SMPTE 309M/ATC in vitc/encoder.rs)
- [ ] Improve `drop_frame` module with exact frame-accurate drop frame calculation (current from_frames uses approximation) (verified-open 2026-05-16: no exact/precise from_frames variant in drop_frame.rs)
## New Features
- [x] Implement `timecode_generator` module for free-running timecode generation with configurable start time and frame rate (verified 2026-05-16; src/timecode_generator.rs:19 TimecodeGenerator, 262 lines)
- [x] Add `timecode_overlay` module for rendering timecode as text overlay on video frames (integration with burn_in) (verified 2026-05-16; src/timecode_overlay.rs:630 lines)
- [x] Implement `jam_sync` module for syncing local timecode generator to external timecode reference with holdover (verified 2026-05-16; src/jam_sync.rs:80 JamSyncController, 448 lines)
- [x] Add `timecode_event` module for event-triggered timecode capture (mark in/out points, cue triggers) (verified 2026-05-16; src/timecode_event.rs:60 TimecodeEvent, 378 lines)
- [x] Implement `ndf_to_df` and `df_to_ndf` conversion utilities in `tc_convert` for workflow interop (verified 2026-05-16; src/tc_convert.rs:237 fn ndf_to_df, :267 fn df_to_ndf)
- [x] Add `embedded_tc` module for reading/writing ATC (Ancillary Timecode) in SDI ancillary data packets (verified 2026-05-16; src/embedded_tc.rs:443 lines)
- [x] Implement `timecode_log` module for recording timecode-stamped production notes and metadata events (verified 2026-05-16; src/timecode_log.rs:490 lines)
- [x] Add `timecode_display` module for formatting timecode in different regional conventions (SMPTE vs EBU) (verified 2026-05-16; src/timecode_display.rs:360 lines)
## Performance
- [ ] Cache frame count in `Timecode` struct to avoid recomputing `to_frames()` on repeated access
- [ ] Implement batch LTC encoding in `ltc_encoder` that generates multiple frames of audio in a single call
- [ ] Use lookup table for drop frame minute boundaries in `from_frames` instead of division-based calculation
- [ ] Add SIMD-accelerated Manchester encoding/decoding for LTC bitstream processing
- [ ] Pre-compute VITC line insertion patterns in `vitc::encoder` for common frame rates
## Testing
- [ ] Add exhaustive drop frame validation test: iterate all valid timecodes in 24 hours at 29.97DF and verify frame count matches SMPTE specification
- [ ] Test `Timecode::increment`/`decrement` at all boundary conditions: midnight rollover, minute boundaries, drop frame skip points
- [ ] Add LTC encode-decode round-trip test with noisy audio signal (SNR sweep from 40dB to 6dB)
- [ ] Test `tc_drift` detection with synthetic timecode streams containing known drift rates
- [ ] Verify `tc_interpolate` accuracy for sub-frame interpolation between two known timecodes
- [ ] Add `midi_timecode` MTC quarter-frame encode/decode round-trip test for all frame rates
## Documentation
- [ ] Add drop frame timecode explanation with frame numbering diagram for 29.97DF
- [ ] Document LTC audio format specification (baud rate, modulation, sync word) in ltc module docs
- [ ] Add comparison table of LTC vs. VITC vs. MTC showing accuracy, latency, and use case recommendations