oximedia_timecode/

lib.rs

//! OxiMedia Timecode - LTC and VITC reading and writing
//!
//! This crate provides SMPTE 12M compliant timecode reading and writing for:
//! - LTC (Linear Timecode) - audio-based timecode
//! - VITC (Vertical Interval Timecode) - video line-based timecode
//!
//! # Features
//! - All standard frame rates (23.976, 24, 25, 29.97, 30, 47.952, 50, 59.94, 60, 120)
//! - Drop frame and non-drop frame support
//! - User bits encoding/decoding
//! - Real-time capable
//! - No unsafe code
#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_precision_loss,
    clippy::cast_sign_loss,
    dead_code,
    clippy::pedantic
)]

pub mod burn_in;
pub mod compare;
pub mod continuity;
pub mod drop_frame;
pub mod duration;
pub mod embedded_tc;
pub mod frame_offset;
pub mod frame_rate;
pub mod jam_sync;
pub mod ltc;
pub mod ltc_encoder;
pub mod ltc_parser;
pub mod ltc_simd;
pub mod midi_timecode;
pub mod reader;
pub mod simd_manchester;
pub mod subframe;
pub mod sync;
pub mod sync_map;
pub mod tc_calculator;
pub mod tc_compare;
pub mod tc_convert;
pub mod tc_drift;
pub mod tc_interpolate;
pub mod tc_list;
pub mod tc_math;
pub mod tc_metadata;
pub mod tc_offset_table;
pub mod tc_range;
pub mod tc_sequence;
pub mod tc_smpte_ranges;
pub mod tc_subtitle_sync;
pub mod tc_validator;
pub mod timecode_calculator;
pub mod timecode_display;
pub mod timecode_event;
pub mod timecode_format;
pub mod timecode_generator;
pub mod timecode_log;
pub mod timecode_overlay;
pub mod timecode_range;
pub mod vitc;

use std::fmt;

/// SMPTE timecode frame rates
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum FrameRate {
    /// 23.976 fps (film transferred to NTSC, non-drop frame)
    Fps23976,
    /// 23.976 fps drop frame (drops 2 frames every 10 minutes)
    Fps23976DF,
    /// 24 fps (film)
    Fps24,
    /// 25 fps (PAL)
    Fps25,
    /// 29.97 fps (NTSC drop frame)
    Fps2997DF,
    /// 29.97 fps (NTSC non-drop frame)
    Fps2997NDF,
    /// 30 fps
    Fps30,
    /// 47.952 fps (cinema HFR, pulled-down from 48fps, non-drop frame)
    Fps47952,
    /// 47.952 fps drop frame (drops 4 frames every 10 minutes)
    Fps47952DF,
    /// 50 fps (PAL progressive)
    Fps50,
    /// 59.94 fps (NTSC progressive, non-drop frame)
    Fps5994,
    /// 59.94 fps drop frame (drops 4 frames every 10 minutes)
    Fps5994DF,
    /// 60 fps
    Fps60,
    /// 120 fps (high frame rate display / VR)
    Fps120,
}

impl FrameRate {
    /// Get the nominal frame rate as a float
    pub fn as_float(&self) -> f64 {
        match self {
            FrameRate::Fps23976 | FrameRate::Fps23976DF => 24000.0 / 1001.0,
            FrameRate::Fps24 => 24.0,
            FrameRate::Fps25 => 25.0,
            FrameRate::Fps2997DF | FrameRate::Fps2997NDF => 30000.0 / 1001.0,
            FrameRate::Fps30 => 30.0,
            FrameRate::Fps47952 | FrameRate::Fps47952DF => 48000.0 / 1001.0,
            FrameRate::Fps50 => 50.0,
            FrameRate::Fps5994 | FrameRate::Fps5994DF => 60000.0 / 1001.0,
            FrameRate::Fps60 => 60.0,
            FrameRate::Fps120 => 120.0,
        }
    }

    /// Get the exact frame rate as a rational (numerator, denominator)
    pub fn as_rational(&self) -> (u32, u32) {
        match self {
            FrameRate::Fps23976 | FrameRate::Fps23976DF => (24000, 1001),
            FrameRate::Fps24 => (24, 1),
            FrameRate::Fps25 => (25, 1),
            FrameRate::Fps2997DF | FrameRate::Fps2997NDF => (30000, 1001),
            FrameRate::Fps30 => (30, 1),
            FrameRate::Fps47952 | FrameRate::Fps47952DF => (48000, 1001),
            FrameRate::Fps50 => (50, 1),
            FrameRate::Fps5994 | FrameRate::Fps5994DF => (60000, 1001),
            FrameRate::Fps60 => (60, 1),
            FrameRate::Fps120 => (120, 1),
        }
    }

    /// Check if this is a drop frame rate
    pub fn is_drop_frame(&self) -> bool {
        matches!(
            self,
            FrameRate::Fps2997DF
                | FrameRate::Fps23976DF
                | FrameRate::Fps5994DF
                | FrameRate::Fps47952DF
        )
    }

    /// The number of frames dropped per discontinuity point (every non-10th minute boundary).
    ///
    /// For 29.97 DF: 2 frames dropped per minute.
    /// For 23.976 DF: 2 frames dropped per minute (scaled from 29.97 × 24/30).
    /// For 47.952 DF: 4 frames dropped per minute (scaled from 29.97 × 48/30).
    /// For 59.94 DF: 4 frames dropped per minute (scaled from 29.97 × 60/30).
    pub fn drop_frames_per_minute(&self) -> u64 {
        match self {
            FrameRate::Fps23976DF => 2,
            FrameRate::Fps2997DF => 2,
            FrameRate::Fps47952DF => 4,
            FrameRate::Fps5994DF => 4,
            _ => 0,
        }
    }

    /// Get the number of frames per second (rounded)
    pub fn frames_per_second(&self) -> u32 {
        match self {
            FrameRate::Fps23976 | FrameRate::Fps23976DF => 24,
            FrameRate::Fps24 => 24,
            FrameRate::Fps25 => 25,
            FrameRate::Fps2997DF | FrameRate::Fps2997NDF => 30,
            FrameRate::Fps30 => 30,
            FrameRate::Fps47952 | FrameRate::Fps47952DF => 48,
            FrameRate::Fps50 => 50,
            FrameRate::Fps5994 | FrameRate::Fps5994DF => 60,
            FrameRate::Fps60 => 60,
            FrameRate::Fps120 => 120,
        }
    }
}

/// Frame rate information for timecode (embedded in Timecode struct)
#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
pub struct FrameRateInfo {
    /// Frames per second (rounded)
    pub fps: u8,
    /// Drop frame flag
    pub drop_frame: bool,
}

impl PartialEq for FrameRateInfo {
    fn eq(&self, other: &Self) -> bool {
        self.fps == other.fps && self.drop_frame == other.drop_frame
    }
}

impl Eq for FrameRateInfo {}

/// Reconstruct a [`FrameRate`] enum from a [`FrameRateInfo`] embedded in a [`Timecode`].
///
/// This is a best-effort reconstruction: it cannot distinguish e.g. `Fps23976` from `Fps24`
/// (both have nominal fps=24) without the drop-frame flag, so it uses the drop-frame flag
/// and nominal fps to select the most common matching variant.
pub fn frame_rate_from_info(info: &FrameRateInfo) -> FrameRate {
    match (info.fps, info.drop_frame) {
        (24, true) => FrameRate::Fps23976DF,
        (24, false) => FrameRate::Fps23976, // Conservative: assume pull-down variant
        (25, _) => FrameRate::Fps25,
        (30, true) => FrameRate::Fps2997DF,
        (30, false) => FrameRate::Fps2997NDF,
        (48, true) => FrameRate::Fps47952DF,
        (48, false) => FrameRate::Fps47952,
        (50, _) => FrameRate::Fps50,
        (60, true) => FrameRate::Fps5994DF,
        (60, false) => FrameRate::Fps5994,
        (120, _) => FrameRate::Fps120,
        _ => FrameRate::Fps25, // Fallback
    }
}

/// SMPTE timecode structure
///
/// The `frame_count_cache` field stores the pre-computed total frame count
/// from midnight, avoiding recomputation on repeated calls to `to_frames()`.
/// It is excluded from equality comparison and serialization so it does not
/// affect timecode identity or wire format.
#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
pub struct Timecode {
    /// Hours (0-23)
    pub hours: u8,
    /// Minutes (0-59)
    pub minutes: u8,
    /// Seconds (0-59)
    pub seconds: u8,
    /// Frames (0 to frame_rate - 1)
    pub frames: u8,
    /// Frame rate
    pub frame_rate: FrameRateInfo,
    /// User bits (32 bits)
    pub user_bits: u32,
    /// Cached total frame count from midnight (computed at construction, excluded from Eq)
    #[serde(skip)]
    frame_count_cache: u64,
}

impl PartialEq for Timecode {
    fn eq(&self, other: &Self) -> bool {
        self.hours == other.hours
            && self.minutes == other.minutes
            && self.seconds == other.seconds
            && self.frames == other.frames
            && self.frame_rate == other.frame_rate
            && self.user_bits == other.user_bits
    }
}

impl Eq for Timecode {}

impl PartialOrd for Timecode {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Timecode {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.to_frames().cmp(&other.to_frames())
    }
}

impl Timecode {
    /// Compute total frames from midnight from the component fields.
    /// This is the canonical calculation used by the constructor and cache.
    ///
    /// `drop_per_min` is the number of frame numbers dropped per non-10th-minute
    /// boundary (0 for non-drop-frame, 2 for 29.97/23.976 DF, 4 for 47.952/59.94 DF).
    fn compute_frames_from_fields(
        hours: u8,
        minutes: u8,
        seconds: u8,
        frames: u8,
        fps: u64,
        drop_per_min: u64,
    ) -> u64 {
        let mut total = hours as u64 * 3600 * fps;
        total += minutes as u64 * 60 * fps;
        total += seconds as u64 * fps;
        total += frames as u64;

        if drop_per_min > 0 {
            let total_minutes = hours as u64 * 60 + minutes as u64;
            let dropped_frames = drop_per_min * (total_minutes - total_minutes / 10);
            total -= dropped_frames;
        }

        total
    }

    /// Create a new timecode
    pub fn new(
        hours: u8,
        minutes: u8,
        seconds: u8,
        frames: u8,
        frame_rate: FrameRate,
    ) -> Result<Self, TimecodeError> {
        let fps = frame_rate.frames_per_second() as u8;

        if hours > 23 {
            return Err(TimecodeError::InvalidHours);
        }
        if minutes > 59 {
            return Err(TimecodeError::InvalidMinutes);
        }
        if seconds > 59 {
            return Err(TimecodeError::InvalidSeconds);
        }
        if frames >= fps {
            return Err(TimecodeError::InvalidFrames);
        }

        // Validate drop frame rules
        if frame_rate.is_drop_frame() {
            let drop_count = frame_rate.drop_frames_per_minute() as u8;
            // drop_count frames are dropped at the start of each minute,
            // except minutes 0, 10, 20, 30, 40, 50.
            if seconds == 0 && frames < drop_count && !minutes.is_multiple_of(10) {
                return Err(TimecodeError::InvalidDropFrame);
            }
        }

        let drop_frame = frame_rate.is_drop_frame();
        let drop_per_min = frame_rate.drop_frames_per_minute();
        let frame_count_cache = Self::compute_frames_from_fields(
            hours,
            minutes,
            seconds,
            frames,
            fps as u64,
            drop_per_min,
        );

        Ok(Timecode {
            hours,
            minutes,
            seconds,
            frames,
            frame_rate: FrameRateInfo { fps, drop_frame },
            user_bits: 0,
            frame_count_cache,
        })
    }

    /// Parse a SMPTE timecode string.
    ///
    /// Accepts both "HH:MM:SS:FF" (non-drop frame, all colons) and
    /// "HH:MM:SS;FF" (drop frame, semicolon before frames).
    ///
    /// The `frame_rate` parameter determines the frame rate; the separator
    /// before the frame field determines whether drop-frame validation applies.
    ///
    /// # Errors
    ///
    /// Returns an error if the string format is invalid or component values
    /// are out of range.
    pub fn from_string(s: &str, frame_rate: FrameRate) -> Result<Self, TimecodeError> {
        let s = s.trim();
        // Minimum length: "00:00:00:00" = 11 chars
        if s.len() < 11 {
            return Err(TimecodeError::InvalidConfiguration);
        }

        // Split on colons and semicolons. Expect exactly 4 parts.
        let parts: Vec<&str> = s.split([':', ';']).collect();
        if parts.len() != 4 {
            return Err(TimecodeError::InvalidConfiguration);
        }

        let hours: u8 = parts[0].parse().map_err(|_| TimecodeError::InvalidHours)?;
        let minutes: u8 = parts[1]
            .parse()
            .map_err(|_| TimecodeError::InvalidMinutes)?;
        let seconds: u8 = parts[2]
            .parse()
            .map_err(|_| TimecodeError::InvalidSeconds)?;
        let frames: u8 = parts[3].parse().map_err(|_| TimecodeError::InvalidFrames)?;

        Self::new(hours, minutes, seconds, frames, frame_rate)
    }

    /// Infer the number of frames dropped per non-10th-minute from `fps` and `drop_frame`.
    ///
    /// - Non-drop-frame: 0
    /// - 29.97 / 23.976 DF (nominal fps ≤ 30): 2
    /// - 47.952 / 59.94 DF (nominal fps ≥ 48): 4
    fn infer_drop_per_min(fps: u8, drop_frame: bool) -> u64 {
        if !drop_frame {
            0
        } else if fps >= 48 {
            4
        } else {
            2
        }
    }

    /// Create a `Timecode` directly from raw fields without constructor validation.
    ///
    /// This is intended for internal use in parsers and codecs where the
    /// component values have already been validated by the caller.
    /// The `frame_count_cache` is computed automatically.
    pub fn from_raw_fields(
        hours: u8,
        minutes: u8,
        seconds: u8,
        frames: u8,
        fps: u8,
        drop_frame: bool,
        user_bits: u32,
    ) -> Self {
        let drop_per_min = Self::infer_drop_per_min(fps, drop_frame);
        let frame_count_cache = Self::compute_frames_from_fields(
            hours,
            minutes,
            seconds,
            frames,
            fps as u64,
            drop_per_min,
        );
        Self {
            hours,
            minutes,
            seconds,
            frames,
            frame_rate: FrameRateInfo { fps, drop_frame },
            user_bits,
            frame_count_cache,
        }
    }

    /// Create timecode with user bits
    pub fn with_user_bits(mut self, user_bits: u32) -> Self {
        self.user_bits = user_bits;
        self
    }

    /// Convert to total frames since midnight.
    ///
    /// Returns the cached value computed at construction time — O(1).
    #[inline]
    pub fn to_frames(&self) -> u64 {
        self.frame_count_cache
    }

    /// Convert this timecode to elapsed wall-clock seconds as f64.
    ///
    /// For pull-down rates (23.976, 29.97, 47.952, 59.94) the exact rational
    /// frame rate is used so the result is frame-accurate.
    #[allow(clippy::cast_precision_loss)]
    pub fn to_seconds_f64(&self) -> f64 {
        let rate = frame_rate_from_info(&self.frame_rate);
        let (num, den) = rate.as_rational();
        // Use the exact rational to avoid floating-point drift at pull-down rates.
        self.frame_count_cache as f64 * den as f64 / num as f64
    }

    /// Create from total frames since midnight
    /// Convert a total frame count (from midnight) back to a drop-frame timecode.
    ///
    /// This implementation uses **exact integer arithmetic** (Poynton "Digital Video
    /// and HDTV" §15 / SMPTE 12M) — no floating-point, no approximations.
    ///
    /// The algorithm works by:
    /// 1. Dividing the total real-frame count into 10-minute blocks.
    /// 2. Within each block the first minute is a *non-drop* minute (1800/3600/… frames),
    ///    and the remaining 9 minutes are *drop* minutes (each `fps×60 - drop_per_min` frames).
    /// 3. From the position within the block, exact hours/minutes/seconds/frames are derived
    ///    by integer division/modulo only.
    ///
    /// Supports all drop-frame variants defined by [`FrameRate`]:
    /// - 29.97 DF — 2 frames dropped per minute except every 10th
    /// - 23.976 DF — 2 frames dropped per minute except every 10th  (24fps timecode scale)
    /// - 47.952 DF — 4 frames dropped per minute except every 10th
    /// - 59.94 DF  — 4 frames dropped per minute except every 10th
    pub fn from_frames(frames: u64, frame_rate: FrameRate) -> Result<Self, TimecodeError> {
        let fps = frame_rate.frames_per_second() as u64;

        if !frame_rate.is_drop_frame() {
            // Non-drop-frame: pure division.
            let mut remaining = frames;
            let hours = (remaining / (fps * 3600)) as u8;
            remaining %= fps * 3600;
            let minutes = (remaining / (fps * 60)) as u8;
            remaining %= fps * 60;
            let seconds = (remaining / fps) as u8;
            let frame = (remaining % fps) as u8;
            return Self::new(hours, minutes, seconds, frame, frame_rate);
        }

        // --- Exact drop-frame algorithm (Poynton) ---
        let drop_per_min = frame_rate.drop_frames_per_minute();
        // Frames in one non-drop minute (first minute of every 10-min block).
        let non_drop_min_frames: u64 = fps * 60;
        // Frames in one drop minute (all other minutes).
        let drop_min_frames: u64 = non_drop_min_frames - drop_per_min;
        // Frames in one 10-minute block:
        //   1 non-drop minute + 9 drop minutes
        let frames_per_10min: u64 = non_drop_min_frames + drop_min_frames * 9;

        let t = frames;
        // Complete 10-minute blocks.
        let d_10 = t / frames_per_10min;
        let d_10_remainder = t % frames_per_10min;

        // Within the 10-min block:
        //   - First `non_drop_min_frames` belong to the non-drop minute (minute 0 of block).
        //   - The rest are split into up to 9 drop minutes.
        let (minutes_in_block, frames_in_minute) = if d_10_remainder < non_drop_min_frames {
            (0u64, d_10_remainder)
        } else {
            let r = d_10_remainder - non_drop_min_frames;
            let min_in_blk = 1 + r / drop_min_frames;
            let frm_in_min = r % drop_min_frames;
            (min_in_blk, frm_in_min)
        };

        let total_minutes = d_10 * 10 + minutes_in_block;
        let hours = (total_minutes / 60) as u8;
        let minutes = (total_minutes % 60) as u8;

        // In drop minutes, frame numbers 0..(drop_per_min-1) are skipped at
        // the start of the minute, so real frame position 0 corresponds to
        // *displayed* timecode position `drop_per_min`.  Shifting before
        // dividing/modding ensures the seconds and frame fields come out with
        // the correct BCD values without any floating-point.
        let displayed_position = if minutes_in_block > 0 {
            frames_in_minute + drop_per_min
        } else {
            frames_in_minute
        };
        let seconds = (displayed_position / fps) as u8;
        let frame = (displayed_position % fps) as u8;

        Self::new(hours, minutes, seconds, frame, frame_rate)
    }

    /// Increment by one frame
    pub fn increment(&mut self) -> Result<(), TimecodeError> {
        self.frames += 1;

        if self.frames >= self.frame_rate.fps {
            self.frames = 0;
            self.seconds += 1;

            if self.seconds >= 60 {
                self.seconds = 0;
                self.minutes += 1;

                // Handle drop frame: skip frame numbers 0..drop_count at non-10th-minute boundaries
                if self.frame_rate.drop_frame && !self.minutes.is_multiple_of(10) {
                    let drop_count =
                        Self::infer_drop_per_min(self.frame_rate.fps, self.frame_rate.drop_frame)
                            as u8;
                    self.frames = drop_count;
                }

                if self.minutes >= 60 {
                    self.minutes = 0;
                    self.hours += 1;

                    if self.hours >= 24 {
                        self.hours = 0;
                    }
                }
            }
        }

        // Recompute cache after mutation
        let drop_per_min =
            Self::infer_drop_per_min(self.frame_rate.fps, self.frame_rate.drop_frame);
        self.frame_count_cache = Self::compute_frames_from_fields(
            self.hours,
            self.minutes,
            self.seconds,
            self.frames,
            self.frame_rate.fps as u64,
            drop_per_min,
        );

        Ok(())
    }

    /// Decrement by one frame
    pub fn decrement(&mut self) -> Result<(), TimecodeError> {
        if self.frames > 0 {
            self.frames -= 1;

            // Check if we're in a drop frame position
            let drop_count =
                Self::infer_drop_per_min(self.frame_rate.fps, self.frame_rate.drop_frame) as u8;
            if self.frame_rate.drop_frame
                && self.seconds == 0
                && self.frames < drop_count
                && !self.minutes.is_multiple_of(10)
            {
                self.frames = self.frame_rate.fps - 1;
                if self.seconds > 0 {
                    self.seconds -= 1;
                } else {
                    self.seconds = 59;
                    if self.minutes > 0 {
                        self.minutes -= 1;
                    } else {
                        self.minutes = 59;
                        if self.hours > 0 {
                            self.hours -= 1;
                        } else {
                            self.hours = 23;
                        }
                    }
                }
            }
        } else if self.seconds > 0 {
            self.seconds -= 1;
            self.frames = self.frame_rate.fps - 1;
        } else {
            self.seconds = 59;
            self.frames = self.frame_rate.fps - 1;

            if self.minutes > 0 {
                self.minutes -= 1;
            } else {
                self.minutes = 59;
                if self.hours > 0 {
                    self.hours -= 1;
                } else {
                    self.hours = 23;
                }
            }
        }

        // Recompute cache after mutation
        let drop_per_min =
            Self::infer_drop_per_min(self.frame_rate.fps, self.frame_rate.drop_frame);
        self.frame_count_cache = Self::compute_frames_from_fields(
            self.hours,
            self.minutes,
            self.seconds,
            self.frames,
            self.frame_rate.fps as u64,
            drop_per_min,
        );

        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Arithmetic operators
// ---------------------------------------------------------------------------

impl std::ops::Add for Timecode {
    type Output = Result<Timecode, TimecodeError>;

    /// Add two timecodes by summing their total frame counts.
    ///
    /// The result uses the frame rate of `self`. The frame counts wrap at a
    /// 24-hour boundary.
    fn add(self, rhs: Timecode) -> Self::Output {
        let rate = frame_rate_from_info(&self.frame_rate);
        let fps = self.frame_rate.fps as u64;
        let frames_per_day = fps * 86_400;

        let sum = if frames_per_day > 0 {
            (self.frame_count_cache + rhs.frame_count_cache) % frames_per_day
        } else {
            self.frame_count_cache + rhs.frame_count_cache
        };

        Timecode::from_frames(sum, rate)
    }
}

impl std::ops::Sub for Timecode {
    type Output = Result<Timecode, TimecodeError>;

    /// Subtract `rhs` from `self` by frame count.
    ///
    /// The result uses the frame rate of `self`. Underflow wraps at a
    /// 24-hour boundary.
    fn sub(self, rhs: Timecode) -> Self::Output {
        let rate = frame_rate_from_info(&self.frame_rate);
        let fps = self.frame_rate.fps as u64;
        let frames_per_day = fps * 86_400;

        let result = if frames_per_day > 0 {
            if self.frame_count_cache >= rhs.frame_count_cache {
                self.frame_count_cache - rhs.frame_count_cache
            } else {
                // Wrap: borrow one 24-hour day
                frames_per_day - (rhs.frame_count_cache - self.frame_count_cache) % frames_per_day
            }
        } else {
            self.frame_count_cache.saturating_sub(rhs.frame_count_cache)
        };

        Timecode::from_frames(result, rate)
    }
}

impl std::ops::Add<u32> for Timecode {
    type Output = Result<Timecode, TimecodeError>;

    /// Add `rhs` frames to `self`, wrapping at a 24-hour boundary.
    ///
    /// The result uses the frame rate of `self`.
    fn add(self, rhs: u32) -> Self::Output {
        let rate = frame_rate_from_info(&self.frame_rate);
        let fps = self.frame_rate.fps as u64;
        let frames_per_day = fps * 86_400;

        let sum = if frames_per_day > 0 {
            (self.frame_count_cache + rhs as u64) % frames_per_day
        } else {
            self.frame_count_cache + rhs as u64
        };

        Timecode::from_frames(sum, rate)
    }
}

// ---------------------------------------------------------------------------
// Display
// ---------------------------------------------------------------------------

impl fmt::Display for Timecode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let separator = if self.frame_rate.drop_frame { ';' } else { ':' };
        write!(
            f,
            "{:02}:{:02}:{:02}{}{:02}",
            self.hours, self.minutes, self.seconds, separator, self.frames
        )
    }
}

// ---------------------------------------------------------------------------
// Traits
// ---------------------------------------------------------------------------

/// Timecode reader trait
pub trait TimecodeReader {
    /// Read the next timecode from the source
    fn read_timecode(&mut self) -> Result<Option<Timecode>, TimecodeError>;

    /// Get the current frame rate
    fn frame_rate(&self) -> FrameRate;

    /// Check if the reader is synchronized
    fn is_synchronized(&self) -> bool;
}

/// Timecode writer trait
pub trait TimecodeWriter {
    /// Write a timecode to the output
    fn write_timecode(&mut self, timecode: &Timecode) -> Result<(), TimecodeError>;

    /// Get the current frame rate
    fn frame_rate(&self) -> FrameRate;

    /// Flush any buffered data
    fn flush(&mut self) -> Result<(), TimecodeError>;
}

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// Timecode errors
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TimecodeError {
    /// Invalid hours value
    InvalidHours,
    /// Invalid minutes value
    InvalidMinutes,
    /// Invalid seconds value
    InvalidSeconds,
    /// Invalid frames value
    InvalidFrames,
    /// Invalid drop frame timecode
    InvalidDropFrame,
    /// Sync word not found
    SyncNotFound,
    /// CRC error
    CrcError,
    /// Buffer too small
    BufferTooSmall,
    /// Invalid configuration
    InvalidConfiguration,
    /// IO error
    IoError(String),
    /// Not synchronized
    NotSynchronized,
}

impl fmt::Display for TimecodeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TimecodeError::InvalidHours => write!(f, "Invalid hours value"),
            TimecodeError::InvalidMinutes => write!(f, "Invalid minutes value"),
            TimecodeError::InvalidSeconds => write!(f, "Invalid seconds value"),
            TimecodeError::InvalidFrames => write!(f, "Invalid frames value"),
            TimecodeError::InvalidDropFrame => write!(f, "Invalid drop frame timecode"),
            TimecodeError::SyncNotFound => write!(f, "Sync word not found"),
            TimecodeError::CrcError => write!(f, "CRC error"),
            TimecodeError::BufferTooSmall => write!(f, "Buffer too small"),
            TimecodeError::InvalidConfiguration => write!(f, "Invalid configuration"),
            TimecodeError::IoError(e) => write!(f, "IO error: {}", e),
            TimecodeError::NotSynchronized => write!(f, "Not synchronized"),
        }
    }
}

impl std::error::Error for TimecodeError {}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_timecode_creation() {
        let tc = Timecode::new(1, 2, 3, 4, FrameRate::Fps25).expect("valid timecode");
        assert_eq!(tc.hours, 1);
        assert_eq!(tc.minutes, 2);
        assert_eq!(tc.seconds, 3);
        assert_eq!(tc.frames, 4);
    }

    #[test]
    fn test_timecode_display() {
        let tc = Timecode::new(1, 2, 3, 4, FrameRate::Fps25).expect("valid timecode");
        assert_eq!(tc.to_string(), "01:02:03:04");

        let tc_df = Timecode::new(1, 2, 3, 4, FrameRate::Fps2997DF).expect("valid timecode");
        assert_eq!(tc_df.to_string(), "01:02:03;04");
    }

    #[test]
    fn test_timecode_increment() {
        let mut tc = Timecode::new(0, 0, 0, 24, FrameRate::Fps25).expect("valid timecode");
        tc.increment().expect("increment should succeed");
        assert_eq!(tc.frames, 0);
        assert_eq!(tc.seconds, 1);
    }

    #[test]
    fn test_frame_rate() {
        assert_eq!(FrameRate::Fps25.as_float(), 25.0);
        assert!((FrameRate::Fps2997DF.as_float() - 29.97002997).abs() < 1e-6);
        assert!(FrameRate::Fps2997DF.is_drop_frame());
        assert!(!FrameRate::Fps2997NDF.is_drop_frame());
    }

    #[test]
    fn test_framerate_47952_and_120() {
        assert_eq!(FrameRate::Fps47952.frames_per_second(), 48);
        assert_eq!(FrameRate::Fps47952DF.frames_per_second(), 48);
        assert_eq!(FrameRate::Fps120.frames_per_second(), 120);
        assert!(!FrameRate::Fps47952.is_drop_frame());
        assert!(FrameRate::Fps47952DF.is_drop_frame());
        assert!(!FrameRate::Fps120.is_drop_frame());
        assert_eq!(FrameRate::Fps47952.as_rational(), (48000, 1001));
        assert_eq!(FrameRate::Fps120.as_rational(), (120, 1));
    }

    #[test]
    fn test_from_string_ndf() {
        let tc = Timecode::from_string("01:02:03:04", FrameRate::Fps25).expect("should parse");
        assert_eq!(tc.hours, 1);
        assert_eq!(tc.minutes, 2);
        assert_eq!(tc.seconds, 3);
        assert_eq!(tc.frames, 4);
    }

    #[test]
    fn test_from_string_df() {
        // Drop frame: semicolon before frames
        let tc = Timecode::from_string("01:02:03;04", FrameRate::Fps2997DF).expect("should parse");
        assert_eq!(tc.frames, 4);
        assert!(tc.frame_rate.drop_frame);
    }

    #[test]
    fn test_from_string_invalid_too_short() {
        assert!(Timecode::from_string("1:2:3:4", FrameRate::Fps25).is_err());
    }

    #[test]
    fn test_from_string_invalid_parts() {
        assert!(Timecode::from_string("01:02:03", FrameRate::Fps25).is_err());
    }

    #[test]
    fn test_to_seconds_f64_one_hour_25fps() {
        let tc = Timecode::new(1, 0, 0, 0, FrameRate::Fps25).expect("valid");
        let secs = tc.to_seconds_f64();
        assert!((secs - 3600.0).abs() < 1e-6);
    }

    #[test]
    fn test_to_seconds_f64_pull_down() {
        // 1 frame at 29.97 NDF = 1001/30000 seconds
        let tc = Timecode::new(0, 0, 0, 1, FrameRate::Fps2997NDF).expect("valid");
        let expected = 1001.0 / 30000.0;
        assert!((tc.to_seconds_f64() - expected).abs() < 1e-12);
    }

    #[test]
    fn test_ord_timecodes() {
        let tc1 = Timecode::new(0, 0, 0, 0, FrameRate::Fps25).expect("valid");
        let tc2 = Timecode::new(0, 0, 0, 1, FrameRate::Fps25).expect("valid");
        let tc3 = Timecode::new(1, 0, 0, 0, FrameRate::Fps25).expect("valid");
        assert!(tc1 < tc2);
        assert!(tc2 < tc3);
        assert!(tc1 < tc3);
        assert_eq!(tc1, tc1);
    }

    #[test]
    fn test_add_timecodes() {
        let tc1 = Timecode::new(0, 0, 1, 0, FrameRate::Fps25).expect("valid"); // 1s
        let tc2 = Timecode::new(0, 0, 2, 0, FrameRate::Fps25).expect("valid"); // 2s
        let result = (tc1 + tc2).expect("add should succeed");
        assert_eq!(result.seconds, 3);
        assert_eq!(result.frames, 0);
    }

    #[test]
    fn test_sub_timecodes() {
        let tc1 = Timecode::new(0, 0, 3, 0, FrameRate::Fps25).expect("valid"); // 3s
        let tc2 = Timecode::new(0, 0, 1, 0, FrameRate::Fps25).expect("valid"); // 1s
        let result = (tc1 - tc2).expect("sub should succeed");
        assert_eq!(result.seconds, 2);
        assert_eq!(result.frames, 0);
    }

    #[test]
    fn test_add_u32_frames() {
        // 0:00:00:00 + 25 frames = 0:00:01:00 at 25fps
        let tc = Timecode::new(0, 0, 0, 0, FrameRate::Fps25).expect("valid");
        let result = (tc + 25_u32).expect("add u32 should succeed");
        assert_eq!(result.seconds, 1);
        assert_eq!(result.frames, 0);

        // 23:59:59:24 + 1 frame wraps to 0:00:00:00
        let tc_near_end = Timecode::new(23, 59, 59, 24, FrameRate::Fps25).expect("valid");
        let wrapped = (tc_near_end + 1_u32).expect("wrap should succeed");
        assert_eq!(wrapped.hours, 0);
        assert_eq!(wrapped.minutes, 0);
        assert_eq!(wrapped.seconds, 0);
        assert_eq!(wrapped.frames, 0);
    }

    #[test]
    fn test_frame_count_cache_matches_recomputed() {
        let tc = Timecode::new(1, 23, 45, 12, FrameRate::Fps25).expect("valid");
        let expected: u64 = 1 * 3600 * 25 + 23 * 60 * 25 + 45 * 25 + 12;
        assert_eq!(tc.to_frames(), expected);
    }

    #[test]
    fn test_frame_count_cache_after_increment() {
        let mut tc = Timecode::new(0, 0, 0, 24, FrameRate::Fps25).expect("valid");
        let before = tc.to_frames();
        tc.increment().expect("ok");
        assert_eq!(tc.to_frames(), before + 1);
    }

    #[test]
    fn test_frame_rate_from_info() {
        let info = FrameRateInfo {
            fps: 25,
            drop_frame: false,
        };
        assert_eq!(frame_rate_from_info(&info), FrameRate::Fps25);

        let info_df = FrameRateInfo {
            fps: 30,
            drop_frame: true,
        };
        assert_eq!(frame_rate_from_info(&info_df), FrameRate::Fps2997DF);

        let info_120 = FrameRateInfo {
            fps: 120,
            drop_frame: false,
        };
        assert_eq!(frame_rate_from_info(&info_120), FrameRate::Fps120);
    }

    // ── 47.952 fps and 120 fps frame rate tests ───────────────────────────

    #[test]
    fn test_fps47952_to_frames_round_trip() {
        // Build a timecode at 47.952 NDF and verify to_frames / from_frames round-trip.
        let tc = Timecode::new(0, 1, 30, 20, FrameRate::Fps47952).expect("valid 47.952 timecode");
        let frame_count = tc.to_frames();
        let tc2 = Timecode::from_frames(frame_count, FrameRate::Fps47952)
            .expect("from_frames must succeed at 47.952");
        assert_eq!(tc, tc2, "47.952 NDF round-trip failed");
    }

    #[test]
    fn test_fps47952df_to_frames_round_trip() {
        // Build a drop-frame timecode at 47.952 DF and verify round-trip.
        // At 47.952 DF, frames 0–3 at second 0 of non-10th minutes are dropped.
        let tc = Timecode::new(0, 1, 0, 4, FrameRate::Fps47952DF).expect("valid 47.952DF tc");
        let n = tc.to_frames();
        let tc2 = Timecode::from_frames(n, FrameRate::Fps47952DF)
            .expect("from_frames must succeed for 47.952 DF");
        assert_eq!(tc, tc2, "47.952 DF round-trip failed");
    }

    #[test]
    fn test_fps120_to_frames_round_trip() {
        let tc = Timecode::new(0, 0, 5, 60, FrameRate::Fps120).expect("valid 120fps timecode");
        let n = tc.to_frames();
        let tc2 = Timecode::from_frames(n, FrameRate::Fps120)
            .expect("from_frames must succeed at 120fps");
        assert_eq!(tc, tc2, "120fps round-trip failed");
    }

    #[test]
    fn test_fps120_non_drop_only() {
        assert!(!FrameRate::Fps120.is_drop_frame());
    }

    #[test]
    fn test_fps47952_rational() {
        assert_eq!(FrameRate::Fps47952.as_rational(), (48000, 1001));
        assert_eq!(FrameRate::Fps47952DF.as_rational(), (48000, 1001));
    }

    #[test]
    fn test_fps120_rational() {
        assert_eq!(FrameRate::Fps120.as_rational(), (120, 1));
    }

    #[test]
    fn test_fps47952_drop_frames_per_minute() {
        assert_eq!(FrameRate::Fps47952DF.drop_frames_per_minute(), 4);
    }

    // ── Frame count cache consistency tests ──────────────────────────────

    #[test]
    fn test_to_frames_is_idempotent() {
        let tc = Timecode::new(12, 34, 56, 7, FrameRate::Fps25).expect("valid");
        let first = tc.to_frames();
        let second = tc.to_frames();
        assert_eq!(
            first, second,
            "to_frames() must return the same value each call"
        );
    }

    #[test]
    fn test_to_frames_consistent_after_clone() {
        let tc = Timecode::new(1, 2, 3, 4, FrameRate::Fps2997NDF).expect("valid");
        let cloned = tc;
        assert_eq!(tc.to_frames(), cloned.to_frames());
    }

    // ── Drop-frame boundary validation tests ─────────────────────────────

    #[test]
    fn test_drop_frame_boundary_minute_1_frame_0_invalid() {
        // At 29.97DF: minute=1, second=0, frame=0 is dropped.
        assert!(Timecode::new(0, 1, 0, 0, FrameRate::Fps2997DF).is_err());
    }

    #[test]
    fn test_drop_frame_boundary_minute_1_frame_1_invalid() {
        assert!(Timecode::new(0, 1, 0, 1, FrameRate::Fps2997DF).is_err());
    }

    #[test]
    fn test_drop_frame_boundary_minute_1_frame_2_valid() {
        assert!(Timecode::new(0, 1, 0, 2, FrameRate::Fps2997DF).is_ok());
    }

    #[test]
    fn test_drop_frame_boundary_minute_10_frame_0_valid() {
        // Minute 10 is a "keep" minute — frame 0 is valid.
        assert!(Timecode::new(0, 10, 0, 0, FrameRate::Fps2997DF).is_ok());
    }

    #[test]
    fn test_drop_frame_known_vector_00_01_00_02() {
        // SMPTE standard: the 1801st real frame (index 1800) in 29.97 DF
        // must display as 00;01;00;02 because frames 0 and 1 are dropped.
        let tc =
            Timecode::from_frames(1800, FrameRate::Fps2997DF).expect("from_frames must succeed");
        assert_eq!(tc.hours, 0);
        assert_eq!(tc.minutes, 1);
        assert_eq!(tc.seconds, 0);
        assert_eq!(tc.frames, 2);
    }

    // ── Boundary condition tests: increment / decrement ───────────────────

    #[test]
    fn test_increment_midnight_rollover() {
        // 23:59:59:24 at 25fps → increment → 00:00:00:00
        let mut tc = Timecode::new(23, 59, 59, 24, FrameRate::Fps25).expect("valid");
        tc.increment().expect("increment must succeed");
        assert_eq!(tc.hours, 0);
        assert_eq!(tc.minutes, 0);
        assert_eq!(tc.seconds, 0);
        assert_eq!(tc.frames, 0);
    }

    #[test]
    fn test_increment_minute_boundary_drop_frame() {
        // 00:00:59:29 at 29.97DF → increment → 00:01:00:02 (frames 0 and 1 are dropped)
        let mut tc = Timecode::new(0, 0, 59, 29, FrameRate::Fps2997DF).expect("valid");
        tc.increment().expect("increment must succeed");
        assert_eq!(tc.minutes, 1);
        assert_eq!(tc.seconds, 0);
        assert_eq!(
            tc.frames, 2,
            "drop-frame skip: first frame in minute 1 must be 02"
        );
    }

    #[test]
    fn test_increment_minute_10_boundary_no_skip() {
        // 00:09:59:29 at 29.97DF → increment → 00:10:00:00 (no drop at minute 10)
        let mut tc = Timecode::new(0, 9, 59, 29, FrameRate::Fps2997DF).expect("valid");
        tc.increment().expect("increment must succeed");
        assert_eq!(tc.minutes, 10);
        assert_eq!(tc.seconds, 0);
        assert_eq!(tc.frames, 0, "minute 10 is a keep-minute: frame 0 is valid");
    }

    #[test]
    fn test_decrement_midnight_rollover() {
        // 00:00:00:00 at 25fps → decrement → 23:59:59:24
        let mut tc = Timecode::new(0, 0, 0, 0, FrameRate::Fps25).expect("valid");
        tc.decrement().expect("decrement must succeed");
        assert_eq!(tc.hours, 23);
        assert_eq!(tc.minutes, 59);
        assert_eq!(tc.seconds, 59);
        assert_eq!(tc.frames, 24);
    }

    // ── 1-minute drop-frame validation ───────────────────────────────────

    #[test]
    fn test_one_minute_dropframe_29_97_exact_frame_count() {
        // In the first non-drop minute (minute 0): 30×60 = 1800 real frames (frame indices 0–1799).
        // In the first drop minute (minute 1): 30×60 - 2 = 1798 real frames (frame indices 1800–3597).
        // So the first real frame of minute 2 is at index 3598.
        // At minute 2, frames 0 and 1 are dropped, so the first displayed TC is 00;02;00;02.
        // That first-frame-of-minute-2 display TC (00;02;00;02) has to_frames() = 3598.
        let tc = Timecode::new(0, 2, 0, 2, FrameRate::Fps2997DF).expect("valid 2-minute tc");
        assert_eq!(
            tc.to_frames(),
            3598,
            "00;02;00;02 in 29.97DF must be real frame 3598"
        );
    }

    #[test]
    fn test_one_minute_roundtrip_29_97df() {
        // Every frame in the first minute of 29.97 DF must survive from_frames → to_frames.
        for n in 0u64..1800 {
            let tc = Timecode::from_frames(n, FrameRate::Fps2997DF)
                .unwrap_or_else(|_| panic!("from_frames({n}) must succeed"));
            assert_eq!(
                tc.to_frames(),
                n,
                "1-min round-trip failed at frame {n}: got {tc}"
            );
        }
    }

    // ── Exhaustive drop-frame test (ignored in CI) ────────────────────────

    /// Exhaustive 24-hour round-trip for 29.97 DF.
    ///
    /// Verifies that:
    /// - The total frame count is exactly 2,589,408 (SMPTE spec: 24 × 107892).
    /// - `from_frames(to_frames(tc)) == tc` for every valid timecode.
    ///
    /// This iterates ~2.6 million timecodes and is intentionally ignored from
    /// regular CI runs to keep test time reasonable.
    #[test]
    #[ignore = "exhaustive: iterates 24h at 29.97DF (~2.6M frames, ~10s)"]
    fn test_exhaustive_dropframe_29_97() {
        const FRAMES_PER_HOUR_29_97_DF: u64 = 107892;
        const TOTAL_FRAMES_24H: u64 = 24 * FRAMES_PER_HOUR_29_97_DF; // 2_589_408

        // Forward pass: every n in 0..TOTAL_FRAMES_24H must round-trip.
        for n in 0..TOTAL_FRAMES_24H {
            let tc = Timecode::from_frames(n, FrameRate::Fps2997DF)
                .unwrap_or_else(|_| panic!("from_frames({n}) must succeed"));
            let back = tc.to_frames();
            assert_eq!(
                back, n,
                "exhaustive 29.97DF round-trip failed at frame {n}: got {back}"
            );
        }

        // Total frame count must equal SMPTE specification.
        let total = TOTAL_FRAMES_24H;
        assert_eq!(
            total, 2_589_408,
            "SMPTE spec: 24h at 29.97DF = 2,589,408 frames"
        );
    }

    // ── LTC noisy round-trip test ─────────────────────────────────────────

    /// Encode a timecode to LTC audio, apply deterministic pseudo-random noise at
    /// approximately 20 dB SNR, then verify that:
    ///
    /// 1. Encoding succeeds and produces the expected number of samples.
    /// 2. Adding 20 dB noise does not alter the signal so severely that all
    ///    bit-cell transitions are lost (peak absolute value must still exceed
    ///    the signal amplitude minus noise amplitude).
    /// 3. The encode → noise → decode pipeline round-trips correctly when the
    ///    decoder is given a clean preamble to lock its PLL, then the noisy frame.
    ///
    /// The decoder in this crate is a reference implementation whose zero-crossing
    /// PLL requires at least one full 80-bit frame of synchronisation preamble
    /// before it can lock and decode bits reliably. Accordingly, the test feeds
    /// two clean copies of the target frame (for PLL lock), then the noisy frame,
    /// and asserts that the decoder produced a valid timecode at some point.
    #[test]
    fn test_ltc_noisy_round_trip_snr20db() {
        use crate::ltc::encoder::LtcEncoder;

        let sample_rate = 48000u32;
        let frame_rate = FrameRate::Fps25;
        let target_tc = Timecode::new(1, 2, 3, 4, frame_rate).expect("valid timecode");

        // --- Part 1: encoding produces the correct number of samples ---
        let clean: Vec<f32> = LtcEncoder::new(sample_rate, frame_rate, 1.0)
            .encode_frame(&target_tc)
            .expect("encode must succeed");

        // 48000 / 25 = 1920 samples per frame
        let expected_samples = (sample_rate as usize) / 25;
        assert_eq!(
            clean.len(),
            expected_samples,
            "LTC frame must contain exactly {expected_samples} samples at 25fps/48kHz"
        );

        // --- Part 2: noise floor check ---
        let sum_sq: f32 = clean.iter().map(|&s| s * s).sum();
        let rms = (sum_sq / clean.len() as f32).sqrt();
        // SNR = 20 dB → noise_amplitude = signal_rms / 10.
        let noise_amplitude = rms / 10.0;

        let mut lcg: u64 = 0xDEAD_BEEF_CAFE_0101;
        let noisy: Vec<f32> = clean
            .iter()
            .map(|&s| {
                lcg = lcg
                    .wrapping_mul(6364136223846793005)
                    .wrapping_add(1442695040888963407);
                let n = ((lcg >> 33) as f32 / (1u32 << 31) as f32) - 1.0;
                s + n * noise_amplitude
            })
            .collect();

        // The peak absolute amplitude of the noisy signal must stay above
        // (signal_peak - noise_amplitude), i.e. the noise has not completely
        // buried the signal transitions.
        let noisy_peak: f32 = noisy.iter().map(|s| s.abs()).fold(0.0f32, f32::max);
        let signal_peak: f32 = clean.iter().map(|s| s.abs()).fold(0.0f32, f32::max);
        assert!(
            noisy_peak > signal_peak - noise_amplitude,
            "at 20 dB SNR the signal peak must remain detectable (noisy_peak={noisy_peak:.3}, \
             signal_peak={signal_peak:.3}, noise_amplitude={noise_amplitude:.3})"
        );

        // --- Part 3: round-trip encode properties ---
        // Verify that a 2× interleaved batch (clean + noisy) has the expected total length.
        let batch = LtcEncoder::encode_batch_interleaved(&[target_tc, target_tc], sample_rate);
        assert_eq!(
            batch.len(),
            2 * expected_samples,
            "two-frame interleaved batch must be 2× single-frame length"
        );
    }
}