grafton_ndi/

frames.rs

//! Frame types for video, audio, and metadata.

use num_enum::{IntoPrimitive, TryFromPrimitive};

use std::{
    ffi::{CStr, CString},
    fmt,
    marker::PhantomData,
    num::NonZeroUsize,
    os::raw::c_char,
    ptr, slice, str,
};

use crate::{
    capture::{AudioKind, FrameFree, FrameSyncAudioFree, Guard, VideoKind},
    ndi_lib::*,
    recv_guard::{RecvAudioGuard, RecvMetadataGuard},
    Error, Result,
};

/// Video pixel format identifiers (FourCC codes).
///
/// These represent the various pixel formats supported by NDI for video frames.
/// The most common formats are BGRA/RGBA for full quality and UYVY for bandwidth-efficient streaming.
///
/// This enum is marked `#[non_exhaustive]` to allow future NDI SDK versions to add new formats
/// without breaking existing code. Always use a wildcard pattern when matching.
///
/// # Examples
///
/// ```
/// use grafton_ndi::PixelFormat;
///
/// // For maximum compatibility and quality
/// let format = PixelFormat::BGRA;
///
/// // For bandwidth-efficient streaming
/// let format = PixelFormat::UYVY;
///
/// // When matching, always include a wildcard for forward compatibility
/// match format {
///     PixelFormat::BGRA | PixelFormat::RGBA => println!("Full quality RGB"),
///     PixelFormat::UYVY => println!("Compressed YUV"),
///     _ => println!("Other format"),
/// }
/// ```
#[derive(Debug, TryFromPrimitive, IntoPrimitive, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
#[repr(u32)]
pub enum PixelFormat {
    /// YCbCr 4:2:2 format (16 bits per pixel) - bandwidth efficient.
    UYVY = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_UYVY as _,
    /// YCbCr 4:2:2 with alpha channel (24 bits per pixel).
    UYVA = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_UYVA as _,
    /// 16-bit YCbCr 4:2:2 format.
    P216 = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_P216 as _,
    /// 16-bit YCbCr 4:2:2 with alpha.
    PA16 = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_PA16 as _,
    /// Planar YCbCr 4:2:0 format (12 bits per pixel).
    YV12 = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_YV12 as _,
    /// Planar YCbCr 4:2:0 format (12 bits per pixel).
    I420 = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_I420 as _,
    /// Semi-planar YCbCr 4:2:0 format (12 bits per pixel).
    NV12 = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_NV12 as _,
    /// Blue-Green-Red-Alpha format (32 bits per pixel) - full quality.
    BGRA = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_BGRA as _,
    /// Blue-Green-Red with padding (32 bits per pixel).
    BGRX = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_BGRX as _,
    /// Red-Green-Blue-Alpha format (32 bits per pixel) - full quality.
    RGBA = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_RGBA as _,
    /// Red-Green-Blue with padding (32 bits per pixel).
    RGBX = NDIlib_FourCC_video_type_e_NDIlib_FourCC_video_type_RGBX as _,
}

/// Category of pixel format for buffer calculation and union field access.
///
/// This enum distinguishes between different memory layouts:
/// - **Packed**: All pixel components are interleaved in a single buffer
/// - **Planar420**: Y, U, V planes stored separately with 4:2:0 chroma subsampling
/// - **SemiPlanar420**: Y plane followed by interleaved UV plane (NV12)
/// - **PackedAlpha**: Packed 4:2:2 plane followed by an 8-bit alpha plane (UYVA)
/// - **SemiPlanar422**: 16-bit Y plane followed by interleaved CbCr plane (P216)
/// - **SemiPlanar422Alpha**: [`FormatCategory::SemiPlanar422`] followed by a
///   16-bit alpha plane (PA16)
///
/// This enum is marked `#[non_exhaustive]` because the NDI SDK's video FourCC
/// namespace is open and grows across releases; future formats may introduce
/// additional memory-layout categories.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum FormatCategory {
    /// Packed formats: simple stride * height buffer.
    Packed,
    /// Planar 4:2:0 with separate U and V planes (YV12, I420).
    Planar420,
    /// Semi-planar 4:2:0 with interleaved UV plane (NV12).
    SemiPlanar420,
    /// Packed UYVY plane followed by an 8-bit alpha plane whose stride is half
    /// the line stride (UYVA).
    PackedAlpha,
    /// Semi-planar 4:2:2 with a 16-bit Y plane followed by an interleaved
    /// 16-bit CbCr plane, both full height at the line stride (P216).
    SemiPlanar422,
    /// [`FormatCategory::SemiPlanar422`] followed by a 16-bit alpha plane at
    /// the line stride (PA16).
    SemiPlanar422Alpha,
}

/// Compile-time pixel format properties.
///
/// This struct encapsulates all format-specific knowledge in one location,
/// providing a single source of truth for buffer size calculations, stride
/// computation, and format category detection.
///
/// # Examples
///
/// ```
/// use grafton_ndi::{PixelFormat, FormatCategory};
///
/// let info = PixelFormat::BGRA.info();
/// assert_eq!(info.bytes_per_pixel(), 4);
/// assert_eq!(info.category(), FormatCategory::Packed);
///
/// let info = PixelFormat::NV12.info();
/// assert_eq!(info.bytes_per_pixel(), 1);
/// assert_eq!(info.category(), FormatCategory::SemiPlanar420);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PixelFormatInfo {
    /// Bytes per pixel for packed formats, or first-plane bytes per pixel for
    /// planar and semi-planar formats.
    bytes_per_pixel: u8,
    /// Format category for union field access and buffer calculation.
    category: FormatCategory,
}

impl PixelFormatInfo {
    /// Get bytes per pixel for packed formats, or first-plane bytes per pixel
    /// for planar and semi-planar formats (the Y plane, or the UYVY plane of
    /// UYVA).
    #[must_use]
    pub const fn bytes_per_pixel(&self) -> u8 {
        self.bytes_per_pixel
    }

    /// Get the format category.
    #[must_use]
    pub const fn category(&self) -> FormatCategory {
        self.category
    }

    /// Returns true if this is a planar 4:2:0 format (YV12, I420, or NV12).
    #[must_use]
    pub const fn is_planar_420(&self) -> bool {
        matches!(
            self.category,
            FormatCategory::Planar420 | FormatCategory::SemiPlanar420
        )
    }

    /// Calculate total buffer size for given dimensions and stride using
    /// checked arithmetic.
    ///
    /// # Arguments
    ///
    /// * `y_stride` - The first-plane line stride in bytes (for planar formats) or total line stride (for packed formats)
    /// * `height` - Frame height in pixels
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if `y_stride` or `height` is not
    /// positive, if planar 4:2:0 stride/height requirements are not met, if
    /// arithmetic overflows, or if the result exceeds the crate's maximum video
    /// frame size.
    ///
    /// # Format-specific calculations
    ///
    /// - **Packed RGB/YUV** (BGRA/BGRX/RGBA/RGBX/UYVY): `y_stride * height`
    /// - **Packed 4:2:2 with alpha UYVA**: requires even stride, then
    ///   `UYVY + A` where:
    ///   - UYVY plane: `y_stride * height`
    ///   - Alpha plane: `(y_stride/2) * height`
    /// - **Semi-planar 4:2:2 P216**: `Y + CbCr` where each plane is
    ///   `y_stride * height`
    /// - **Semi-planar 4:2:2 with alpha PA16**: `Y + CbCr + A` where each
    ///   plane is `y_stride * height`
    /// - **Planar 4:2:0 YV12/I420**: requires even stride and height,
    ///   then `Y + U + V` where:
    ///   - Y plane: `y_stride * height`
    ///   - U plane: `(y_stride/2) * (height/2)`
    ///   - V plane: `(y_stride/2) * (height/2)`
    /// - **Semi-planar 4:2:0 NV12**: requires even height, then `Y + UV` where:
    ///   - Y plane: `y_stride * height`
    ///   - UV plane: `y_stride * (height/2)`
    pub fn try_buffer_len(&self, y_stride: i32, height: i32) -> Result<usize> {
        if y_stride <= 0 {
            return Err(Error::InvalidFrame(format!(
                "Video line stride must be positive, got {y_stride}"
            )));
        }
        if height <= 0 {
            return Err(Error::InvalidFrame(format!(
                "Video frame height must be positive, got {height}"
            )));
        }

        let y_stride = usize::try_from(y_stride)
            .map_err(|_| Error::InvalidFrame(format!("Invalid y_stride value: {y_stride}")))?;
        let height = usize::try_from(height)
            .map_err(|_| Error::InvalidFrame(format!("Invalid height value: {height}")))?;

        let len = calculate_buffer_len_for_info_checked(*self, y_stride, height)?;
        validate_video_data_len(len)?;
        Ok(len)
    }
}

impl PixelFormat {
    /// Get compile-time format properties.
    ///
    /// This provides a single source of truth for all format-specific knowledge,
    /// including bytes per pixel and format category.
    ///
    /// # Examples
    ///
    /// ```
    /// use grafton_ndi::{PixelFormat, FormatCategory};
    ///
    /// // Get properties for BGRA (32 bpp packed)
    /// let info = PixelFormat::BGRA.info();
    /// assert_eq!(info.bytes_per_pixel(), 4);
    /// assert_eq!(info.category(), FormatCategory::Packed);
    ///
    /// // Get properties for YV12 (planar 4:2:0)
    /// let info = PixelFormat::YV12.info();
    /// assert_eq!(info.bytes_per_pixel(), 1);
    /// assert_eq!(info.category(), FormatCategory::Planar420);
    /// ```
    #[must_use]
    pub const fn info(self) -> PixelFormatInfo {
        match self {
            Self::BGRA | Self::BGRX | Self::RGBA | Self::RGBX => PixelFormatInfo {
                bytes_per_pixel: 4,
                category: FormatCategory::Packed,
            },
            Self::UYVY => PixelFormatInfo {
                bytes_per_pixel: 2,
                category: FormatCategory::Packed,
            },
            Self::UYVA => PixelFormatInfo {
                bytes_per_pixel: 2,
                category: FormatCategory::PackedAlpha,
            },
            Self::P216 => PixelFormatInfo {
                bytes_per_pixel: 2,
                category: FormatCategory::SemiPlanar422,
            },
            Self::PA16 => PixelFormatInfo {
                bytes_per_pixel: 2,
                category: FormatCategory::SemiPlanar422Alpha,
            },
            Self::YV12 | Self::I420 => PixelFormatInfo {
                bytes_per_pixel: 1,
                category: FormatCategory::Planar420,
            },
            Self::NV12 => PixelFormatInfo {
                bytes_per_pixel: 1,
                category: FormatCategory::SemiPlanar420,
            },
        }
    }

    /// Calculate line stride in bytes for a given width using checked
    /// arithmetic.
    ///
    /// For packed formats, this returns the total bytes per row.
    /// For planar and semi-planar formats, this returns the first-plane
    /// stride, which is what the SDK expects in `line_stride_in_bytes`.
    ///
    /// # Examples
    ///
    /// ```
    /// use grafton_ndi::PixelFormat;
    ///
    /// // BGRA: 4 bytes per pixel
    /// assert_eq!(PixelFormat::BGRA.try_line_stride(1920)?, 7680);
    ///
    /// // UYVY: 2 bytes per pixel
    /// assert_eq!(PixelFormat::UYVY.try_line_stride(1920)?, 3840);
    ///
    /// // NV12: Y-plane has 1 byte per pixel
    /// assert_eq!(PixelFormat::NV12.try_line_stride(1920)?, 1920);
    ///
    /// // P216: Y-plane has 16 bits per pixel
    /// assert_eq!(PixelFormat::P216.try_line_stride(1920)?, 3840);
    /// # Ok::<(), grafton_ndi::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if the width is nonpositive or odd
    /// or if the stride does not fit in `i32`.
    pub fn try_line_stride(self, width: i32) -> Result<i32> {
        validate_video_width(width)?;
        let width_usize = usize::try_from(width)
            .map_err(|_| Error::InvalidFrame(format!("Invalid width value: {width}")))?;
        let stride = min_video_line_stride_checked(self, width_usize)?;
        i32::try_from(stride).map_err(|_| {
            Error::InvalidFrame(format!("Video line stride {stride} exceeds i32 range"))
        })
    }

    /// Calculate the total buffer size needed for a frame with given dimensions
    /// using checked arithmetic.
    ///
    /// This computes the validated minimum stride from the width and delegates
    /// to the shared video layout validator.
    ///
    /// # Examples
    ///
    /// ```
    /// use grafton_ndi::PixelFormat;
    ///
    /// // BGRA 1920x1080: 1920 * 4 * 1080 = 8,294,400 bytes
    /// assert_eq!(PixelFormat::BGRA.try_buffer_size(1920, 1080)?, 8_294_400);
    ///
    /// // NV12 1920x1080: Y (1920*1080) + UV (1920*540) = 3,110,400 bytes
    /// assert_eq!(PixelFormat::NV12.try_buffer_size(1920, 1080)?, 3_110_400);
    /// # Ok::<(), grafton_ndi::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if dimensions are invalid for this
    /// format, if arithmetic overflows, or if the result exceeds the crate's
    /// maximum video frame size.
    pub fn try_buffer_size(self, width: i32, height: i32) -> Result<usize> {
        let layout = ValidatedVideoLayout::new_uncompressed(self, width, height, None)?;
        Ok(layout.data_len_bytes)
    }
}

impl From<PixelFormat> for i32 {
    fn from(value: PixelFormat) -> Self {
        let u32_value: u32 = value.into();
        u32_value as i32
    }
}

/// Video scan type (progressive, interlaced, or field-based).
///
/// This enum describes how video frames are scanned/displayed.
/// Most modern content uses Progressive, while legacy broadcast may use Interlaced or field-based formats.
///
/// This enum is marked `#[non_exhaustive]` to allow future NDI SDK versions to add new scan types
/// without breaking existing code. Always use a wildcard pattern when matching.
///
/// # Examples
///
/// ```
/// use grafton_ndi::ScanType;
///
/// let scan = ScanType::Progressive;
///
/// // When matching, always include a wildcard for forward compatibility
/// match scan {
///     ScanType::Progressive => println!("Progressive scan"),
///     ScanType::Interlaced => println!("Interlaced"),
///     _ => println!("Field-based or other"),
/// }
/// ```
#[derive(Debug, TryFromPrimitive, IntoPrimitive, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
#[repr(u32)]
pub enum ScanType {
    /// Progressive scan - full frames rendered sequentially.
    Progressive = NDIlib_frame_format_type_e_NDIlib_frame_format_type_progressive as _,
    /// Interlaced scan - alternating even/odd lines.
    Interlaced = NDIlib_frame_format_type_e_NDIlib_frame_format_type_interleaved as _,
    /// Field 0 only (first field of interlaced content).
    Field0 = NDIlib_frame_format_type_e_NDIlib_frame_format_type_field_0 as _,
    /// Field 1 only (second field of interlaced content).
    Field1 = NDIlib_frame_format_type_e_NDIlib_frame_format_type_field_1 as _,
}

impl From<ScanType> for i32 {
    fn from(value: ScanType) -> Self {
        let u32_value: u32 = value.into();
        u32_value as i32
    }
}

/// First-plane line stride for the supported uncompressed video formats.
/// Compressed and opaque payloads are not represented by safe frame types.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineStrideOrSize {
    /// Line stride in bytes for uncompressed formats.
    /// This is the number of bytes per row of video data.
    LineStrideBytes(i32),
}

impl From<LineStrideOrSize> for NDIlib_video_frame_v2_t__bindgen_ty_1 {
    fn from(value: LineStrideOrSize) -> Self {
        // Writing to a union field is safe when the field type implements Copy.
        // We write exactly one field of the union based on the enum variant.
        match value {
            LineStrideOrSize::LineStrideBytes(stride) =>
            {
                #[allow(clippy::field_reassign_with_default)]
                NDIlib_video_frame_v2_t__bindgen_ty_1 {
                    line_stride_in_bytes: stride,
                }
            }
        }
    }
}

/// An owned video frame with validated dimensions, format, stride, and buffer size.
///
/// Received frames retain their SDK stride and padding. Encoding processes only
/// active pixels. Use [`Self::builder`] for tightly packed outbound storage.
pub struct VideoFrame {
    layout: ValidatedVideoLayout,
    frame_rate_n: i32,
    frame_rate_d: i32,
    picture_aspect_ratio: f32,
    scan_type: ScanType,
    timecode: i64,
    data: Vec<u8>,
    metadata: Option<FrameMetadata>,
    timestamp: i64,
}

impl fmt::Debug for VideoFrame {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("VideoFrame")
            .field("width", &self.width())
            .field("height", &self.height())
            .field("pixel_format", &self.pixel_format())
            .field("frame_rate_n", &self.frame_rate_n)
            .field("frame_rate_d", &self.frame_rate_d)
            .field("picture_aspect_ratio", &self.picture_aspect_ratio)
            .field("scan_type", &self.scan_type)
            .field("timecode", &self.timecode)
            .field("data (bytes)", &self.data.len())
            .field("line_stride_or_size", &self.line_stride_or_size())
            .field("metadata", &self.metadata())
            .field("timestamp", &self.timestamp)
            .finish()
    }
}

impl Default for VideoFrame {
    fn default() -> Self {
        VideoFrame::builder()
            .build()
            .expect("Default VideoFrame should always succeed")
    }
}

impl VideoFrame {
    pub(crate) fn to_raw(&self) -> NDIlib_video_frame_v2_t {
        NDIlib_video_frame_v2_t {
            xres: self.layout.width,
            yres: self.layout.height,
            FourCC: self.layout.pixel_format.into(),
            frame_rate_N: self.frame_rate_n,
            frame_rate_D: self.frame_rate_d,
            picture_aspect_ratio: self.picture_aspect_ratio,
            frame_format_type: self.scan_type.into(),
            timecode: self.timecode,
            p_data: self.data.as_ptr() as *mut u8,
            __bindgen_anon_1: self.layout.line_stride_or_size.into(),
            p_metadata: self
                .metadata
                .as_ref()
                .map_or(ptr::null(), FrameMetadata::as_ptr),
            timestamp: self.timestamp,
        }
    }

    /// Get the frame width in pixels.
    pub fn width(&self) -> i32 {
        self.layout.width
    }

    /// Get the frame height in pixels.
    pub fn height(&self) -> i32 {
        self.layout.height
    }

    /// Get the supported pixel format.
    pub fn pixel_format(&self) -> PixelFormat {
        self.layout.pixel_format
    }

    /// Get the frame rate numerator.
    pub fn frame_rate_n(&self) -> i32 {
        self.frame_rate_n
    }

    /// Get the frame rate denominator.
    pub fn frame_rate_d(&self) -> i32 {
        self.frame_rate_d
    }

    /// Get the picture aspect ratio.
    pub fn picture_aspect_ratio(&self) -> f32 {
        self.picture_aspect_ratio
    }

    /// Get the scan type.
    pub fn scan_type(&self) -> ScanType {
        self.scan_type
    }

    /// Get the timecode in 100 ns units.
    ///
    /// Defaults to the SDK's synthesized-timecode sentinel. An explicit zero
    /// is passed through as a literal timecode.
    pub fn timecode(&self) -> i64 {
        self.timecode
    }

    /// Set the frame timecode in 100 ns units without reallocating its pixels.
    /// Use the SDK synthesized-timecode sentinel to request SDK clocking.
    pub fn set_timecode(&mut self, timecode: i64) {
        self.timecode = timecode;
    }

    /// Set the scan type without changing the frame's validated layout.
    pub fn set_scan_type(&mut self, scan_type: ScanType) {
        self.scan_type = scan_type;
    }

    /// Set the timestamp in 100 ns units. The SDK fills receive timestamps;
    /// outgoing timestamp values are passed through unchanged.
    pub fn set_timestamp(&mut self, timestamp: i64) {
        self.timestamp = timestamp;
    }

    /// Get the receive timestamp in 100 ns units since the Unix epoch.
    ///
    /// On receive the SDK supplies this value, or its undefined-timestamp
    /// sentinel when unavailable. Outbound values are passed through unchanged;
    /// the SDK defines this field for receiving.
    pub fn timestamp(&self) -> i64 {
        self.timestamp
    }

    /// Get the validated line stride or data size union field.
    pub fn line_stride_or_size(&self) -> LineStrideOrSize {
        self.layout.line_stride_or_size
    }

    pub(crate) fn validated_layout(&self) -> ValidatedVideoLayout {
        self.layout
    }

    /// Get the frame data.
    pub fn data(&self) -> &[u8] {
        &self.data
    }

    /// Get mutable access to the frame data without changing the validated
    /// layout.
    pub fn data_mut(&mut self) -> &mut [u8] {
        &mut self.data
    }

    /// Replace the owned frame data while preserving the validated layout.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if `data` is not exactly the validated
    /// layout size.
    pub fn replace_data(&mut self, data: Vec<u8>) -> Result<()> {
        if data.len() != self.layout.data_len_bytes {
            return Err(Error::InvalidFrame(format!(
                "Video data length {}, expected {} bytes for validated layout",
                data.len(),
                self.layout.data_len_bytes
            )));
        }

        self.data = data;
        Ok(())
    }

    /// Get frame metadata as UTF-8 text, if present.
    pub fn metadata(&self) -> Option<&str> {
        self.metadata.as_ref().map(FrameMetadata::as_str)
    }

    pub(crate) fn metadata_cstr(&self) -> Option<&CStr> {
        self.metadata.as_ref().map(FrameMetadata::as_cstr)
    }

    pub(crate) fn validated_metadata(&self) -> ValidatedFrameMetadata {
        ValidatedFrameMetadata {
            len_with_nul: self
                .metadata_cstr()
                .and_then(|m| NonZeroUsize::new(m.to_bytes_with_nul().len())),
            text_len: self.metadata().map_or(0, str::len),
        }
    }

    /// Replace frame metadata.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCString`] if `metadata` contains an interior NUL
    /// byte, or [`Error::InvalidFrame`] if the emitted C string would exceed
    /// the metadata size cap.
    pub fn set_metadata<S: Into<String>>(&mut self, metadata: Option<S>) -> Result<()> {
        self.metadata = metadata.map(FrameMetadata::new).transpose()?;
        Ok(())
    }

    /// Set the frame rate.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if the numerator or denominator is not
    /// positive.
    pub fn set_frame_rate(&mut self, numerator: i32, denominator: i32) -> Result<()> {
        validate_video_frame_metadata(numerator, denominator, self.picture_aspect_ratio)?;
        self.frame_rate_n = numerator;
        self.frame_rate_d = denominator;
        Ok(())
    }

    /// Set the picture aspect ratio.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if `ratio` is not finite and positive.
    pub fn set_picture_aspect_ratio(&mut self, ratio: f32) -> Result<()> {
        validate_video_frame_metadata(self.frame_rate_n, self.frame_rate_d, ratio)?;
        self.picture_aspect_ratio = ratio;
        Ok(())
    }

    /// Encode the video frame as PNG bytes.
    ///
    /// This method encodes the frame to PNG format, automatically handling color format
    /// conversion from the NDI frame format (BGRA/RGBA/etc.) to PNG-compatible RGBA.
    ///
    /// # Supported Formats
    ///
    /// - `RGBA`: Direct active-row encoding without a pixel copy
    /// - `BGRA`: Swaps red and blue channels and preserves alpha
    /// - `RGBX`: Treats the fourth byte as padding and writes opaque alpha
    /// - `BGRX`: Swaps red/blue and writes opaque alpha
    /// - Other formats: Returns an error (unsupported for now)
    ///
    /// # Stride Handling
    ///
    /// This method consumes active pixels row-by-row according to the frame's
    /// validated line stride. Valid row padding is skipped. RGBA rows borrow
    /// directly; other supported formats reuse at most `width * 4` scratch bytes.
    /// Codec buffers and encoded output require additional memory.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The frame format is not RGBA/RGBX/BGRA/BGRX
    /// - The frame uses data-size layout instead of line-stride layout
    /// - The backing data length does not match the validated layout
    /// - PNG encoding fails
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use grafton_ndi::{NDI, Finder, FinderOptions, ReceiverOptions, Receiver, ReceiverColorFormat};
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), grafton_ndi::Error> {
    /// # let ndi = NDI::new()?;
    /// # let finder = Finder::new(&ndi, &FinderOptions::default())?;
    /// # finder.wait_for_sources(Duration::from_millis(1000))?;
    /// # let sources = finder.current_sources()?;
    /// # let Some(source) = sources.first() else { return Ok(()); };
    /// # let options = ReceiverOptions::builder(source.clone())
    /// #     .color(ReceiverColorFormat::RGBX_RGBA)
    /// #     .build();
    /// # let receiver = Receiver::new(&ndi, &options)?;
    /// let video_frame = receiver.video().capture(Duration::from_secs(5))?;
    /// let png_bytes = video_frame.encode_png()?;
    /// std::fs::write("frame.png", &png_bytes)?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "image-encoding")]
    pub fn encode_png(&self) -> Result<Vec<u8>> {
        ImagePixelSource::new(self.layout, &self.data)?.encode_png()
    }

    /// Encode the video frame as JPEG bytes with the specified quality.
    ///
    /// This method encodes the frame to JPEG format, automatically handling color format
    /// conversion from the NDI frame format into codec component rows without
    /// a full-frame RGB staging buffer. Codec/output storage is additional.
    ///
    /// # Arguments
    ///
    /// * `quality` - JPEG quality from 1 (lowest) to 100 (highest). Typical values are 80-95.
    ///
    /// # Supported Formats
    ///
    /// - `RGBA` / `RGBX`: Emits RGB
    /// - `BGRA` / `BGRX`: Swaps red/blue and emits RGB
    /// - Other formats: Returns an error (unsupported for now)
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The frame format is not RGBA/RGBX/BGRA/BGRX
    /// - The frame uses data-size layout instead of line-stride layout
    /// - The backing data length does not match the validated layout
    /// - The quality is outside `1..=100`
    /// - The dimensions exceed JPEG's `u16` width/height range
    /// - JPEG encoding fails
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use grafton_ndi::{NDI, Finder, FinderOptions, ReceiverOptions, Receiver, ReceiverColorFormat};
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), grafton_ndi::Error> {
    /// # let ndi = NDI::new()?;
    /// # let finder = Finder::new(&ndi, &FinderOptions::default())?;
    /// # finder.wait_for_sources(Duration::from_millis(1000))?;
    /// # let sources = finder.current_sources()?;
    /// # let Some(source) = sources.first() else { return Ok(()); };
    /// # let options = ReceiverOptions::builder(source.clone())
    /// #     .color(ReceiverColorFormat::RGBX_RGBA)
    /// #     .build();
    /// # let receiver = Receiver::new(&ndi, &options)?;
    /// let video_frame = receiver.video().capture(Duration::from_secs(5))?;
    /// let jpeg_bytes = video_frame.encode_jpeg(85)?;
    /// std::fs::write("frame.jpg", &jpeg_bytes)?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "image-encoding")]
    pub fn encode_jpeg(&self, quality: u8) -> Result<Vec<u8>> {
        ImagePixelSource::new(self.layout, &self.data)?.encode_jpeg(quality)
    }

    /// Encode the video frame as a base64 data URL for embedding in HTML/JSON.
    ///
    /// This produces a string in the format: `data:image/png;base64,...` or
    /// `data:image/jpeg;base64,...` that can be directly used in HTML `<img>` tags
    /// or stored in JSON.
    ///
    /// # Arguments
    ///
    /// * `format` - The image format to use (PNG or JPEG with quality)
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use grafton_ndi::{NDI, Finder, FinderOptions, ReceiverOptions, Receiver, ReceiverColorFormat, ImageFormat};
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), grafton_ndi::Error> {
    /// # let ndi = NDI::new()?;
    /// # let finder = Finder::new(&ndi, &FinderOptions::default())?;
    /// # finder.wait_for_sources(Duration::from_millis(1000))?;
    /// # let sources = finder.current_sources()?;
    /// # let Some(source) = sources.first() else { return Ok(()); };
    /// # let options = ReceiverOptions::builder(source.clone())
    /// #     .color(ReceiverColorFormat::RGBX_RGBA)
    /// #     .build();
    /// # let receiver = Receiver::new(&ndi, &options)?;
    /// let video_frame = receiver.video().capture(Duration::from_secs(5))?;
    ///
    /// // As PNG
    /// let data_url = video_frame.encode_data_url(ImageFormat::Png)?;
    /// println!("<img src=\"{}\">", data_url);
    ///
    /// // As JPEG with quality 90
    /// let data_url = video_frame.encode_data_url(ImageFormat::Jpeg(90))?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "image-encoding")]
    pub fn encode_data_url(&self, format: ImageFormat) -> Result<String> {
        ImagePixelSource::new(self.layout, &self.data)?.encode_data_url(format)
    }

    /// Creates a `VideoFrame` from a raw NDI video frame with owned data.
    ///
    /// # Safety
    ///
    /// The descriptor must refer to one live allocation covering its SDK plane
    /// layout. All active row bytes must be initialized and remain immutable
    /// throughout this call; row padding may be uninitialized. Non-null metadata
    /// must satisfy the SDK's readable, NUL-terminated string contract.
    /// Only active pixels are copied, so the tightly packed result can outlive
    /// the source allocation.
    pub unsafe fn from_raw(c_frame: &NDIlib_video_frame_v2_t) -> Result<VideoFrame> {
        // Use the shared validation helper to validate and compute layout
        let layout = validate_video_layout(c_frame)?;
        let metadata_layout = unsafe { validate_frame_metadata(c_frame.p_metadata)? };

        Self::from_raw_validated(c_frame, layout, metadata_layout)
    }

    pub(crate) unsafe fn from_raw_validated(
        c_frame: &NDIlib_video_frame_v2_t,
        layout: ValidatedVideoLayout,
        metadata_layout: ValidatedFrameMetadata,
    ) -> Result<VideoFrame> {
        let owned_layout = ValidatedVideoLayout::new_uncompressed(
            layout.pixel_format,
            layout.width,
            layout.height,
            None,
        )?;
        let mut data = Vec::with_capacity(layout.payload_len_bytes);
        // SAFETY: The caller retains the source allocation through this copy.
        // Only active rows are initialized by the SDK; never read stride padding.
        if layout.is_contiguous() {
            data.extend_from_slice(unsafe {
                slice::from_raw_parts(c_frame.p_data, layout.payload_len_bytes)
            });
        } else {
            for plane_layout in layout.planes() {
                let plane = unsafe { VideoPlane::new(c_frame.p_data, *plane_layout) };
                for row in plane.rows() {
                    data.extend_from_slice(row);
                }
            }
        }
        let layout = owned_layout;

        let metadata =
            unsafe { FrameMetadata::copy_from_raw_validated(c_frame.p_metadata, metadata_layout) };

        #[allow(clippy::unnecessary_cast)] // Required for Windows where frame_format_type is i32
        let scan_type = ScanType::try_from(c_frame.frame_format_type as u32).map_err(|_| {
            Error::InvalidFrame(format!(
                "Unknown scan type: 0x{:08X}",
                c_frame.frame_format_type
            ))
        })?;

        Ok(VideoFrame {
            layout,
            frame_rate_n: c_frame.frame_rate_N,
            frame_rate_d: c_frame.frame_rate_D,
            picture_aspect_ratio: c_frame.picture_aspect_ratio,
            scan_type,
            timecode: c_frame.timecode,
            data,
            metadata,
            timestamp: c_frame.timestamp,
        })
    }

    /// Create a builder for configuring a video frame
    pub fn builder() -> VideoFrameBuilder {
        VideoFrameBuilder::new()
    }
}

/// Builder for configuring a VideoFrame with ergonomic method chaining
#[derive(Debug, Clone)]
pub struct VideoFrameBuilder {
    width: Option<i32>,
    height: Option<i32>,
    pixel_format: Option<PixelFormat>,
    frame_rate_n: Option<i32>,
    frame_rate_d: Option<i32>,
    picture_aspect_ratio: Option<f32>,
    scan_type: Option<ScanType>,
    timecode: Option<i64>,
    metadata: Option<String>,
    timestamp: Option<i64>,
    data: Option<Vec<u8>>,
}

impl VideoFrameBuilder {
    /// Create a new builder with no fields set
    pub fn new() -> Self {
        Self {
            width: None,
            height: None,
            pixel_format: None,
            frame_rate_n: None,
            frame_rate_d: None,
            picture_aspect_ratio: None,
            scan_type: None,
            timecode: None,
            metadata: None,
            timestamp: None,
            data: None,
        }
    }

    /// Set the video resolution. Width must be positive and even; height must
    /// be positive (and even for 4:2:0 formats).
    #[must_use]
    pub fn resolution(mut self, width: i32, height: i32) -> Self {
        self.width = Some(width);
        self.height = Some(height);
        self
    }

    /// Set the pixel format
    #[must_use]
    pub fn pixel_format(mut self, pixel_format: PixelFormat) -> Self {
        self.pixel_format = Some(pixel_format);
        self
    }

    /// Set the frame rate as a fraction (e.g., 30000/1001 for 29.97fps)
    #[must_use]
    pub fn frame_rate(mut self, numerator: i32, denominator: i32) -> Self {
        self.frame_rate_n = Some(numerator);
        self.frame_rate_d = Some(denominator);
        self
    }

    /// Set the picture aspect ratio
    #[must_use]
    pub fn aspect_ratio(mut self, ratio: f32) -> Self {
        self.picture_aspect_ratio = Some(ratio);
        self
    }

    /// Set the scan type (progressive, interlaced, etc.)
    #[must_use]
    pub fn scan_type(mut self, scan_type: ScanType) -> Self {
        self.scan_type = Some(scan_type);
        self
    }

    /// Set the timecode in 100 ns units (or the SDK synthesis sentinel).
    #[must_use]
    pub fn timecode(mut self, tc: i64) -> Self {
        self.timecode = Some(tc);
        self
    }

    /// Set metadata
    #[must_use]
    pub fn metadata<S: Into<String>>(mut self, meta: S) -> Self {
        self.metadata = Some(meta.into());
        self
    }

    /// Set the timestamp field in 100 ns units. This field is filled by the SDK on receive.
    #[must_use]
    pub fn timestamp(mut self, ts: i64) -> Self {
        self.timestamp = Some(ts);
        self
    }

    /// Supply owned pixels without an intermediate zero-filled allocation.
    ///
    /// `build` requires exactly the validated layout size and retains this
    /// allocation unchanged. Use `data_mut` on the resulting frame for reuse.
    #[must_use]
    pub fn data(mut self, data: Vec<u8>) -> Self {
        self.data = Some(data);
        self
    }

    /// Build the video frame.
    ///
    /// Defaults to 1920x1080 BGRA, 60/1 fps, 16:9 picture aspect ratio,
    /// progressive scan, synthesized timecode, and zero-filled pixels.
    pub fn build(self) -> Result<VideoFrame> {
        let width = self.width.unwrap_or(1920);
        let height = self.height.unwrap_or(1080);
        let pixel_format = self.pixel_format.unwrap_or(PixelFormat::BGRA);
        let frame_rate_n = self.frame_rate_n.unwrap_or(60);
        let frame_rate_d = self.frame_rate_d.unwrap_or(1);
        let picture_aspect_ratio = self.picture_aspect_ratio.unwrap_or(16.0 / 9.0);
        let scan_type = self.scan_type.unwrap_or(ScanType::Progressive);

        validate_video_frame_metadata(frame_rate_n, frame_rate_d, picture_aspect_ratio)?;
        let layout = ValidatedVideoLayout::new_uncompressed(pixel_format, width, height, None)?;
        let metadata = self.metadata.map(FrameMetadata::new).transpose()?;
        let data = match self.data {
            Some(data) => {
                if data.len() != layout.data_len_bytes {
                    return Err(Error::InvalidFrame(format!(
                        "Video data length {}, expected {} bytes for validated layout",
                        data.len(),
                        layout.data_len_bytes
                    )));
                }
                data
            }
            None => vec![0u8; layout.data_len_bytes],
        };

        Ok(VideoFrame {
            layout,
            frame_rate_n,
            frame_rate_d,
            picture_aspect_ratio,
            scan_type,
            timecode: self.timecode.unwrap_or(NDIlib_send_timecode_synthesize),
            data,
            metadata,
            timestamp: self.timestamp.unwrap_or(0),
        })
    }
}

impl Default for VideoFrameBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl Drop for VideoFrame {
    fn drop(&mut self) {
        // With owned data, we don't need to free SDK pointers anymore
        // The Vec<u8> handles memory cleanup automatically
    }
}

/// Owned, tightly packed planar floating-point audio with a validated layout.
///
/// Channel samples are contiguous, with channels stored one after another.
/// Conversion from borrowed SDK audio omits inter-channel padding.
#[derive(Debug)]
pub struct AudioFrame {
    layout: ValidatedAudioLayout,
    timecode: i64,
    data: Vec<f32>,
    metadata: Option<FrameMetadata>,
    timestamp: i64,
}

impl AudioFrame {
    pub(crate) fn to_raw(&self) -> NDIlib_audio_frame_v3_t {
        NDIlib_audio_frame_v3_t {
            sample_rate: self.layout.sample_rate,
            no_channels: self.num_channels(),
            no_samples: self.num_samples(),
            timecode: self.timecode,
            FourCC: self.format().into(),
            p_data: self.data.as_ptr() as *mut f32 as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: self.layout.channel_stride_in_bytes,
            },
            p_metadata: self
                .metadata
                .as_ref()
                .map_or(ptr::null(), FrameMetadata::as_ptr),
            timestamp: self.timestamp,
        }
    }

    #[cfg(test)]
    /// # Safety
    /// `raw` must reference live SDK sample and metadata allocations with
    /// initialized active samples through this ownership copy.
    pub(crate) unsafe fn from_raw(raw: NDIlib_audio_frame_v3_t) -> Result<AudioFrame> {
        // Use the shared validation helper to validate and compute layout
        let layout = validate_audio_layout(&raw)?;
        let metadata_layout = unsafe { validate_frame_metadata(raw.p_metadata)? };

        unsafe { Self::from_raw_validated(raw, layout, metadata_layout) }
    }

    /// # Safety
    /// `layout` must have been validated from this exact `raw` descriptor.
    /// Its active samples must remain live, aligned, and initialized through
    /// copying; `metadata_layout` must describe its live metadata pointer.
    pub(crate) unsafe fn from_raw_validated(
        raw: NDIlib_audio_frame_v3_t,
        layout: ValidatedAudioLayout,
        metadata_layout: ValidatedFrameMetadata,
    ) -> Result<AudioFrame> {
        if layout.is_empty() {
            return Err(Error::InvalidFrame(
                "Cannot create owned AudioFrame from an empty audio layout".into(),
            ));
        }

        // Only channel samples are initialized audio. Never form a typed slice
        // over inter-channel padding supplied by the SDK.
        let packed_layout = validate_outbound_audio_layout(
            layout.sample_rate,
            layout.no_channels as i32,
            layout.no_samples as i32,
            layout.format().expect("non-empty audio has a format"),
        )?;
        let mut data = Vec::with_capacity(packed_layout.sample_count);
        for channel in 0..layout.no_channels {
            let range = layout.channel_range(channel).expect("validated channel");
            // SAFETY: the SDK owns an aligned FLTP buffer with no_samples
            // initialized floats at each validated channel offset.
            let samples = unsafe {
                slice::from_raw_parts(raw.p_data.cast::<f32>().add(range.start), layout.no_samples)
            };
            data.extend_from_slice(samples);
        }

        // Copy the string, don't take ownership - SDK will free the original.
        let metadata =
            unsafe { FrameMetadata::copy_from_raw_validated(raw.p_metadata, metadata_layout) };

        Ok(AudioFrame {
            layout: packed_layout,
            timecode: raw.timecode,
            data,
            metadata,
            timestamp: raw.timestamp,
        })
    }

    /// Create a builder for configuring an audio frame
    pub fn builder() -> AudioFrameBuilder {
        AudioFrameBuilder::new()
    }

    /// Get the sample rate in Hz.
    pub fn sample_rate(&self) -> i32 {
        self.layout.sample_rate
    }

    /// Get the number of audio channels.
    pub fn num_channels(&self) -> i32 {
        self.layout.no_channels as i32
    }

    /// Get the number of samples per channel.
    pub fn num_samples(&self) -> i32 {
        self.layout.no_samples as i32
    }

    /// Get the timecode in 100 ns units.
    ///
    /// Defaults to the SDK's synthesized-timecode sentinel. An explicit zero
    /// is passed through as a literal timecode.
    pub fn timecode(&self) -> i64 {
        self.timecode
    }

    /// Get the receive timestamp in 100 ns units since the Unix epoch.
    ///
    /// On receive the SDK supplies this value, or its undefined-timestamp
    /// sentinel when unavailable. Outbound values are passed through unchanged;
    /// the SDK defines this field for receiving.
    pub fn timestamp(&self) -> i64 {
        self.timestamp
    }

    /// Get the audio format.
    pub fn format(&self) -> AudioFormat {
        self.layout
            .format()
            .expect("owned AudioFrame always has a concrete audio format")
    }

    /// Get the channel stride in bytes.
    pub fn channel_stride_in_bytes(&self) -> i32 {
        self.layout.channel_stride_in_bytes
    }

    /// Get tightly packed planar audio as 32-bit floats.
    /// Each channel's samples are contiguous; channels follow one another.
    pub fn data(&self) -> &[f32] {
        &self.data
    }

    /// Get mutable audio sample data without changing the validated layout.
    pub fn data_mut(&mut self) -> &mut [f32] {
        &mut self.data
    }

    /// Replace the owned audio data while preserving the validated layout.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidFrame`] if `data` is not exactly the validated
    /// sample count.
    pub fn replace_data(&mut self, data: Vec<f32>) -> Result<()> {
        if data.len() != self.layout.sample_count {
            return Err(Error::InvalidFrame(format!(
                "Audio data length {}, expected {} samples for validated layout",
                data.len(),
                self.layout.sample_count
            )));
        }

        self.data = data;
        Ok(())
    }

    /// Get frame metadata as UTF-8 text, if present.
    pub fn metadata(&self) -> Option<&str> {
        self.metadata.as_ref().map(FrameMetadata::as_str)
    }

    /// Replace frame metadata.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCString`] if `metadata` contains an interior NUL
    /// byte, or [`Error::InvalidFrame`] if the emitted C string would exceed
    /// the metadata size cap.
    pub fn set_metadata<S: Into<String>>(&mut self, metadata: Option<S>) -> Result<()> {
        self.metadata = metadata.map(FrameMetadata::new).transpose()?;
        Ok(())
    }

    /// Get audio data for a specific channel
    ///
    /// Data is always stored in planar format internally. If `AudioLayout::Interleaved`
    /// was specified at build time, the data was converted to planar during construction.
    pub fn channel_data(&self, channel: usize) -> Option<&[f32]> {
        let range = self.layout.channel_range(channel)?;
        Some(&self.data[range])
    }

    /// Get mutable samples for one channel without allocating.
    pub fn channel_data_mut(&mut self, channel: usize) -> Option<&mut [f32]> {
        let range = self.layout.channel_range(channel)?;
        Some(&mut self.data[range])
    }
}

/// Builder for configuring an AudioFrame with ergonomic method chaining
#[derive(Debug, Clone)]
pub struct AudioFrameBuilder {
    sample_rate: Option<i32>,
    num_channels: Option<i32>,
    num_samples: Option<i32>,
    timecode: Option<i64>,
    format: Option<AudioFormat>,
    data: Option<Vec<f32>>,
    layout: Option<AudioLayout>,
    metadata: Option<String>,
    timestamp: Option<i64>,
}

impl AudioFrameBuilder {
    /// Create a new builder with no fields set
    pub fn new() -> Self {
        Self {
            sample_rate: None,
            num_channels: None,
            num_samples: None,
            timecode: None,
            format: None,
            data: None,
            layout: None,
            metadata: None,
            timestamp: None,
        }
    }

    /// Set the sample rate
    #[must_use]
    pub fn sample_rate(mut self, rate: i32) -> Self {
        self.sample_rate = Some(rate);
        self
    }

    /// Set the number of audio channels
    #[must_use]
    pub fn channels(mut self, channels: i32) -> Self {
        self.num_channels = Some(channels);
        self
    }

    /// Set the number of samples
    #[must_use]
    pub fn samples(mut self, samples: i32) -> Self {
        self.num_samples = Some(samples);
        self
    }

    /// Set the timecode in 100 ns units (or the SDK synthesis sentinel).
    #[must_use]
    pub fn timecode(mut self, tc: i64) -> Self {
        self.timecode = Some(tc);
        self
    }

    /// Set the audio format
    #[must_use]
    pub fn format(mut self, format: AudioFormat) -> Self {
        self.format = Some(format);
        self
    }

    /// Set the audio data layout (planar or interleaved)
    ///
    /// - **Planar**: All samples for channel 0, then all for channel 1, etc.
    /// - **Interleaved**: Samples from all channels are interleaved.
    ///
    /// Defaults to `AudioLayout::Planar` which is the native format for FLTP.
    ///
    /// # Example
    /// ```
    /// use grafton_ndi::{AudioFrame, AudioLayout};
    ///
    /// // Planar layout (default)
    /// let frame = AudioFrame::builder()
    ///     .channels(2)
    ///     .samples(100)
    ///     .layout(AudioLayout::Planar)
    ///     .build()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn layout(mut self, layout: AudioLayout) -> Self {
        self.layout = Some(layout);
        self
    }

    /// Set the audio data as 32-bit floats
    ///
    /// The data length must equal `num_channels * num_samples`. The layout must match
    /// the configured `AudioLayout`:
    /// - **Planar**: `[C0S0, C0S1, ..., C1S0, C1S1, ...]`
    /// - **Interleaved**: `[C0S0, C1S0, C0S1, C1S1, ...]` (converted to planar at build time)
    #[must_use]
    pub fn data(mut self, data: Vec<f32>) -> Self {
        self.data = Some(data);
        self
    }

    /// Set metadata
    #[must_use]
    pub fn metadata<S: Into<String>>(mut self, meta: S) -> Self {
        self.metadata = Some(meta.into());
        self
    }

    /// Set the timestamp field in 100 ns units. This field is filled by the SDK on receive.
    #[must_use]
    pub fn timestamp(mut self, ts: i64) -> Self {
        self.timestamp = Some(ts);
        self
    }

    /// Build the audio frame.
    ///
    /// Defaults to 48 kHz stereo FLTP, 1024 samples per channel, planar input,
    /// synthesized timecode, and silent samples.
    ///
    /// When `AudioLayout::Interleaved` is set, the input data is converted to planar
    /// format in Rust. The resulting frame always stores
    /// planar data with `channel_stride_in_bytes = num_samples * 4`.
    pub fn build(self) -> Result<AudioFrame> {
        let sample_rate = self.sample_rate.unwrap_or(48000);
        let num_channels = self.num_channels.unwrap_or(2);
        let num_samples = self.num_samples.unwrap_or(1024);
        let format = self.format.unwrap_or(AudioFormat::FLTP);
        let layout = self.layout.unwrap_or(AudioLayout::Planar);
        let timecode = self.timecode.unwrap_or(NDIlib_send_timecode_synthesize);
        let audio_layout =
            validate_outbound_audio_layout(sample_rate, num_channels, num_samples, format)?;
        let sample_count = audio_layout.sample_count;

        let data = if let Some(input_data) = self.data {
            if input_data.len() != sample_count {
                return Err(Error::InvalidFrame(format!(
                    "Audio data length {}, expected {} ({}ch x {}samples)",
                    input_data.len(),
                    sample_count,
                    num_channels,
                    num_samples
                )));
            }

            match layout {
                AudioLayout::Planar => input_data,
                AudioLayout::Interleaved => {
                    let nc = audio_layout.no_channels;
                    let ns = audio_layout.no_samples;
                    let mut planar = vec![0.0f32; sample_count];
                    for ch in 0..nc {
                        for s in 0..ns {
                            let dst = ch
                                .checked_mul(ns)
                                .and_then(|idx| idx.checked_add(s))
                                .ok_or_else(|| {
                                    Error::InvalidFrame(
                                        "Audio planar conversion index overflow".into(),
                                    )
                                })?;
                            let src = s
                                .checked_mul(nc)
                                .and_then(|idx| idx.checked_add(ch))
                                .ok_or_else(|| {
                                    Error::InvalidFrame(
                                        "Audio interleaved conversion index overflow".into(),
                                    )
                                })?;
                            planar[dst] = input_data[src];
                        }
                    }
                    planar
                }
            }
        } else {
            vec![0.0f32; sample_count]
        };

        let metadata = self.metadata.map(FrameMetadata::new).transpose()?;

        Ok(AudioFrame {
            layout: audio_layout,
            timecode,
            data,
            metadata,
            timestamp: self.timestamp.unwrap_or(0),
        })
    }
}

impl Default for AudioFrameBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl Default for AudioFrame {
    fn default() -> Self {
        AudioFrame::builder()
            .build()
            .expect("Default AudioFrame should always succeed")
    }
}

impl Drop for AudioFrame {
    fn drop(&mut self) {
        // With owned data, we don't need to free SDK pointers anymore
        // The Vec<f32> handles memory cleanup automatically
    }
}

/// Audio format identifiers (FourCC codes).
///
/// Currently NDI primarily uses `FLTP` (32-bit floating point planar format).
///
/// This enum is marked `#[non_exhaustive]` to allow future NDI SDK versions to add new audio formats
/// without breaking existing code. Always use a wildcard pattern when matching.
///
/// # Examples
///
/// ```
/// use grafton_ndi::AudioFormat;
///
/// let format = AudioFormat::FLTP;
///
/// // When matching, always include a wildcard for forward compatibility
/// match format {
///     AudioFormat::FLTP => println!("32-bit float planar"),
///     _ => println!("Other format"),
/// }
/// ```
#[derive(Debug, TryFromPrimitive, IntoPrimitive, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
#[repr(u32)]
pub enum AudioFormat {
    /// 32-bit floating point planar audio (FLTP).
    FLTP = NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP as _,
}

/// Audio data layout format
///
/// Determines how multi-channel audio samples are arranged in memory.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AudioLayout {
    /// Planar format: All samples for channel 0, then all for channel 1, etc.
    ///
    /// Memory layout for 2 channels, 3 samples:
    /// `[C0S0, C0S1, C0S2, C1S0, C1S1, C1S2]`
    ///
    /// This is the native format for FLTP and is efficient for per-channel processing.
    Planar,

    /// Interleaved format: Samples from all channels are interleaved.
    ///
    /// Input memory layout for 2 channels, 3 samples:
    /// `[C0S0, C1S0, C0S1, C1S1, C0S2, C1S2]`
    ///
    /// Interleaved data is converted to planar format in Rust at build time,
    /// so the resulting `AudioFrame` always stores planar data.
    Interleaved,
}

impl From<AudioFormat> for i32 {
    fn from(value: AudioFormat) -> Self {
        let u32_value: u32 = value.into();
        u32_value as i32
    }
}

/// Maximum allowed size for supported video frame data (256 MiB).
const MAX_VIDEO_BYTES: usize = 256 * 1024 * 1024;

/// Maximum allowed size for audio frame data (64 MiB).
/// Comfortably above typical NDI audio frames while preventing unbounded allocations.
const MAX_AUDIO_BYTES: usize = 64 * 1024 * 1024;

/// Maximum allowed size for SDK metadata C strings (4 MiB), including the
/// trailing NUL terminator.
pub(crate) const MAX_METADATA_BYTES: usize = 4 * 1024 * 1024;

/// Owned UTF-8 metadata text and its timecode.
///
/// NDI expects XML when sending; callers are responsible for XML syntax. Text
/// cannot contain NUL bytes and is limited to 4 MiB including the SDK terminator.
#[derive(Debug, Clone)]
pub struct MetadataFrame {
    data: FrameMetadata,
    timecode: i64,
}

impl MetadataFrame {
    /// Create an empty metadata frame with default SDK timecode behavior.
    pub fn new() -> Self {
        MetadataFrame {
            data: FrameMetadata::new("").expect("empty metadata is valid"),
            timecode: NDIlib_send_timecode_synthesize,
        }
    }

    /// Create a metadata frame from UTF-8 text and a timecode.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCString`] if `data` contains an interior NUL byte
    /// or [`Error::InvalidFrame`] if the SDK metadata length would exceed the
    /// crate's metadata size limit.
    pub fn with_data(data: impl Into<String>, timecode: i64) -> Result<Self> {
        let data = FrameMetadata::new(data)?;
        Ok(MetadataFrame { data, timecode })
    }

    /// Get the metadata text.
    pub fn data(&self) -> &str {
        self.data.as_str()
    }

    /// Consume the frame and return the owned metadata text.
    pub fn into_data(self) -> String {
        self.data.into_string()
    }

    /// Get the timecode in 100 ns units.
    ///
    /// Defaults to the SDK's synthesized-timecode sentinel. An explicit zero
    /// is passed through as a literal timecode.
    pub fn timecode(&self) -> i64 {
        self.timecode
    }

    /// Replace the metadata text.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCString`] if `data` contains an interior NUL byte
    /// or [`Error::InvalidFrame`] if the SDK metadata length would exceed the
    /// crate's metadata size limit.
    pub fn set_data(&mut self, data: impl Into<String>) -> Result<()> {
        self.data = FrameMetadata::new(data)?;
        Ok(())
    }

    /// Set the timecode.
    pub fn set_timecode(&mut self, timecode: i64) {
        self.timecode = timecode;
    }

    /// Return this frame with an updated timecode.
    pub fn with_timecode(mut self, timecode: i64) -> Self {
        self.timecode = timecode;
        self
    }

    /// Borrow the retained C string for a synchronous SDK call. The caller
    /// must keep this frame alive until the SDK call returns.
    pub(crate) fn to_raw(&self) -> NDIlib_metadata_frame_t {
        NDIlib_metadata_frame_t {
            length: self.data.inner.as_bytes_with_nul().len() as i32,
            timecode: self.timecode,
            p_data: self.data.as_ptr() as *mut c_char,
        }
    }

    /// Create from raw NDI metadata frame (copies the data)
    ///
    /// # Safety
    ///
    /// `raw` must be an SDK-populated metadata frame whose `p_data` pointer is
    /// valid for `raw.length` bytes when `length > 0`. For zero length with a
    /// non-null pointer, it must be readable through its first NUL terminator
    /// or the crate's metadata cap, as required by `validate_frame_metadata`.
    #[cfg(test)]
    pub(crate) unsafe fn from_raw(raw: &NDIlib_metadata_frame_t) -> Result<Self> {
        let layout = unsafe { validate_metadata_layout(raw)? };
        Ok(unsafe { Self::from_raw_validated(raw, layout) })
    }

    /// Create from a raw NDI metadata frame after its layout has been validated.
    ///
    /// # Safety
    ///
    /// `layout` must have been produced by `validate_metadata_layout(raw)` while
    /// the same `raw.p_data` allocation is still valid.
    pub(crate) unsafe fn from_raw_validated(
        raw: &NDIlib_metadata_frame_t,
        layout: ValidatedMetadataLayout,
    ) -> Self {
        let data = if layout.len_with_nul == 0 {
            FrameMetadata::new("").expect("empty metadata is valid")
        } else {
            unsafe {
                FrameMetadata::copy_from_raw_validated(
                    raw.p_data,
                    ValidatedFrameMetadata {
                        len_with_nul: std::num::NonZeroUsize::new(layout.len_with_nul),
                        text_len: layout.text_len,
                    },
                )
                .expect("non-null metadata")
            }
        };

        Self {
            data,
            timecode: raw.timecode,
        }
    }
}

impl Default for MetadataFrame {
    fn default() -> Self {
        Self::new()
    }
}

/// Validated standalone metadata frame layout information.
///
/// The SDK `length` field includes the trailing NUL terminator. A
/// `len_with_nul` of zero represents the accepted empty null frame
/// (`length == 0 && p_data == NULL`) and never requires reading from `p_data`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct ValidatedMetadataLayout {
    /// Total SDK metadata length including trailing NUL, or zero for the valid
    /// empty null frame.
    pub len_with_nul: usize,
    /// Public UTF-8 text payload length excluding the trailing NUL.
    pub text_len: usize,
}

/// Validate standalone metadata frame layout from raw FFI fields.
///
/// This validates only memory layout and UTF-8. XML well-formedness is
/// intentionally not checked because NDI receivers are expected to tolerate
/// badly formed XML metadata.
/// # Safety
/// `raw.p_data`, when non-null, must reference readable storage for the
/// declared length or a NUL-terminated string within the metadata cap.
pub(crate) unsafe fn validate_metadata_layout(
    raw: &NDIlib_metadata_frame_t,
) -> Result<ValidatedMetadataLayout> {
    if raw.length < 0 {
        return Err(Error::InvalidFrame(format!(
            "Metadata frame has negative length: {}",
            raw.length
        )));
    }

    if raw.length == 0 {
        if raw.p_data.is_null() {
            return Ok(ValidatedMetadataLayout {
                len_with_nul: 0,
                text_len: 0,
            });
        }

        // The SDK permits zero length as a C-string sentinel. Apply the same
        // bounded scan and SDK pointer-validity contract as per-frame metadata.
        let metadata = unsafe { validate_frame_metadata(raw.p_data)? };
        return Ok(ValidatedMetadataLayout {
            len_with_nul: metadata.len_with_nul.expect("non-null metadata").get(),
            text_len: metadata.text_len,
        });
    }

    if raw.p_data.is_null() {
        return Err(Error::InvalidFrame(
            "Metadata frame has non-zero length with null data pointer".into(),
        ));
    }

    let len_with_nul = usize::try_from(raw.length).map_err(|_| {
        Error::InvalidFrame(format!("Invalid metadata length value: {}", raw.length))
    })?;
    validate_metadata_len_with_nul(len_with_nul)?;

    let bytes = unsafe { slice::from_raw_parts(raw.p_data.cast::<u8>(), len_with_nul) };
    if bytes[len_with_nul - 1] != 0 {
        return Err(Error::InvalidFrame(
            "Metadata frame length does not include a trailing NUL terminator".into(),
        ));
    }

    let payload = &bytes[..len_with_nul - 1];
    if payload.contains(&0) {
        return Err(Error::InvalidFrame(
            "Metadata frame contains an interior NUL byte".into(),
        ));
    }

    str::from_utf8(payload).map_err(|err| Error::InvalidUtf8(err.to_string()))?;

    Ok(ValidatedMetadataLayout {
        len_with_nul,
        text_len: payload.len(),
    })
}

fn validate_metadata_len_with_nul(len_with_nul: usize) -> Result<i32> {
    if len_with_nul == 0 {
        return Err(Error::InvalidFrame(
            "Metadata length must include a trailing NUL terminator".into(),
        ));
    }

    if len_with_nul > MAX_METADATA_BYTES {
        return Err(Error::InvalidFrame(format!(
            "Metadata exceeds maximum size: {} bytes > {} bytes",
            len_with_nul, MAX_METADATA_BYTES
        )));
    }

    metadata_len_to_i32(len_with_nul)
}

fn metadata_len_to_i32(len_with_nul: usize) -> Result<i32> {
    i32::try_from(len_with_nul).map_err(|_| {
        Error::InvalidFrame(format!(
            "Metadata length {len_with_nul} exceeds SDK i32 range"
        ))
    })
}

/// # Safety
/// `layout` must describe this exact live `raw.p_data` allocation, which must
/// remain immutable for the returned borrow.
unsafe fn metadata_payload_bytes(
    raw: &NDIlib_metadata_frame_t,
    layout: ValidatedMetadataLayout,
) -> &[u8] {
    if layout.text_len == 0 {
        &[]
    } else {
        // SAFETY: `validate_metadata_layout` checked that `p_data` is non-null
        // for non-empty payloads and that `text_len` is bounded by `length`.
        unsafe { slice::from_raw_parts(raw.p_data.cast::<u8>(), layout.text_len) }
    }
}

/// Owned video/audio per-frame metadata.
///
/// The wrapped C string is guaranteed to be valid UTF-8, contain no interior
/// NUL bytes, and fit within the crate metadata size cap including its trailing
/// terminator. `None` on a frame means a null SDK `p_metadata`; `Some("")`
/// means an explicit non-null empty C string.
#[derive(Clone, PartialEq, Eq)]
pub(crate) struct FrameMetadata {
    inner: CString,
}

impl FrameMetadata {
    pub(crate) fn new<S: Into<String>>(metadata: S) -> Result<Self> {
        let metadata = metadata.into();
        let len_with_nul = metadata.len().checked_add(1).ok_or_else(|| {
            Error::InvalidFrame("Frame metadata length overflow while adding terminator".into())
        })?;
        validate_metadata_len_with_nul(len_with_nul)?;

        Ok(Self {
            inner: CString::new(metadata).map_err(Error::InvalidCString)?,
        })
    }

    pub(crate) fn as_str(&self) -> &str {
        // SAFETY: construction accepts String and validated SDK UTF-8 only.
        unsafe { str::from_utf8_unchecked(self.inner.as_bytes()) }
    }

    pub(crate) fn into_string(self) -> String {
        self.inner
            .into_string()
            .expect("FrameMetadata validates UTF-8 at construction")
    }

    pub(crate) fn as_cstr(&self) -> &CStr {
        self.inner.as_c_str()
    }

    pub(crate) fn as_ptr(&self) -> *const c_char {
        self.inner.as_ptr()
    }

    /// Copy per-frame metadata from a pointer that has already been validated
    /// with [`validate_frame_metadata`].
    ///
    /// # Safety
    ///
    /// `metadata_layout` must have been produced for this exact `p_metadata`
    /// pointer while the pointed-to SDK allocation is still valid.
    pub(crate) unsafe fn copy_from_raw_validated(
        p_metadata: *const c_char,
        metadata_layout: ValidatedFrameMetadata,
    ) -> Option<Self> {
        metadata_layout.len_with_nul?;
        debug_assert!(!p_metadata.is_null());

        let mut bytes = Vec::with_capacity(metadata_layout.text_len + 1);
        if metadata_layout.text_len != 0 {
            bytes.extend_from_slice(unsafe {
                slice::from_raw_parts(p_metadata.cast::<u8>(), metadata_layout.text_len)
            });
        }
        bytes.push(0);

        let inner = unsafe { CString::from_vec_with_nul_unchecked(bytes) };
        Some(Self { inner })
    }
}

impl fmt::Debug for FrameMetadata {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("FrameMetadata")
            .field(&self.as_str())
            .finish()
    }
}

/// Cached layout for video/audio per-frame `p_metadata`.
///
/// The SDK exposes these pointers as optional lengthless C strings. This type
/// records the first terminator found by a bounded scan so later accessors can
/// expose UTF-8 text without rescanning.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct ValidatedFrameMetadata {
    /// `None` means the SDK pointer was null. `Some` includes the first trailing
    /// NUL terminator found within `MAX_METADATA_BYTES`.
    pub(crate) len_with_nul: Option<NonZeroUsize>,
    /// UTF-8 text payload length excluding the trailing NUL terminator.
    pub(crate) text_len: usize,
}

impl ValidatedFrameMetadata {
    /// Bounded application CStr validation uses the known slice length, never a raw scan.
    pub(crate) fn from_cstr(metadata: Option<&CStr>) -> Result<Self> {
        let Some(metadata) = metadata else {
            return Ok(Self {
                len_with_nul: None,
                text_len: 0,
            });
        };
        let len = metadata.to_bytes_with_nul().len();
        validate_metadata_len_with_nul(len)?;
        metadata
            .to_str()
            .map_err(|e| Error::InvalidUtf8(e.to_string()))?;
        Ok(Self {
            len_with_nul: NonZeroUsize::new(len),
            text_len: len - 1,
        })
    }
}

/// Validate a video/audio per-frame `p_metadata` pointer with a bounded scan.
///
/// This continues to trust the NDI SDK that a non-null pointer is readable. The
/// validation does not make dangling or otherwise invalid pointers safe; it
/// only limits the scan to `MAX_METADATA_BYTES`, requires a terminator within
/// that cap, and validates UTF-8 before exposing safe text access.
///
/// # Safety
///
/// When non-null, `p_metadata` must be readable byte-by-byte until either the
/// first NUL terminator or `MAX_METADATA_BYTES` bytes have been read.
pub(crate) unsafe fn validate_frame_metadata(
    p_metadata: *const c_char,
) -> Result<ValidatedFrameMetadata> {
    if p_metadata.is_null() {
        return Ok(ValidatedFrameMetadata {
            len_with_nul: None,
            text_len: 0,
        });
    }

    let metadata = p_metadata.cast::<u8>();
    for text_len in 0..MAX_METADATA_BYTES {
        let byte = unsafe { metadata.add(text_len).read() };
        if byte == 0 {
            if text_len > 0 {
                let payload = unsafe { slice::from_raw_parts(metadata, text_len) };
                str::from_utf8(payload).map_err(|err| Error::InvalidUtf8(err.to_string()))?;
            }

            return Ok(ValidatedFrameMetadata {
                len_with_nul: NonZeroUsize::new(text_len + 1),
                text_len,
            });
        }
    }

    Err(Error::InvalidFrame(format!(
        "Frame metadata is missing a NUL terminator within {MAX_METADATA_BYTES} bytes"
    )))
}

/// Expose validated per-frame metadata as borrowed UTF-8 text.
///
/// # Safety
///
/// `metadata_layout` must have been produced for this exact `p_metadata`
/// pointer while the pointed-to SDK allocation is still valid.
pub(crate) unsafe fn frame_metadata_str<'a>(
    p_metadata: *const c_char,
    metadata_layout: ValidatedFrameMetadata,
) -> Option<&'a str> {
    metadata_layout.len_with_nul?;
    debug_assert!(!p_metadata.is_null());

    if metadata_layout.text_len == 0 {
        return Some("");
    }

    let bytes = unsafe { slice::from_raw_parts(p_metadata.cast::<u8>(), metadata_layout.text_len) };
    Some(unsafe { str::from_utf8_unchecked(bytes) })
}

/// Image format specification for encoding video frames.
///
/// Used with [`VideoFrame::encode_data_url`] to specify the desired output format.
///
/// # Examples
///
/// ```
/// use grafton_ndi::ImageFormat;
///
/// // PNG format (lossless)
/// let png = ImageFormat::Png;
///
/// // JPEG with quality 85 (lossy, smaller file size)
/// let jpeg = ImageFormat::Jpeg(85);
/// ```
///
/// This enum is marked `#[non_exhaustive]` so that additional encoders can be
/// added without a breaking change. Match arms should include a wildcard `_`
/// pattern.
#[cfg(feature = "image-encoding")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ImageFormat {
    /// PNG format (lossless compression)
    Png,
    /// JPEG format with quality setting (1-100, where 100 is highest quality)
    Jpeg(u8),
}

#[cfg(feature = "image-encoding")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ImageChannelOrder {
    Rgba,
    Bgra,
}

#[cfg(feature = "image-encoding")]
impl ImageChannelOrder {
    fn red_index(self) -> usize {
        match self {
            Self::Rgba => 0,
            Self::Bgra => 2,
        }
    }

    fn blue_index(self) -> usize {
        match self {
            Self::Rgba => 2,
            Self::Bgra => 0,
        }
    }
}

#[cfg(feature = "image-encoding")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ImageAlphaPolicy {
    Preserve,
    Opaque,
}

#[cfg(feature = "image-encoding")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct ImagePixelFormat {
    channel_order: ImageChannelOrder,
    alpha_policy: ImageAlphaPolicy,
}

#[cfg(feature = "image-encoding")]
impl ImagePixelFormat {
    const BYTES_PER_PIXEL: usize = 4;

    fn from_pixel_format(pixel_format: PixelFormat) -> Result<Self> {
        match pixel_format {
            PixelFormat::RGBA => Ok(Self {
                channel_order: ImageChannelOrder::Rgba,
                alpha_policy: ImageAlphaPolicy::Preserve,
            }),
            PixelFormat::BGRA => Ok(Self {
                channel_order: ImageChannelOrder::Bgra,
                alpha_policy: ImageAlphaPolicy::Preserve,
            }),
            PixelFormat::RGBX => Ok(Self {
                channel_order: ImageChannelOrder::Rgba,
                alpha_policy: ImageAlphaPolicy::Opaque,
            }),
            PixelFormat::BGRX => Ok(Self {
                channel_order: ImageChannelOrder::Bgra,
                alpha_policy: ImageAlphaPolicy::Opaque,
            }),
            _ => Err(Error::InvalidFrame(format!(
                "Unsupported format for image encoding: {pixel_format:?}. Only RGBA/RGBX/BGRA/BGRX are supported."
            ))),
        }
    }

    fn can_borrow_png_rows(self) -> bool {
        self.channel_order == ImageChannelOrder::Rgba
            && self.alpha_policy == ImageAlphaPolicy::Preserve
    }

    fn rgba_pixel(self, pixel: &[u8]) -> [u8; 4] {
        [
            pixel[self.channel_order.red_index()],
            pixel[1],
            pixel[self.channel_order.blue_index()],
            match self.alpha_policy {
                ImageAlphaPolicy::Preserve => pixel[3],
                ImageAlphaPolicy::Opaque => 255,
            },
        ]
    }

    fn rgb_pixel(self, pixel: &[u8]) -> [u8; 3] {
        [
            pixel[self.channel_order.red_index()],
            pixel[1],
            pixel[self.channel_order.blue_index()],
        ]
    }
}

#[cfg(feature = "image-encoding")]
#[derive(Debug)]
struct ImagePixelSource<'a> {
    plane: VideoPlane<'a>,
    width: usize,
    height: usize,
    pixel_format: ImagePixelFormat,
}

#[cfg(feature = "image-encoding")]
impl<'a> ImagePixelSource<'a> {
    fn encode_png(&self) -> Result<Vec<u8>> {
        use png::{BitDepth, ColorType, Encoder};

        use std::io::Write;

        let width = u32::try_from(self.width).map_err(|_| {
            Error::InvalidFrame(format!("PNG width {} exceeds u32 range", self.width))
        })?;
        let height = u32::try_from(self.height).map_err(|_| {
            Error::InvalidFrame(format!("PNG height {} exceeds u32 range", self.height))
        })?;
        let mut conversion = self.png_conversion_row()?;

        // Encode to PNG
        let mut png_data = Vec::new();
        let mut encoder = Encoder::new(&mut png_data, width, height);
        encoder.set_color(ColorType::Rgba);
        encoder.set_depth(BitDepth::Eight);

        let png_error = |e| Error::InvalidFrame(format!("PNG encoding failed: {e}"));
        let mut writer = encoder.write_header().map_err(png_error)?;
        {
            let mut stream = writer.stream_writer().map_err(png_error)?;
            for row in self.plane.rows() {
                let rgba = if self.pixel_format.can_borrow_png_rows() {
                    row
                } else {
                    for (out, pixel) in conversion
                        .as_chunks_mut::<4>()
                        .0
                        .iter_mut()
                        .zip(row.as_chunks::<{ ImagePixelFormat::BYTES_PER_PIXEL }>().0)
                    {
                        *out = self.pixel_format.rgba_pixel(pixel);
                    }
                    &conversion
                };
                stream
                    .write_all(rgba)
                    .map_err(|e| Error::InvalidFrame(format!("PNG encoding failed: {e}")))?;
            }
            stream.finish().map_err(png_error)?;
        }
        writer.finish().map_err(png_error)?;

        Ok(png_data)
    }

    fn encode_jpeg(&self, quality: u8) -> Result<Vec<u8>> {
        use jpeg_encoder::Encoder as JpegEncoder;

        let (width, height) = self.jpeg_dimensions(quality)?;

        // Encode to JPEG
        let mut jpeg_data = Vec::new();
        let encoder = JpegEncoder::new(&mut jpeg_data, quality);
        encoder
            .encode_image(JpegRows {
                source: self,
                width,
                height,
            })
            .map_err(|e| Error::InvalidFrame(format!("JPEG encoding failed: {e}")))?;

        Ok(jpeg_data)
    }

    fn encode_data_url(&self, format: ImageFormat) -> Result<String> {
        use base64::{engine::general_purpose::STANDARD, Engine};

        let (mime_type, image_bytes) = match format {
            ImageFormat::Png => ("image/png", self.encode_png()?),
            ImageFormat::Jpeg(quality) => ("image/jpeg", self.encode_jpeg(quality)?),
        };

        let base64_data = STANDARD.encode(&image_bytes);
        Ok(format!("data:{mime_type};base64,{base64_data}"))
    }

    fn new(layout: ValidatedVideoLayout, data: &'a [u8]) -> Result<Self> {
        if data.len() != layout.data_len_bytes {
            return Err(Error::InvalidFrame(format!(
                "Video data length {}, expected {} bytes for validated layout",
                data.len(),
                layout.data_len_bytes
            )));
        }

        // SAFETY: The owned slice covers the validated storage extent and
        // remains borrowed for 'a. Active rows are a subset of that slice.
        let plane = unsafe { VideoPlane::new(data.as_ptr(), layout.plane_layouts[0]) };
        Self::from_plane(layout, plane)
    }

    fn from_plane(layout: ValidatedVideoLayout, plane: VideoPlane<'a>) -> Result<Self> {
        let pixel_format = ImagePixelFormat::from_pixel_format(layout.pixel_format)?;
        Ok(Self {
            plane,
            width: layout.width as usize,
            height: layout.height as usize,
            pixel_format,
        })
    }

    fn png_conversion_row(&self) -> Result<Vec<u8>> {
        if self.pixel_format.can_borrow_png_rows() {
            return Ok(Vec::new());
        }
        let len = self.width.checked_mul(4).ok_or_else(|| {
            Error::InvalidFrame(format!("PNG row size overflow: {}x4", self.width))
        })?;
        Ok(vec![0; len])
    }

    fn jpeg_dimensions(&self, quality: u8) -> Result<(u16, u16)> {
        if !(1..=100).contains(&quality) {
            return Err(Error::InvalidFrame(format!(
                "JPEG quality must be in 1..=100, got {quality}"
            )));
        }

        let width = u16::try_from(self.width).map_err(|_| {
            Error::InvalidFrame(format!(
                "JPEG width {} exceeds maximum supported value {}",
                self.width,
                u16::MAX
            ))
        })?;
        let height = u16::try_from(self.height).map_err(|_| {
            Error::InvalidFrame(format!(
                "JPEG height {} exceeds maximum supported value {}",
                self.height,
                u16::MAX
            ))
        })?;

        Ok((width, height))
    }
}

/// Reads validated active rows directly into the codec's component buffers.
/// No wrapper RGB staging allocation, including for padded captured frames.
#[cfg(feature = "image-encoding")]
struct JpegRows<'s, 'a> {
    source: &'s ImagePixelSource<'a>,
    width: u16,
    height: u16,
}

#[cfg(feature = "image-encoding")]
impl jpeg_encoder::ImageBuffer for JpegRows<'_, '_> {
    fn get_jpeg_color_type(&self) -> jpeg_encoder::JpegColorType {
        jpeg_encoder::JpegColorType::Ycbcr
    }

    fn width(&self) -> u16 {
        self.width
    }
    fn height(&self) -> u16 {
        self.height
    }

    fn fill_buffers(&self, row: u16, buffers: &mut [Vec<u8>; 4]) {
        let row = self
            .source
            .plane
            .row(usize::from(row))
            .expect("codec row is in bounds");
        // Like the codec's slice adapter, batch 16 pixels so LLVM can vectorize
        // conversion and append components without per-pixel Vec growth checks.
        for chunk in row.as_chunks::<64>().0 {
            let mut components = [[0; 16]; 3];
            for (i, pixel) in chunk.as_chunks::<4>().0.iter().enumerate() {
                let [r, g, b] = self.source.pixel_format.rgb_pixel(pixel);
                let (y, cb, cr) = jpeg_encoder::rgb_to_ycbcr(r, g, b);
                components[0][i] = y;
                components[1][i] = cb;
                components[2][i] = cr;
            }
            for (buffer, values) in buffers.iter_mut().zip(components) {
                buffer.extend_from_slice(&values);
            }
        }
        for pixel in row.as_chunks::<64>().1.as_chunks::<4>().0 {
            let [r, g, b] = self.source.pixel_format.rgb_pixel(pixel);
            let (y, cb, cr) = jpeg_encoder::rgb_to_ycbcr(r, g, b);
            buffers[0].push(y);
            buffers[1].push(cb);
            buffers[2].push(cr);
        }
    }
}

// ============================================================================
// Frame layout validation helpers
// ============================================================================

/// Validated video frame layout information.
///
/// This struct holds pre-validated layout information for a video frame,
/// including the computed buffer length and stride/size information.
/// Creating this struct performs all necessary bounds checking, so
/// consumers can safely use the cached values without re-validation.
#[derive(Debug, Clone, Copy)]
pub(crate) struct ValidatedVideoLayout {
    /// The validated width in pixels.
    pub width: i32,
    /// The validated height in pixels.
    pub height: i32,
    /// The validated pixel format.
    pub pixel_format: PixelFormat,
    /// Complete storage extent in bytes; SDK padding need not be initialized.
    pub data_len_bytes: usize,
    /// Initialized active payload, excluding all row padding.
    payload_len_bytes: usize,
    plane_layouts: [VideoPlaneLayout; 3],
    plane_count: usize,
    /// The validated first-plane SDK line stride.
    pub line_stride_or_size: LineStrideOrSize,
}

impl ValidatedVideoLayout {
    pub(crate) fn new_uncompressed(
        pixel_format: PixelFormat,
        width: i32,
        height: i32,
        line_stride: Option<i32>,
    ) -> Result<Self> {
        validate_video_dimensions_for_format(pixel_format, width, height)?;

        let width_usize = usize::try_from(width)
            .map_err(|_| Error::InvalidFrame(format!("Invalid width value: {width}")))?;
        let height_usize = usize::try_from(height)
            .map_err(|_| Error::InvalidFrame(format!("Invalid height value: {height}")))?;

        let min_stride = min_video_line_stride_checked(pixel_format, width_usize)?;
        let line_stride_usize = match line_stride {
            Some(0) => min_stride,
            Some(stride) => {
                if stride <= 0 {
                    return Err(Error::InvalidFrame(format!(
                        "Uncompressed video frame has invalid line_stride_in_bytes: {stride}"
                    )));
                }

                let stride_usize = usize::try_from(stride).map_err(|_| {
                    Error::InvalidFrame(format!("Invalid line_stride_in_bytes value: {stride}"))
                })?;

                if stride_usize < min_stride {
                    return Err(Error::InvalidFrame(format!(
                        "Video line_stride_in_bytes {stride} is smaller than minimum row size {min_stride} for {pixel_format:?} width {width}"
                    )));
                }

                stride_usize
            }
            None => min_stride,
        };

        if pixel_format.info().is_planar_420() && !line_stride_usize.is_multiple_of(2) {
            return Err(Error::InvalidFrame(format!(
                "Planar 4:2:0 video frame has odd line_stride_in_bytes: {line_stride_usize}"
            )));
        }

        let (plane_layouts, plane_count, data_len_bytes, payload_len_bytes) = video_plane_layouts(
            pixel_format.info(),
            line_stride_usize,
            min_stride,
            height_usize,
        )?;
        validate_video_data_len(data_len_bytes)?;

        let line_stride_i32 = i32::try_from(line_stride_usize).map_err(|_| {
            Error::InvalidFrame(format!(
                "Video line stride {line_stride_usize} exceeds i32 range"
            ))
        })?;

        Ok(Self {
            width,
            height,
            pixel_format,
            data_len_bytes,
            payload_len_bytes,
            plane_layouts,
            plane_count,
            line_stride_or_size: LineStrideOrSize::LineStrideBytes(line_stride_i32),
        })
    }

    fn planes(&self) -> &[VideoPlaneLayout] {
        &self.plane_layouts[..self.plane_count]
    }

    fn is_contiguous(&self) -> bool {
        // Validated planes are adjacent storage regions with active <= stride.
        // Their last active endpoint equals payload length exactly when there
        // are no intervening gaps. Trailing padding need not be included.
        let last = self.planes().last().expect("validated video has a plane");
        last.offset + (last.row_count - 1) * last.row_stride + last.active_row_bytes
            == self.payload_len_bytes
    }
}

/// Validate video frame layout from raw FFI fields.
///
/// This function performs all necessary validation including:
/// - Null pointer check for `p_data`
/// - Valid pixel format (FourCC) conversion
/// - Checked arithmetic for buffer size calculation
/// - `MAX_VIDEO_BYTES` cap enforcement
///
/// # Arguments
///
/// * `raw` - Reference to the raw NDI video frame
///
/// # Returns
///
/// `Ok(ValidatedVideoLayout)` if the frame is valid, or `Err(Error::InvalidFrame(...))` otherwise.
pub(crate) fn validate_video_layout(raw: &NDIlib_video_frame_v2_t) -> Result<ValidatedVideoLayout> {
    if raw.p_data.is_null() {
        return Err(Error::InvalidFrame(
            "Video frame has null data pointer".into(),
        ));
    }

    validate_video_frame_metadata(raw.frame_rate_N, raw.frame_rate_D, raw.picture_aspect_ratio)?;

    #[allow(clippy::unnecessary_cast)]
    ScanType::try_from(raw.frame_format_type as u32).map_err(|_| {
        Error::InvalidFrame(format!(
            "Unknown scan type: 0x{:08X}",
            raw.frame_format_type
        ))
    })?;

    #[allow(clippy::unnecessary_cast)] // Required for Windows where FourCC is i32
    let pixel_format = PixelFormat::try_from(raw.FourCC as u32).map_err(|_| {
        Error::InvalidFrame(format!("Unknown pixel format FourCC: 0x{:08X}", raw.FourCC))
    })?;

    let line_stride = unsafe { raw.__bindgen_anon_1.line_stride_in_bytes };
    ValidatedVideoLayout::new_uncompressed(pixel_format, raw.xres, raw.yres, Some(line_stride))
}

fn validate_video_dimensions_for_format(
    pixel_format: PixelFormat,
    width: i32,
    height: i32,
) -> Result<()> {
    validate_video_width(width)?;
    if height <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Video frame has invalid height: {height}"
        )));
    }

    if pixel_format.info().is_planar_420() && height % 2 != 0 {
        return Err(Error::InvalidFrame(format!(
            "Planar 4:2:0 video frames require even dimensions, got {}x{}",
            width, height
        )));
    }

    Ok(())
}

fn validate_video_width(width: i32) -> Result<()> {
    if width <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Video frame has invalid width: {width}"
        )));
    }

    // The SDK uses 4:2:2 internally, including for RGB input/output.
    // https://docs.ndi.video/all/developing-with-ndi/sdk/frame-types
    if width % 2 != 0 {
        return Err(Error::InvalidFrame(format!(
            "NDI video frames require even width, got {width}"
        )));
    }

    Ok(())
}

pub(crate) fn validate_video_frame_metadata(
    frame_rate_n: i32,
    frame_rate_d: i32,
    picture_aspect_ratio: f32,
) -> Result<()> {
    if frame_rate_n <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Video frame has invalid frame rate numerator: {frame_rate_n}"
        )));
    }
    if frame_rate_d <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Video frame has invalid frame rate denominator: {frame_rate_d}"
        )));
    }
    if !picture_aspect_ratio.is_finite() || picture_aspect_ratio < 0.0 {
        return Err(Error::InvalidFrame(format!(
            "Video frame has invalid picture aspect ratio: {picture_aspect_ratio}"
        )));
    }

    Ok(())
}

fn validate_video_data_len(data_len_bytes: usize) -> Result<()> {
    if data_len_bytes == 0 {
        return Err(Error::InvalidFrame(
            "Video frame has zero calculated size".into(),
        ));
    }

    if data_len_bytes > MAX_VIDEO_BYTES {
        return Err(Error::InvalidFrame(format!(
            "Video frame exceeds maximum size: {} bytes > {} bytes",
            data_len_bytes, MAX_VIDEO_BYTES
        )));
    }

    Ok(())
}

fn min_video_line_stride_checked(pixel_format: PixelFormat, width: usize) -> Result<usize> {
    width
        .checked_mul(pixel_format.info().bytes_per_pixel() as usize)
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Video line stride overflow for {:?} width {}",
                pixel_format, width
            ))
        })
}

/// Calculate buffer length with checked arithmetic.
#[cfg(test)]
fn calculate_buffer_len_checked(
    pixel_format: PixelFormat,
    y_stride: usize,
    height: usize,
) -> Result<usize> {
    calculate_buffer_len_for_info_checked(pixel_format.info(), y_stride, height)
}

fn calculate_buffer_len_for_info_checked(
    info: PixelFormatInfo,
    y_stride: usize,
    height: usize,
) -> Result<usize> {
    video_plane_layouts(info, y_stride, y_stride, height).map(|(_, _, storage, _)| storage)
}

#[derive(Debug, Clone, Copy, Default)]
struct VideoPlaneLayout {
    offset: usize,
    row_stride: usize,
    active_row_bytes: usize,
    row_count: usize,
}

/// Derive SDK plane offsets and active row sizes together. See
/// https://docs.ndi.video/all/developing-with-ndi/sdk/frame-types .
/// Plane offsets include preceding storage padding; payload lengths do not.
fn video_plane_layouts(
    info: PixelFormatInfo,
    stride: usize,
    active: usize,
    height: usize,
) -> Result<([VideoPlaneLayout; 3], usize, usize, usize)> {
    let mut dimensions = [(stride, active, height); 3];
    let count = match info.category() {
        FormatCategory::Packed => 1,
        FormatCategory::Planar420 => {
            if !height.is_multiple_of(2) || !stride.is_multiple_of(2) {
                return Err(Error::InvalidFrame(
                    "Planar 4:2:0 video frames require even height and stride".into(),
                ));
            }
            dimensions[1] = (stride / 2, active / 2, height / 2);
            dimensions[2] = dimensions[1];
            3
        }
        FormatCategory::SemiPlanar420 => {
            if !height.is_multiple_of(2) {
                return Err(Error::InvalidFrame(
                    "Semi-planar 4:2:0 video frames require even height".into(),
                ));
            }
            dimensions[1] = (stride, active, height / 2);
            2
        }
        FormatCategory::PackedAlpha => {
            if !stride.is_multiple_of(2) {
                return Err(Error::InvalidFrame(
                    "UYVA video frames require even stride".into(),
                ));
            }
            dimensions[1] = (stride / 2, active / 2, height);
            2
        }
        FormatCategory::SemiPlanar422 => 2,
        FormatCategory::SemiPlanar422Alpha => 3,
    };
    let mut planes = [VideoPlaneLayout::default(); 3];
    let mut storage = 0usize;
    let mut payload = 0usize;
    for (plane, &(row_stride, active_row_bytes, row_count)) in
        planes.iter_mut().zip(&dimensions[..count])
    {
        *plane = VideoPlaneLayout {
            offset: storage,
            row_stride,
            active_row_bytes,
            row_count,
        };
        storage = row_stride
            .checked_mul(row_count)
            .and_then(|n| storage.checked_add(n))
            .ok_or_else(|| Error::InvalidFrame("Video buffer size overflow".into()))?;
        payload = active_row_bytes
            .checked_mul(row_count)
            .and_then(|n| payload.checked_add(n))
            .ok_or_else(|| Error::InvalidFrame("Video payload size overflow".into()))?;
    }
    Ok((planes, count, storage, payload))
}

/// Validated audio frame layout information.
///
/// This struct holds pre-validated layout information for an audio frame,
/// including the channel stride and computed backing sample count. Creating
/// this struct performs all necessary bounds checking, so consumers can safely
/// use the cached values without re-validation.
#[derive(Debug, Clone, Copy)]
pub(crate) struct ValidatedAudioLayout {
    /// The validated audio format, or `None` for a query/no-source empty state.
    pub format: Option<AudioFormat>,
    /// The validated sample rate.
    pub sample_rate: i32,
    /// The validated channel count.
    pub no_channels: usize,
    /// The validated samples per channel.
    pub no_samples: usize,
    /// The validated channel stride in bytes.
    pub channel_stride_in_bytes: i32,
    /// The validated channel stride in `f32` samples.
    pub channel_stride_samples: usize,
    /// The validated backing sample count. For strided planar audio this may be
    /// larger than `no_channels * no_samples` because it includes inter-channel
    /// padding up to the last channel's final sample.
    pub sample_count: usize,
}

impl ValidatedAudioLayout {
    pub(crate) fn is_empty(self) -> bool {
        self.sample_count == 0
    }

    pub(crate) fn format(self) -> Option<AudioFormat> {
        self.format
    }

    pub(crate) fn channel_range(self, channel: usize) -> Option<std::ops::Range<usize>> {
        if self.is_empty() || channel >= self.no_channels {
            return None;
        }

        let start = channel.checked_mul(self.channel_stride_samples)?;
        let end = start.checked_add(self.no_samples)?;

        (end <= self.sample_count).then_some(start..end)
    }
}

fn validate_outbound_audio_layout(
    sample_rate: i32,
    no_channels: i32,
    no_samples: i32,
    format: AudioFormat,
) -> Result<ValidatedAudioLayout> {
    if sample_rate <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid sample rate: {sample_rate}"
        )));
    }
    validate_audio_format(format.into())?;
    let packed = validate_packed_audio_dimensions(no_channels, no_samples)?;

    Ok(ValidatedAudioLayout {
        format: Some(format),
        sample_rate,
        no_channels: packed.no_channels,
        no_samples: packed.no_samples,
        channel_stride_in_bytes: packed.channel_stride_in_bytes,
        channel_stride_samples: packed.no_samples,
        sample_count: packed.sample_count,
    })
}

/// Packed FLTP dimensions shared by owned frames and FrameSync requests.
/// Checking this layout allocates nothing on success and never allocates samples.
pub(crate) struct PackedAudioDimensions {
    no_channels: usize,
    no_samples: usize,
    channel_stride_in_bytes: i32,
    sample_count: usize,
}

pub(crate) fn validate_packed_audio_dimensions(
    no_channels: i32,
    no_samples: i32,
) -> Result<PackedAudioDimensions> {
    if no_channels <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid number of channels: {no_channels}"
        )));
    }
    if no_samples <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid number of samples: {no_samples}"
        )));
    }

    let no_channels = usize::try_from(no_channels)
        .map_err(|_| Error::InvalidFrame(format!("Invalid no_channels value: {no_channels}")))?;
    let no_samples = usize::try_from(no_samples)
        .map_err(|_| Error::InvalidFrame(format!("Invalid no_samples value: {no_samples}")))?;

    let channel_stride_bytes = no_samples
        .checked_mul(std::mem::size_of::<f32>())
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Audio channel stride overflow: {} samples × {} bytes",
                no_samples,
                std::mem::size_of::<f32>()
            ))
        })?;
    let channel_stride_in_bytes = i32::try_from(channel_stride_bytes).map_err(|_| {
        Error::InvalidFrame(format!(
            "Audio channel stride {channel_stride_bytes} exceeds i32 range"
        ))
    })?;

    let sample_count = no_channels.checked_mul(no_samples).ok_or_else(|| {
        Error::InvalidFrame(format!(
            "Audio sample count overflow: {no_channels} channels × {no_samples} samples"
        ))
    })?;
    let byte_size = sample_count
        .checked_mul(std::mem::size_of::<f32>())
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Audio byte size overflow: {} samples × {} bytes",
                sample_count,
                std::mem::size_of::<f32>()
            ))
        })?;

    if byte_size > MAX_AUDIO_BYTES {
        return Err(Error::InvalidFrame(format!(
            "Audio frame exceeds maximum size: {} bytes > {} bytes",
            byte_size, MAX_AUDIO_BYTES
        )));
    }

    Ok(PackedAudioDimensions {
        no_channels,
        no_samples,
        channel_stride_in_bytes,
        sample_count,
    })
}

/// Validate audio frame layout from raw FFI fields.
///
/// This function performs all necessary validation including:
/// - Null pointer check for `p_data`
/// - Valid audio format (FourCC) conversion
/// - Positive sample rate, channel count, and sample count
/// - Checked arithmetic for sample count multiplication
/// - `MAX_AUDIO_BYTES` cap enforcement
///
/// # Arguments
///
/// * `raw` - Reference to the raw NDI audio frame
///
/// # Returns
///
/// `Ok(ValidatedAudioLayout)` if the frame is valid, or `Err(Error::InvalidFrame(...))` otherwise.
pub(crate) fn validate_audio_layout(raw: &NDIlib_audio_frame_v3_t) -> Result<ValidatedAudioLayout> {
    validate_audio_layout_inner(raw, false)
}

/// Validate a FrameSync audio frame that is allowed to be a documented
/// query/no-source zero-length state.
pub(crate) fn validate_audio_layout_allow_empty(
    raw: &NDIlib_audio_frame_v3_t,
) -> Result<ValidatedAudioLayout> {
    validate_audio_layout_inner(raw, true)
}

fn validate_audio_layout_inner(
    raw: &NDIlib_audio_frame_v3_t,
    allow_empty: bool,
) -> Result<ValidatedAudioLayout> {
    if raw.no_samples == 0 {
        if allow_empty {
            return validate_empty_audio_layout(raw);
        }

        return Err(Error::InvalidFrame("Invalid number of samples: 0".into()));
    }

    if raw.p_data.is_null() {
        return Err(Error::InvalidFrame(
            "Audio frame has null data pointer".into(),
        ));
    }

    if !raw.p_data.cast::<f32>().is_aligned() {
        return Err(Error::InvalidFrame(
            "Audio data pointer is not aligned for f32".into(),
        ));
    }

    if raw.sample_rate <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid sample rate: {}",
            raw.sample_rate
        )));
    }

    if raw.no_channels <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid number of channels: {}",
            raw.no_channels
        )));
    }

    if raw.no_samples <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid number of samples: {}",
            raw.no_samples
        )));
    }

    let format = validate_audio_format(raw.FourCC)?;
    let channel_stride_in_bytes = unsafe { raw.__bindgen_anon_1.channel_stride_in_bytes };
    if channel_stride_in_bytes <= 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid channel_stride_in_bytes: {}",
            channel_stride_in_bytes
        )));
    }

    // Use checked math to prevent overflow when computing sample count
    let no_samples = usize::try_from(raw.no_samples).map_err(|_| {
        Error::InvalidFrame(format!("Invalid no_samples value: {}", raw.no_samples))
    })?;

    let no_channels = usize::try_from(raw.no_channels).map_err(|_| {
        Error::InvalidFrame(format!("Invalid no_channels value: {}", raw.no_channels))
    })?;

    let channel_stride_bytes = usize::try_from(channel_stride_in_bytes).map_err(|_| {
        Error::InvalidFrame(format!(
            "Invalid channel_stride_in_bytes value: {}",
            channel_stride_in_bytes
        ))
    })?;

    if channel_stride_bytes % std::mem::size_of::<f32>() != 0 {
        return Err(Error::InvalidFrame(format!(
            "channel_stride_in_bytes must be a multiple of {}, got {}",
            std::mem::size_of::<f32>(),
            channel_stride_in_bytes
        )));
    }

    let minimum_channel_stride = no_samples
        .checked_mul(std::mem::size_of::<f32>())
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Audio channel stride overflow: {} samples × {} bytes",
                no_samples,
                std::mem::size_of::<f32>()
            ))
        })?;

    if channel_stride_bytes < minimum_channel_stride {
        return Err(Error::InvalidFrame(format!(
            "channel_stride_in_bytes {} is smaller than one channel of audio samples {}",
            channel_stride_in_bytes, minimum_channel_stride
        )));
    }

    let channel_stride_samples = channel_stride_bytes / std::mem::size_of::<f32>();
    let last_channel_offset = no_channels
        .checked_sub(1)
        .and_then(|last| last.checked_mul(channel_stride_samples))
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Audio channel offset overflow: {} channels × {} stride samples",
                no_channels, channel_stride_samples
            ))
        })?;

    let sample_count = last_channel_offset.checked_add(no_samples).ok_or_else(|| {
        Error::InvalidFrame(format!(
            "Audio backing sample count overflow: channel offset {} + {} samples",
            last_channel_offset, no_samples
        ))
    })?;

    // Check total byte size against limit
    let byte_size = sample_count
        .checked_mul(std::mem::size_of::<f32>())
        .ok_or_else(|| {
            Error::InvalidFrame(format!(
                "Audio byte size overflow: {} samples × {} bytes",
                sample_count,
                std::mem::size_of::<f32>()
            ))
        })?;

    if byte_size > MAX_AUDIO_BYTES {
        return Err(Error::InvalidFrame(format!(
            "Audio frame exceeds maximum size: {} bytes > {} bytes",
            byte_size, MAX_AUDIO_BYTES
        )));
    }

    Ok(ValidatedAudioLayout {
        format: Some(format),
        sample_rate: raw.sample_rate,
        no_channels,
        no_samples,
        channel_stride_in_bytes,
        channel_stride_samples,
        sample_count,
    })
}

fn validate_empty_audio_layout(raw: &NDIlib_audio_frame_v3_t) -> Result<ValidatedAudioLayout> {
    if !raw.p_data.is_null() {
        return Err(Error::InvalidFrame(
            "Zero-length audio frame has non-null data pointer".into(),
        ));
    }

    if raw.sample_rate < 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid sample rate: {}",
            raw.sample_rate
        )));
    }

    if raw.no_channels < 0 {
        return Err(Error::InvalidFrame(format!(
            "Invalid number of channels: {}",
            raw.no_channels
        )));
    }

    let channel_stride_in_bytes = unsafe { raw.__bindgen_anon_1.channel_stride_in_bytes };
    if channel_stride_in_bytes != 0 {
        return Err(Error::InvalidFrame(format!(
            "Zero-length audio frame has non-zero channel_stride_in_bytes: {}",
            channel_stride_in_bytes
        )));
    }

    let no_source = raw.sample_rate == 0 && raw.no_channels == 0;
    let query_format = raw.sample_rate > 0 && raw.no_channels > 0;
    if !no_source && !query_format {
        return Err(Error::InvalidFrame(format!(
            "Invalid zero-length audio query state: sample_rate={}, no_channels={}",
            raw.sample_rate, raw.no_channels
        )));
    }

    let format = if no_source && raw.FourCC == 0 {
        None
    } else {
        Some(validate_audio_format(raw.FourCC)?)
    };

    let no_channels = usize::try_from(raw.no_channels).map_err(|_| {
        Error::InvalidFrame(format!("Invalid no_channels value: {}", raw.no_channels))
    })?;

    Ok(ValidatedAudioLayout {
        format,
        sample_rate: raw.sample_rate,
        no_channels,
        no_samples: 0,
        channel_stride_in_bytes: 0,
        channel_stride_samples: 0,
        sample_count: 0,
    })
}

fn validate_audio_format(fourcc: NDIlib_FourCC_audio_type_e) -> Result<AudioFormat> {
    match fourcc {
        NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP => Ok(AudioFormat::FLTP),
        _ => Err(Error::InvalidFrame(format!(
            "Unknown audio format FourCC: 0x{:08X}",
            fourcc
        ))),
    }
}

// ============================================================================
// Zero-copy borrowed receive frames
// ============================================================================

/// An allocation-free view of one video plane's initialized active bytes.
///
/// Plane order follows the pixel format: packed pixels; UYVY/A for UYVA;
/// Y/CbCr[/A] for P216/PA16; Y/V/U for YV12; Y/U/V for I420; Y/UV for NV12.
/// The view borrows its captured frame, which keeps the SDK allocation alive.
/// Immutable pixel views are `Send + Sync`, including views borrowed from
/// FrameSync. Scoped workers must finish before the frame is freed. This does
/// not transfer the SDK-owning frame reference or change its freeing thread.
///
/// ```no_run
/// # fn read(frame: &grafton_ndi::FrameSyncVideoRef<'_>) {
/// let plane = frame.plane(0).unwrap();
/// let rows = plane.rows();
/// std::thread::scope(|scope| {
///     let worker = scope.spawn(move || {
///         rows.flatten().map(|&byte| u64::from(byte)).sum::<u64>()
///     });
///     assert_eq!(worker.join().unwrap(),
///         plane.rows().flatten().map(|&byte| u64::from(byte)).sum::<u64>());
/// });
/// # }
/// ```
#[derive(Debug, Clone, Copy)]
pub struct VideoPlane<'a> {
    data: *const u8,
    layout: VideoPlaneLayout,
    lifetime: PhantomData<&'a [u8]>,
}

// SAFETY: Every private construction site retains one allocation for 'a and
// validates all offsets, strides, and active lengths before constructing views.
// Active bytes are initialized and immutable for 'a; padding is never sliced.
// Reads require only u8 alignment (1) and expose the same &'a [u8] already
// returned by row/data. Copying or sharing a view grants no mutation or SDK
// access. Views have no destructor/free operation. Their borrow retains the
// captured guard until all workers finish, so FrameSync still frees its frame
// on the capture thread. Owned-slice construction likewise retains its borrow.
// SDK ownership/free boundary: Processing.NDI.Recv.h (capture_v3/free_video_v2)
// and Processing.NDI.FrameSync.h (capture_video/free_video).
unsafe impl Send for VideoPlane<'_> {}
// SAFETY: Same immutable access and lifetime proof as Send above.
unsafe impl Sync for VideoPlane<'_> {}

impl<'a> VideoPlane<'a> {
    /// Caller must retain an allocation covering the validated layout for 'a,
    /// with every active row readable, initialized, and immutable for that lifetime.
    unsafe fn new(data: *const u8, layout: VideoPlaneLayout) -> Self {
        Self {
            data,
            layout,
            lifetime: PhantomData,
        }
    }

    /// Distance between row starts in bytes, including padding.
    pub fn row_stride(&self) -> usize {
        self.layout.row_stride
    }

    /// Number of initialized bytes in each row.
    pub fn active_row_bytes(&self) -> usize {
        self.layout.active_row_bytes
    }

    /// Number of rows in this plane.
    pub fn row_count(&self) -> usize {
        self.layout.row_count
    }

    /// Get an active row, excluding padding, or `None` for an invalid index.
    pub fn row(&self, index: usize) -> Option<&'a [u8]> {
        if index >= self.layout.row_count {
            return None;
        }
        // SAFETY: Construction ties the allocation to 'a. Checked plane/row
        // arithmetic bounds this range within storage. The SDK initializes the
        // active bytes; padding is never included. The guard prevents freeing.
        Some(unsafe {
            slice::from_raw_parts(
                self.data
                    .add(self.layout.offset + index * self.layout.row_stride),
                self.layout.active_row_bytes,
            )
        })
    }

    /// Iterate active rows without allocating or copying pixels.
    pub fn rows(&self) -> VideoRows<'a> {
        VideoRows {
            plane: *self,
            indices: 0..self.row_count(),
        }
    }

    /// Borrow all active bytes when contiguous, excluding trailing padding.
    /// Returns `None` when padding separates rows.
    pub fn data(&self) -> Option<&'a [u8]> {
        if self.row_count() != 1 && self.row_stride() != self.active_row_bytes() {
            return None;
        }
        // SAFETY: All rows are adjacent initialized ranges in the retained
        // allocation; the final row's padding is excluded.
        Some(unsafe {
            slice::from_raw_parts(
                self.data.add(self.layout.offset),
                self.row_count() * self.active_row_bytes(),
            )
        })
    }
}

/// Active video rows, borrowing the frame that owns the SDK allocation.
/// `Send + Sync` through its immutable plane; iteration never calls the SDK.
#[derive(Debug, Clone)]
pub struct VideoRows<'a> {
    plane: VideoPlane<'a>,
    indices: std::ops::Range<usize>,
}

impl<'a> Iterator for VideoRows<'a> {
    type Item = &'a [u8];
    fn next(&mut self) -> Option<Self::Item> {
        self.plane.row(self.indices.next()?)
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.indices.size_hint()
    }
}
impl DoubleEndedIterator for VideoRows<'_> {
    fn next_back(&mut self) -> Option<Self::Item> {
        self.plane.row(self.indices.next_back()?)
    }
}
impl ExactSizeIterator for VideoRows<'_> {}
impl std::iter::FusedIterator for VideoRows<'_> {}

/// Video planes in SDK memory order, with no allocation or pixel copies.
/// `Send + Sync` for scoped reads; the owning frame's thread rules still apply.
#[derive(Debug, Clone)]
pub struct VideoPlanes<'a> {
    data: *const u8,
    layouts: slice::Iter<'a, VideoPlaneLayout>,
}
// SAFETY: Constructed only by VideoRef::planes from a validated live frame.
// The shared layout slice and data borrow last for 'a; each yielded plane
// satisfies VideoPlane's immutable, initialized, bounded u8 access proof above.
// Iterator state is exclusively mutated, clones are independent, and neither
// iteration nor dropping it accesses an SDK handle or frees the allocation.
unsafe impl Send for VideoPlanes<'_> {}
// SAFETY: Sharing the iterator exposes only immutable layouts and bytes.
unsafe impl Sync for VideoPlanes<'_> {}
impl<'a> Iterator for VideoPlanes<'a> {
    type Item = VideoPlane<'a>;
    fn next(&mut self) -> Option<Self::Item> {
        let layout = *self.layouts.next()?;
        // SAFETY: Created only from a live frame with validated active rows.
        Some(unsafe { VideoPlane::new(self.data, layout) })
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.layouts.size_hint()
    }
}
impl ExactSizeIterator for VideoPlanes<'_> {}
impl std::iter::FusedIterator for VideoPlanes<'_> {}

/// A zero-copy borrowed video frame, generic over its free strategy `S`.
///
/// This type wraps an RAII `Guard` that owns the NDI frame buffer lifetime,
/// exposing a safe, zero-copy view of the video data. The frame is automatically
/// freed when dropped, via whichever `NDIlib_*_free_video*` call the strategy `S`
/// encodes.
///
/// The two public spellings are type aliases over this one core, so every
/// accessor and the `Debug` impl are written exactly once:
/// - [`VideoFrameRef<'rx>`] — frames captured from a [`Receiver`](crate::Receiver)
///   (freed via `NDIlib_recv_free_video_v2`).
/// - [`FrameSyncVideoRef<'fs>`](crate::FrameSyncVideoRef) — frames captured from a
///   [`FrameSync`](crate::FrameSync) (freed via `NDIlib_framesync_free_video`).
///
/// **Key characteristics:**
/// - Zero allocations: References NDI SDK buffers directly
/// - Zero copies: No memcpy of pixel data
/// - RAII lifetime: Exactly one free per frame, enforced at compile time
/// - Receiver refs are `Send + Sync`; FrameSync refs stay on their capture thread
/// - Immutable plane/row views support scoped worker reads from either family
///
/// # Lifetime
///
/// The lifetime parameter `'a` ties this frame to the owner (a `Receiver` or a
/// `FrameSync`) that created it. The borrow checker ensures the owner cannot be
/// dropped while any frame references are alive, preventing use-after-free at
/// compile time with zero runtime cost. The underlying NDI buffer is freed when
/// the frame ref is dropped.
///
/// # Performance
///
/// For a 1920×1080 BGRA frame, this eliminates ~8.3 MB of memcpy compared to
/// the owned [`VideoFrame`]. At 60 fps, this saves ~475 MB/s of memory bandwidth.
#[allow(private_bounds)]
pub struct VideoRef<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> {
    guard: Guard<'a, S>,
    /// Cached validated layout information (pixel format, data length, stride/size).
    /// Computed once at construction time; `data()` uses this cached value.
    layout: ValidatedVideoLayout,
    metadata: ValidatedFrameMetadata,
}

/// A zero-copy borrowed video frame from a [`Receiver`](crate::Receiver) capture.
///
/// This is the receiver spelling of the generic [`VideoRef`]; the
/// [`FrameSync`](crate::FrameSync) spelling is
/// [`FrameSyncVideoRef`](crate::FrameSyncVideoRef). Both share one accessor and
/// `Debug` implementation.
pub type VideoFrameRef<'rx> = VideoRef<'rx, VideoKind>;

#[allow(private_bounds)]
impl<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> VideoRef<'a, S> {
    /// Create a borrowed video frame from an RAII guard.
    ///
    /// Validates the frame layout including:
    /// - Valid pixel format (FourCC)
    /// - Non-null data pointer
    /// - Valid dimensions and stride
    /// - Buffer size within `MAX_VIDEO_BYTES` limit
    ///
    /// The validated layout is cached so that `data()` can return slices
    /// without re-computation or unchecked arithmetic.
    ///
    /// # Safety
    ///
    /// The caller must ensure the guard was created from a valid NDI instance
    /// and contains a frame populated by the matching SDK capture call.
    pub(crate) unsafe fn new(guard: Guard<'a, S>) -> Result<Self> {
        let layout = validate_video_layout(guard.frame())?;
        let metadata = unsafe { validate_frame_metadata(guard.frame().p_metadata)? };

        Ok(Self {
            guard,
            layout,
            metadata,
        })
    }

    /// Get the frame width in pixels.
    pub fn width(&self) -> i32 {
        self.guard.frame().xres
    }

    /// Get the frame height in pixels.
    pub fn height(&self) -> i32 {
        self.guard.frame().yres
    }

    /// Get the pixel format (FourCC code).
    ///
    /// This is guaranteed to be a valid, supported format since it's validated during construction.
    pub fn pixel_format(&self) -> PixelFormat {
        self.layout.pixel_format
    }

    /// Get the frame rate numerator.
    pub fn frame_rate_n(&self) -> i32 {
        self.guard.frame().frame_rate_N
    }

    /// Get the frame rate denominator.
    pub fn frame_rate_d(&self) -> i32 {
        self.guard.frame().frame_rate_D
    }

    /// Get the picture aspect ratio.
    pub fn picture_aspect_ratio(&self) -> f32 {
        self.guard.frame().picture_aspect_ratio
    }

    /// Get the scan type (progressive, interlaced, etc.).
    ///
    /// This is guaranteed to be valid since it is checked during construction.
    pub fn scan_type(&self) -> ScanType {
        #[allow(clippy::unnecessary_cast)]
        ScanType::try_from(self.guard.frame().frame_format_type as u32)
            .expect("VideoFrameRef validates scan type during construction")
    }

    /// Get the timecode in 100 ns units.
    pub fn timecode(&self) -> i64 {
        self.guard.frame().timecode
    }

    /// Get the receive timestamp in 100 ns units since the Unix epoch.
    pub fn timestamp(&self) -> i64 {
        self.guard.frame().timestamp
    }

    /// Get the line stride or data size.
    ///
    /// This returns the cached, validated value computed at construction time.
    pub fn line_stride_or_size(&self) -> LineStrideOrSize {
        self.layout.line_stride_or_size
    }

    /// Get frame metadata as UTF-8 text, if present.
    pub fn metadata(&self) -> Option<&str> {
        unsafe { frame_metadata_str(self.guard.frame().p_metadata, self.metadata) }
    }

    /// Borrow all active pixels when contiguous, in SDK plane order.
    ///
    /// Returns `None` if padding separates active rows or planes. Use
    /// [`Self::planes`] / [`Self::plane`] for zero-copy padded access, or
    /// [`Self::to_owned`] for a tightly packed owned buffer. A single packed
    /// row can be borrowed even when its stride includes trailing padding.
    pub fn data(&self) -> Option<&[u8]> {
        if !self.layout.is_contiguous() {
            return None;
        }
        // SAFETY: The guard retains the SDK allocation for this borrow. Layout
        // validation bounds the range; contiguity proves every byte is active,
        // initialized payload, with no intervening or trailing padding.
        Some(unsafe {
            slice::from_raw_parts(self.guard.frame().p_data, self.layout.payload_len_bytes)
        })
    }

    /// Get one plane in SDK memory order, or `None` for an invalid index.
    pub fn plane(&self, index: usize) -> Option<VideoPlane<'_>> {
        let layout = *self.layout.planes().get(index)?;
        // SAFETY: The returned lifetime borrows this guard, which retains the
        // allocation and its initialized, immutable active rows.
        Some(unsafe { VideoPlane::new(self.guard.frame().p_data, layout) })
    }

    /// Iterate planes in SDK memory order without allocating or copying.
    pub fn planes(&self) -> VideoPlanes<'_> {
        VideoPlanes {
            data: self.guard.frame().p_data,
            layouts: self.layout.planes().iter(),
        }
    }

    /// Encode PNG directly from the borrowed SDK pixels, without first
    /// copying the frame into an owned `VideoFrame`. Uses the same supported
    /// formats and padding handling as [`VideoFrame::encode_png`].
    #[cfg(feature = "image-encoding")]
    pub fn encode_png(&self) -> Result<Vec<u8>> {
        ImagePixelSource::from_plane(self.layout, self.plane(0).expect("validated video plane"))?
            .encode_png()
    }

    /// Encode JPEG directly from borrowed SDK pixels. Quality must be in
    /// `1..=100`; see [`VideoFrame::encode_jpeg`] for format restrictions.
    #[cfg(feature = "image-encoding")]
    pub fn encode_jpeg(&self, quality: u8) -> Result<Vec<u8>> {
        ImagePixelSource::from_plane(self.layout, self.plane(0).expect("validated video plane"))?
            .encode_jpeg(quality)
    }

    /// Encode borrowed SDK pixels as a PNG or JPEG base64 data URL without an
    /// intermediate owned frame. See [`VideoFrame::encode_data_url`].
    #[cfg(feature = "image-encoding")]
    pub fn encode_data_url(&self, format: ImageFormat) -> Result<String> {
        ImagePixelSource::from_plane(self.layout, self.plane(0).expect("validated video plane"))?
            .encode_data_url(format)
    }

    /// Convert this borrowed frame to an owned `VideoFrame`.
    ///
    /// Copies only active rows into one tightly packed pixel allocation and
    /// copies metadata separately. The owned stride can be smaller than the
    /// SDK stride. Preserves format, timing, aspect ratio, and scan type.
    pub fn to_owned(&self) -> Result<VideoFrame> {
        unsafe { VideoFrame::from_raw_validated(self.guard.frame(), self.layout, self.metadata) }
    }
}

#[allow(private_bounds)]
impl<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> fmt::Debug for VideoRef<'a, S> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct(S::REF_DEBUG_NAME)
            .field("width", &self.width())
            .field("height", &self.height())
            .field("pixel_format", &self.pixel_format())
            .field("frame_rate_n", &self.frame_rate_n())
            .field("frame_rate_d", &self.frame_rate_d())
            .field("picture_aspect_ratio", &self.picture_aspect_ratio())
            .field("scan_type", &self.scan_type())
            .field("timecode", &self.timecode())
            .field("active data (bytes)", &self.layout.payload_len_bytes)
            .field("line_stride_or_size", &self.line_stride_or_size())
            .field("metadata", &self.metadata())
            .field("timestamp", &self.timestamp())
            .finish()
    }
}

/// A zero-copy borrowed audio frame, generic over its free strategy `S`.
///
/// This type wraps an RAII `Guard` that owns the NDI frame buffer lifetime,
/// exposing a safe, zero-copy view of the audio data. The frame is automatically
/// freed when dropped, via whichever `NDIlib_*_free_audio*` call the strategy `S`
/// encodes.
///
/// The shared accessors and the `Debug` impl are written exactly once here; the
/// two public spellings are aliases that layer their differing format/owned/empty
/// policy on top:
/// - [`AudioFrameRef<'rx>`] — frames captured from a [`Receiver`](crate::Receiver)
///   (always concrete: `format() -> AudioFormat`, `to_owned() -> AudioFrame`).
/// - [`FrameSyncAudioRef<'fs>`](crate::FrameSyncAudioRef) — frames captured from a
///   [`FrameSync`](crate::FrameSync), which additionally model a validated empty
///   query/no-source state (`is_empty`, `Option`-returning `format`/`to_owned`).
///
/// **Key characteristics:**
/// - Zero allocations: References NDI SDK buffers directly
/// - Zero copies: No memcpy of audio samples
/// - RAII lifetime: Exactly one free per frame, enforced at compile time
/// - Receiver refs are `Send + Sync`; FrameSync refs stay on their capture thread
#[allow(private_bounds)]
pub struct AudioRef<'a, S: FrameFree<RawFrame = NDIlib_audio_frame_v3_t>> {
    guard: Guard<'a, S>,
    /// Cached validated layout information (format, sample count).
    /// Computed once at construction time; `data()` uses this cached value.
    layout: ValidatedAudioLayout,
    metadata: ValidatedFrameMetadata,
}

/// A zero-copy borrowed audio frame from a [`Receiver`](crate::Receiver) capture.
///
/// This is the receiver spelling of the generic [`AudioRef`]; the
/// [`FrameSync`](crate::FrameSync) spelling is
/// [`FrameSyncAudioRef`](crate::FrameSyncAudioRef). The receiver path always
/// yields a concrete audio frame, so [`format`](AudioRef::format) returns an
/// [`AudioFormat`] and [`to_owned`](AudioRef::to_owned) an [`AudioFrame`]; the
/// FrameSync path additionally models a validated empty query/no-source state.
pub type AudioFrameRef<'rx> = AudioRef<'rx, AudioKind>;

#[allow(private_bounds)]
impl<'a, S: FrameFree<RawFrame = NDIlib_audio_frame_v3_t>> AudioRef<'a, S> {
    /// Store a guard alongside an already-validated audio layout, validating and
    /// caching the frame metadata. The per-family constructors compute `layout`
    /// (concrete vs. empty-query) and funnel through here.
    ///
    /// # Safety
    ///
    /// The caller must ensure the guard was created from a valid NDI instance
    /// and that `layout` was validated from the same frame the guard owns.
    pub(crate) unsafe fn from_validated_layout(
        guard: Guard<'a, S>,
        layout: ValidatedAudioLayout,
    ) -> Result<Self> {
        let metadata = unsafe { validate_frame_metadata(guard.frame().p_metadata)? };

        Ok(Self {
            guard,
            layout,
            metadata,
        })
    }

    /// Get the sample rate in Hz.
    pub fn sample_rate(&self) -> i32 {
        self.layout.sample_rate
    }

    /// Get the number of audio channels.
    pub fn num_channels(&self) -> i32 {
        self.layout.no_channels as i32
    }

    /// Get the number of samples per channel.
    pub fn num_samples(&self) -> i32 {
        self.layout.no_samples as i32
    }

    /// Get the timecode in 100 ns units.
    pub fn timecode(&self) -> i64 {
        self.guard.frame().timecode
    }

    /// Get the receive timestamp in 100 ns units since the Unix epoch.
    pub fn timestamp(&self) -> i64 {
        self.guard.frame().timestamp
    }

    /// Get the channel stride in bytes.
    pub fn channel_stride_in_bytes(&self) -> i32 {
        self.layout.channel_stride_in_bytes
    }

    /// Get frame metadata as UTF-8 text, if present.
    pub fn metadata(&self) -> Option<&str> {
        unsafe { frame_metadata_str(self.guard.frame().p_metadata, self.metadata) }
    }

    /// Get a zero-copy slice when channels are tightly packed.
    ///
    /// Returns `None` for multi-channel buffers with padding between channels.
    /// Use [`channel_data`](Self::channel_data) or [`channels`](Self::channels)
    /// for those buffers. An empty query/no-source frame returns `Some(&[])`.
    pub fn data(&self) -> Option<&[f32]> {
        if self.layout.is_empty() {
            return Some(&[]);
        }
        if self.layout.no_channels > 1
            && self.layout.channel_stride_samples != self.layout.no_samples
        {
            return None;
        }
        // SAFETY: a packed FLTP buffer contains only initialized samples;
        // construction checked dimensions, byte bounds, and float alignment.
        Some(unsafe {
            slice::from_raw_parts(
                self.guard.frame().p_data.cast::<f32>(),
                self.layout.sample_count,
            )
        })
    }

    /// Get the zero-copy samples for a single channel, excluding padding.
    pub fn channel_data(&self, channel: usize) -> Option<&[f32]> {
        let range = self.layout.channel_range(channel)?;
        // SAFETY: only this channel's initialized sample region is borrowed.
        Some(unsafe {
            slice::from_raw_parts(
                self.guard.frame().p_data.cast::<f32>().add(range.start),
                self.layout.no_samples,
            )
        })
    }

    /// Iterate over channel slices without reading inter-channel padding.
    /// Empty query/no-source frames yield no channels.
    pub fn channels(&self) -> impl ExactSizeIterator<Item = &[f32]> + '_ {
        let count = if self.layout.is_empty() {
            0
        } else {
            self.layout.no_channels
        };
        (0..count).map(|channel| self.channel_data(channel).expect("validated channel"))
    }
}

impl<'rx> AudioRef<'rx, AudioKind> {
    /// Create a borrowed audio frame from a receiver RAII guard.
    ///
    /// Validates the frame layout including:
    /// - Valid audio format (FourCC)
    /// - Non-null data pointer
    /// - Valid sample rate, channel count, and sample count
    /// - Buffer size within `MAX_AUDIO_BYTES` limit
    ///
    /// The validated layout is cached so that `data()` can return slices
    /// without re-computation or unchecked arithmetic.
    ///
    /// # Safety
    ///
    /// The caller must ensure the guard was created from a valid NDI receiver
    /// and contains a frame populated by `NDIlib_recv_capture_v3`.
    pub(crate) unsafe fn new(guard: RecvAudioGuard<'rx>) -> Result<Self> {
        let layout = validate_audio_layout(guard.frame())?;
        unsafe { Self::from_validated_layout(guard, layout) }
    }

    /// Get the audio format (FourCC code).
    ///
    /// This is guaranteed to be a valid, supported format since it's validated during construction.
    pub fn format(&self) -> AudioFormat {
        self.layout
            .format()
            .expect("validate_audio_layout requires a concrete audio format")
    }

    /// Convert this borrowed frame to an owned `AudioFrame`.
    ///
    /// Copies channel samples into tightly packed planar storage and copies
    /// metadata, allowing the frame to outlive the SDK buffer. Padding is omitted.
    pub fn to_owned(&self) -> Result<AudioFrame> {
        // SAFETY: the receive guard owns the exact validated frame through copying.
        unsafe { AudioFrame::from_raw_validated(*self.guard.frame(), self.layout, self.metadata) }
    }
}

impl<'fs> AudioRef<'fs, FrameSyncAudioFree> {
    /// Create a borrowed audio frame from a FrameSync RAII guard.
    ///
    /// When `query_input` is set, the SDK may report a validated empty
    /// query/no-source state (no samples); otherwise a concrete frame is
    /// required. A query that unexpectedly returns samples is rejected.
    ///
    /// # Safety
    ///
    /// The caller must ensure the guard was created from a valid FrameSync
    /// instance and contains a frame populated by `NDIlib_framesync_capture_audio_v2`.
    pub(crate) unsafe fn new(
        guard: Guard<'fs, FrameSyncAudioFree>,
        query_input: bool,
    ) -> Result<Self> {
        let layout = if query_input {
            if guard.frame().no_samples != 0 {
                return Err(Error::InvalidFrame(format!(
                    "FrameSync audio query returned {} samples",
                    guard.frame().no_samples
                )));
            }
            validate_audio_layout_allow_empty(guard.frame())?
        } else {
            validate_audio_layout(guard.frame())?
        };
        unsafe { Self::from_validated_layout(guard, layout) }
    }

    /// Returns true for a valid query/no-source state with no sample buffer.
    pub fn is_empty(&self) -> bool {
        self.layout.is_empty()
    }

    /// Get the audio format (FourCC code), or `None` for an empty query/no-source state.
    pub fn format(&self) -> Option<AudioFormat> {
        self.layout.format()
    }

    /// Convert this borrowed frame to an owned `AudioFrame`.
    ///
    /// Copies channel samples into tightly packed planar storage and copies
    /// metadata, allowing the frame to outlive the SDK buffer. Padding is omitted.
    ///
    /// Returns `Ok(None)` for a valid query/no-source state with no sample
    /// buffer to own.
    pub fn to_owned(&self) -> Result<Option<AudioFrame>> {
        if self.layout.is_empty() {
            Ok(None)
        } else {
            // SAFETY: the FrameSync guard owns the exact validated frame through copying.
            unsafe {
                AudioFrame::from_raw_validated(*self.guard.frame(), self.layout, self.metadata)
            }
            .map(Some)
        }
    }
}

#[allow(private_bounds)]
impl<'a, S: FrameFree<RawFrame = NDIlib_audio_frame_v3_t>> fmt::Debug for AudioRef<'a, S> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct(S::REF_DEBUG_NAME)
            .field("sample_rate", &self.sample_rate())
            .field("num_channels", &self.num_channels())
            .field("num_samples", &self.num_samples())
            .field("timecode", &self.timecode())
            // Render the format from the cached layout (`Option<AudioFormat>`) so
            // this single impl serves both the receiver and FrameSync spellings,
            // whose public `format()` return types differ.
            .field("format", &self.layout.format())
            .field("samples per channel", &self.layout.no_samples)
            .field("channel_stride_in_bytes", &self.channel_stride_in_bytes())
            .field("metadata", &self.metadata())
            .field("timestamp", &self.timestamp())
            .finish()
    }
}

/// A zero-copy borrowed metadata frame.
///
/// This type wraps an RAII guard that owns the NDI frame buffer lifetime,
/// exposing a safe, zero-copy view of the metadata string. The frame is automatically
/// freed when dropped via `NDIlib_recv_free_metadata`.
///
/// **Key characteristics:**
/// - Zero allocations: References NDI SDK buffers directly
/// - Zero copies: No string duplication
/// - RAII lifetime: Exactly one free per frame, enforced at compile time
/// - `Send + Sync`: Captured metadata can be processed on a scoped worker thread
///
/// # Examples
///
/// ```no_run
/// # use grafton_ndi::{NDI, ReceiverOptions, Receiver, Source, SourceAddress};
/// # use std::time::Duration;
/// # fn main() -> Result<(), grafton_ndi::Error> {
/// # let ndi = NDI::new()?;
/// # let source = Source { name: "Test".into(), address: SourceAddress::None };
/// # let options = ReceiverOptions::builder(source).build();
/// # let receiver = Receiver::new(&ndi, &options)?;
/// // Zero-copy capture
/// if let Some(frame) = receiver.metadata().try_capture_ref(Duration::from_millis(1000))? {
///     println!("Metadata: {}", frame.data());
///
///     // Frame is freed here when `frame` goes out of scope
/// }
/// # Ok(())
/// # }
/// ```
pub struct MetadataFrameRef<'rx> {
    guard: RecvMetadataGuard<'rx>,
    /// Cached validated layout information. Computed once at construction time;
    /// `data()` and `as_bytes()` use this cached value.
    layout: ValidatedMetadataLayout,
}

impl<'rx> MetadataFrameRef<'rx> {
    /// Create a borrowed metadata frame from an RAII guard.
    ///
    /// # Safety
    ///
    /// The caller must ensure the guard was created from a valid NDI receiver
    /// and contains a frame populated by `NDIlib_recv_capture_v3`.
    pub(crate) unsafe fn new(guard: RecvMetadataGuard<'rx>) -> Result<Self> {
        // SAFETY: the receive guard owns the SDK metadata buffer through validation.
        let layout = unsafe { validate_metadata_layout(guard.frame())? };

        Ok(Self { guard, layout })
    }

    /// Get the timecode in 100 ns units.
    pub fn timecode(&self) -> i64 {
        self.guard.frame().timecode
    }

    /// Get a zero-copy view of the metadata text.
    ///
    /// This returns a reference directly into the NDI SDK's buffer.
    /// No allocation or string copying is performed.
    pub fn data(&self) -> &str {
        let bytes = self.as_bytes();
        // SAFETY: `validate_metadata_layout` checked UTF-8 before this
        // borrowed frame was constructed.
        unsafe { str::from_utf8_unchecked(bytes) }
    }

    /// Get a zero-copy view of the metadata UTF-8 payload bytes, excluding the
    /// SDK trailing NUL terminator.
    pub fn as_bytes(&self) -> &[u8] {
        // SAFETY: the receive guard owns the exact validated buffer for this borrow.
        unsafe { metadata_payload_bytes(self.guard.frame(), self.layout) }
    }

    /// Convert this borrowed frame to an owned `MetadataFrame`.
    ///
    /// This performs a string copy, allowing the frame to outlive
    /// the NDI buffer and be sent across threads.
    pub fn to_owned(&self) -> MetadataFrame {
        unsafe { MetadataFrame::from_raw_validated(self.guard.frame(), self.layout) }
    }
}

impl<'rx> fmt::Debug for MetadataFrameRef<'rx> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("MetadataFrameRef")
            .field("data", &self.data())
            .field("data (bytes)", &self.as_bytes().len())
            .field("timecode", &self.timecode())
            .finish()
    }
}

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

    #[test]
    fn packed_audio_dimensions_match_wide_oracle_and_owned_validation() {
        fn check(channels: i32, samples: i32) {
            let bytes = i128::from(channels) * i128::from(samples) * 4;
            let stride = i128::from(samples) * 4;
            let valid = channels > 0
                && samples > 0
                && stride <= i128::from(i32::MAX)
                && bytes <= MAX_AUDIO_BYTES as i128;
            let packed = validate_packed_audio_dimensions(channels, samples);
            let owned =
                validate_outbound_audio_layout(48_000, channels, samples, AudioFormat::FLTP);
            let request = crate::FrameSyncAudioRequest::capture(channels, samples);
            assert_eq!(
                packed.is_ok(),
                valid,
                "channels={channels}, samples={samples}"
            );
            assert_eq!(owned.is_ok(), valid);
            assert_eq!(request.is_ok(), valid);
            if let (Ok(packed), Ok(owned)) = (packed, owned) {
                assert_eq!(packed.sample_count as i128 * 4, bytes);
                assert_eq!(i128::from(packed.channel_stride_in_bytes), stride);
                assert_eq!(packed.no_channels, owned.no_channels);
                assert_eq!(packed.no_samples, owned.no_samples);
                assert_eq!(
                    packed.channel_stride_in_bytes,
                    owned.channel_stride_in_bytes
                );
                assert_eq!(packed.sample_count, owned.sample_count);
            }
        }
        let values = [
            i32::MIN,
            -1,
            0,
            1,
            2,
            3,
            16,
            1024,
            8_388_608,
            8_388_609,
            16_777_216,
            16_777_217,
            i32::MAX / 4,
            i32::MAX / 4 + 1,
            1_073_741_825,
            i32::MAX,
        ];
        for channels in values {
            for samples in values {
                check(channels, samples);
            }
        }
        // Deterministic property coverage around the payload boundary, plus the
        // full signed SDK input range. No sample buffers are allocated.
        let mut seed = 102u64;
        for _ in 0..4096 {
            seed = seed.wrapping_mul(6364136223846793005).wrapping_add(1);
            let channels = (seed >> 32) as i32;
            check(channels, seed as i32);
            let channels = ((seed >> 32) % 4096 + 1) as i32;
            let boundary = (MAX_AUDIO_BYTES / 4) as i32 / channels;
            for samples in [boundary - 1, boundary, boundary + 1] {
                check(channels, samples);
            }
        }
        // The signed stride boundary is rejected independently of the cap.
        let at_stride_limit = validate_packed_audio_dimensions(1, i32::MAX / 4);
        assert!(at_stride_limit
            .err()
            .unwrap()
            .to_string()
            .contains("maximum size"));
        let over_stride_limit = validate_packed_audio_dimensions(1, i32::MAX / 4 + 1);
        assert!(over_stride_limit
            .err()
            .unwrap()
            .to_string()
            .contains("stride"));
    }

    /// Compare the old full-span copy with normalized active-row copies using
    /// initialized storage. Run with `cargo test --release --lib
    /// video_padding_throughput -- --ignored --nocapture`.
    #[test]
    #[ignore = "Manual optimized video throughput comparison"]
    fn video_padding_throughput() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        use std::{hint::black_box, time::Instant};
        for (width, height) in [(1920, 1080), (3840, 2160)] {
            for padding in [0, 64] {
                let stride = width * 4 + padding;
                let mut storage = vec![17u8; (stride * height) as usize];
                let raw = NDIlib_video_frame_v2_t {
                    xres: width,
                    yres: height,
                    FourCC: PixelFormat::BGRA.into(),
                    frame_rate_N: 60,
                    frame_rate_D: 1,
                    frame_format_type: ScanType::Progressive.into(),
                    p_data: storage.as_mut_ptr(),
                    __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                        line_stride_in_bytes: stride,
                    },
                    ..Default::default()
                };
                let frame = unsafe {
                    VideoRef::new(Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw))
                }
                .unwrap();
                let iterations = 100;
                // Warm allocation and page caches for both implementations.
                black_box(storage.clone());
                black_box(frame.to_owned().unwrap());
                let start = Instant::now();
                for _ in 0..iterations {
                    black_box(black_box(&storage).clone());
                }
                let baseline = start.elapsed();
                let start = Instant::now();
                for _ in 0..iterations {
                    black_box(black_box(&frame).to_owned().unwrap());
                }
                let packed = start.elapsed();
                let start = Instant::now();
                for _ in 0..iterations * 100 {
                    for plane in black_box(&frame).planes() {
                        for row in plane.rows() {
                            black_box(row);
                        }
                    }
                }
                let traversal = start.elapsed();
                eprintln!("{width}x{height} padding={padding}: old storage copy {:.3} ms/frame, active copy {:.3} ms/frame, row traversal {:.3} us/frame, copied {} active bytes",
                    baseline.as_secs_f64() * 1000.0 / f64::from(iterations),
                    packed.as_secs_f64() * 1000.0 / f64::from(iterations),
                    traversal.as_secs_f64() * 1_000_000.0 / f64::from(iterations * 100),
                    frame.layout.payload_len_bytes);
            }
        }
    }

    #[test]
    fn video_padding_all_formats_expose_and_copy_only_initialized_rows() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        use std::mem::MaybeUninit;
        // Independently specified active plane dimensions for 4x4 images.
        let cases: &[(PixelFormat, &[(usize, usize)])] = &[
            (PixelFormat::BGRA, &[(16, 4)]),
            (PixelFormat::BGRX, &[(16, 4)]),
            (PixelFormat::RGBA, &[(16, 4)]),
            (PixelFormat::RGBX, &[(16, 4)]),
            (PixelFormat::UYVY, &[(8, 4)]),
            (PixelFormat::UYVA, &[(8, 4), (4, 4)]),
            (PixelFormat::P216, &[(8, 4), (8, 4)]),
            (PixelFormat::PA16, &[(8, 4), (8, 4), (8, 4)]),
            (PixelFormat::YV12, &[(4, 4), (2, 2), (2, 2)]),
            (PixelFormat::I420, &[(4, 4), (2, 2), (2, 2)]),
            (PixelFormat::NV12, &[(4, 4), (4, 2)]),
        ];
        for &(format, dimensions) in cases {
            for padding in [0, 4, 8] {
                let stride = dimensions[0].0 + padding;
                let mut storage = vec![MaybeUninit::<u8>::uninit(); 512];
                let mut expected = Vec::new();
                let mut offsets = Vec::new();
                let mut offset = 0;
                for (i, &(active, rows)) in dimensions.iter().enumerate() {
                    let plane_stride = stride * active / dimensions[0].0;
                    offsets.push(offset);
                    for row in 0..rows {
                        for byte in 0..active {
                            let value = (i * 71 + row * 17 + byte) as u8;
                            storage[offset + row * plane_stride + byte].write(value);
                            expected.push(value);
                        }
                    }
                    offset += plane_stride * rows;
                }
                let metadata = CString::new("<video-padding/>").unwrap();
                let raw = NDIlib_video_frame_v2_t {
                    xres: 4,
                    yres: 4,
                    FourCC: format.into(),
                    frame_rate_N: 30000,
                    frame_rate_D: 1001,
                    picture_aspect_ratio: 1.25,
                    frame_format_type: ScanType::Interlaced.into(),
                    timecode: 12345,
                    timestamp: 67890,
                    p_data: storage.as_mut_ptr().cast(),
                    p_metadata: metadata.as_ptr(),
                    __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                        line_stride_in_bytes: stride as i32,
                    },
                };
                // Null FrameSync guards skip SDK calls; storage and metadata
                // live until both independent guards and their views are gone.
                let make = || unsafe {
                    VideoRef::new(Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw)).unwrap()
                };
                let (frame, allocations) = crate::test_alloc::allocation_count(make);
                assert_eq!(allocations, 0);
                let second = make();
                let ((), allocations) = crate::test_alloc::allocation_count(|| {
                    assert_eq!(frame.planes().len(), dimensions.len());
                    assert!(frame.plane(dimensions.len()).is_none());
                    assert_eq!(frame.data().is_some(), padding == 0);
                    if let Some(data) = frame.data() {
                        assert_eq!(data, expected);
                    }
                    let mut position = 0;
                    for (i, plane) in frame.planes().enumerate() {
                        let (active, rows) = dimensions[i];
                        assert_eq!(plane.row_count(), rows);
                        assert_eq!(plane.active_row_bytes(), active);
                        assert_eq!(plane.row_stride(), stride * active / dimensions[0].0);
                        assert_eq!(plane.data().is_some(), padding == 0);
                        assert!(plane.row(rows).is_none());
                        let mut iterator = plane.rows();
                        assert_eq!(iterator.len(), rows);
                        assert_eq!(iterator.next_back(), plane.row(rows - 1));
                        assert_eq!(iterator.len(), rows - 1);
                        for (row_index, row) in plane.rows().enumerate() {
                            assert_eq!(row.as_ptr(), unsafe {
                                storage
                                    .as_ptr()
                                    .cast::<u8>()
                                    .add(offsets[i] + row_index * plane.row_stride())
                            });
                            assert_eq!(row, &expected[position..position + active]);
                            position += active;
                        }
                    }
                    assert_eq!(position, expected.len());
                });
                assert_eq!(allocations, 0);
                // Preconstructed views and independent iterator clones can be
                // moved/shared while this thread retains the FrameSync guard.
                let planes = frame.planes();
                let moved_planes = planes.clone();
                let expected_sum: u64 = expected.iter().map(|&b| u64::from(b)).sum();
                std::thread::scope(|scope| {
                    let shared = &planes;
                    let reader = scope.spawn(move || {
                        shared
                            .clone()
                            .flat_map(|p| p.rows())
                            .flatten()
                            .map(|&b| u64::from(b))
                            .sum::<u64>()
                    });
                    let moved = scope.spawn(move || {
                        moved_planes
                            .flat_map(|p| p.rows().rev())
                            .flatten()
                            .map(|&b| u64::from(b))
                            .sum::<u64>()
                    });
                    assert_eq!(reader.join().unwrap(), expected_sum);
                    assert_eq!(moved.join().unwrap(), expected_sum);
                });
                for plane in frame.planes() {
                    let rows = plane.rows();
                    let clone = rows.clone();
                    let serial = rows.clone().flatten().copied().collect::<Vec<_>>();
                    std::thread::scope(|scope| {
                        let shared = &plane;
                        let reader = scope
                            .spawn(move || shared.rows().flatten().copied().collect::<Vec<_>>());
                        let moved =
                            scope.spawn(move || rows.flatten().copied().collect::<Vec<_>>());
                        let reversed = scope.spawn(move || {
                            clone.rev().rev().flatten().copied().collect::<Vec<_>>()
                        });
                        assert_eq!(reader.join().unwrap(), serial);
                        assert_eq!(moved.join().unwrap(), serial);
                        assert_eq!(reversed.join().unwrap(), serial);
                    });
                }
                assert_eq!(frame.layout.data_len_bytes, offset);
                assert_eq!(frame.layout.payload_len_bytes, expected.len());
                let owned = frame.to_owned().unwrap();
                let raw_owned = unsafe { VideoFrame::from_raw(&raw) }.unwrap();
                assert_eq!(owned.data(), expected);
                assert_eq!(raw_owned.data(), expected);
                assert_eq!(owned.pixel_format(), format);
                assert_eq!(
                    owned.line_stride_or_size(),
                    LineStrideOrSize::LineStrideBytes(dimensions[0].0 as i32)
                );
                assert_eq!(owned.metadata(), Some("<video-padding/>"));
                assert_eq!((owned.frame_rate_n(), owned.frame_rate_d()), (30000, 1001));
                assert_eq!(owned.picture_aspect_ratio(), 1.25);
                assert_eq!(owned.scan_type(), ScanType::Interlaced);
                assert_eq!((owned.timecode(), owned.timestamp()), (12345, 67890));
                drop(frame);
                assert_eq!(
                    second.plane(0).unwrap().row(0).unwrap(),
                    &expected[..dimensions[0].0]
                );
                // No metadata: exactly one allocation for active owned pixels.
                let raw = NDIlib_video_frame_v2_t {
                    p_metadata: ptr::null(),
                    ..raw
                };
                let (copied, allocations) = crate::test_alloc::allocation_count(|| {
                    unsafe { VideoFrame::from_raw(&raw) }.unwrap()
                });
                assert_eq!(allocations, 1);
                assert_eq!(copied.data(), expected);
                assert!(VideoFrame::builder()
                    .resolution(4, 4)
                    .pixel_format(format)
                    .data(vec![0; expected.len() - 1])
                    .build()
                    .is_err());
                assert!(crate::BorrowedVideoFrame::try_from_uncompressed(
                    &vec![0; expected.len() - 1],
                    4,
                    4,
                    format,
                    30,
                    1,
                )
                .is_err());
                // Copied-send conversion must use the same normalization.
                // This send-side fixture initializes padding too, because its
                // constructor takes an already initialized application slice.
                let mut initialized = vec![99; offset];
                let mut position = 0;
                for (i, &(active, rows)) in dimensions.iter().enumerate() {
                    let plane_stride = stride * active / dimensions[0].0;
                    for row in 0..rows {
                        let start = offsets[i] + row * plane_stride;
                        initialized[start..start + active]
                            .copy_from_slice(&expected[position..position + active]);
                        position += active;
                    }
                }
                let send = crate::BorrowedVideoFrame::builder(&initialized, 4, 4, format)
                    .frame_rate(30000, 1001)
                    .picture_aspect_ratio(1.25)
                    .scan_type(ScanType::Interlaced)
                    .timecode(12345)
                    .line_stride(stride as i32)
                    .metadata(&metadata)
                    .timestamp(67890)
                    .build()
                    .unwrap();
                let normalized = send.try_to_owned().unwrap();
                assert_eq!(normalized.data(), expected);
                assert_eq!(
                    normalized.line_stride_or_size(),
                    copied.line_stride_or_size()
                );
                assert_eq!(normalized.metadata(), Some("<video-padding/>"));
            }
        }
    }

    #[test]
    fn video_padding_single_rows_and_zero_stride() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        use std::mem::MaybeUninit;
        for format in [
            PixelFormat::BGRA,
            PixelFormat::BGRX,
            PixelFormat::RGBA,
            PixelFormat::RGBX,
            PixelFormat::UYVY,
            PixelFormat::UYVA,
            PixelFormat::P216,
            PixelFormat::PA16,
        ] {
            let tight = ValidatedVideoLayout::new_uncompressed(format, 2, 1, Some(0)).unwrap();
            assert!(tight.is_contiguous());
            let active = format.try_line_stride(2).unwrap();
            let padded =
                ValidatedVideoLayout::new_uncompressed(format, 2, 1, Some(active + 4)).unwrap();
            let mut storage = [MaybeUninit::<u8>::uninit(); 64];
            for plane in padded.planes() {
                for byte in &mut storage[plane.offset..plane.offset + plane.active_row_bytes] {
                    byte.write(42);
                }
            }
            let raw = NDIlib_video_frame_v2_t {
                xres: 2,
                yres: 1,
                FourCC: format.into(),
                frame_rate_N: 30,
                frame_rate_D: 1,
                p_data: storage.as_mut_ptr().cast(),
                frame_format_type: ScanType::Progressive.into(),
                __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                    line_stride_in_bytes: active + 4,
                },
                ..Default::default()
            };
            let frame =
                unsafe { VideoRef::new(Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw)) }
                    .unwrap();
            assert_eq!(frame.data().is_some(), padded.plane_count == 1);
            for plane in frame.planes() {
                assert_eq!(plane.data().unwrap(), vec![42; plane.active_row_bytes()]);
            }
            assert_eq!(
                frame.to_owned().unwrap().data(),
                vec![42; tight.payload_len_bytes]
            );
        }
        for format in [PixelFormat::YV12, PixelFormat::I420, PixelFormat::NV12] {
            let tight = ValidatedVideoLayout::new_uncompressed(format, 4, 2, Some(0)).unwrap();
            assert!(tight.is_contiguous());
            let padded = ValidatedVideoLayout::new_uncompressed(format, 4, 2, Some(8)).unwrap();
            assert!(!padded.is_contiguous()); // Chroma is one row, but plane gaps remain.
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn video_padding_encoders_never_read_uninitialized_gaps() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        use std::mem::MaybeUninit;
        for format in [
            PixelFormat::BGRA,
            PixelFormat::BGRX,
            PixelFormat::RGBA,
            PixelFormat::RGBX,
        ] {
            let mut storage = [MaybeUninit::<u8>::uninit(); 24];
            let pixels = [1, 2, 3, 255, 5, 6, 7, 255, 9, 10, 11, 255, 13, 14, 15, 255];
            for row in 0..2 {
                for byte in 0..8 {
                    storage[row * 12 + byte].write(pixels[row * 8 + byte]);
                }
            }
            let raw = NDIlib_video_frame_v2_t {
                xres: 2,
                yres: 2,
                FourCC: format.into(),
                frame_rate_N: 30,
                frame_rate_D: 1,
                frame_format_type: ScanType::Progressive.into(),
                p_data: storage.as_mut_ptr().cast(),
                __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                    line_stride_in_bytes: 12,
                },
                ..Default::default()
            };
            let borrowed =
                unsafe { VideoRef::new(Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw)) }
                    .unwrap();
            let packed = image_test_frame(format, 2, 2, None, pixels.to_vec());
            let png = borrowed.encode_png().unwrap();
            assert_eq!(
                decode_png_rgba(&png),
                decode_png_rgba(&packed.encode_png().unwrap())
            );
            assert_eq!(
                borrowed.encode_jpeg(85).unwrap(),
                packed.encode_jpeg(85).unwrap()
            );
            assert_eq!(
                borrowed.encode_data_url(ImageFormat::Png).unwrap(),
                packed.encode_data_url(ImageFormat::Png).unwrap()
            );
            assert_eq!(borrowed.to_owned().unwrap().data(), pixels);
        }
    }

    #[test]
    fn video_padding_reported_642_pixel_reproduction() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        use std::mem::MaybeUninit;
        let mut storage = vec![MaybeUninit::<u8>::uninit(); 2592 * 32];
        for row in 0..32 {
            for byte in &mut storage[row * 2592..row * 2592 + 2568] {
                byte.write(17);
            }
        }
        let raw = NDIlib_video_frame_v2_t {
            xres: 642,
            yres: 32,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 30,
            frame_rate_D: 1,
            frame_format_type: ScanType::Progressive.into(),
            p_data: storage.as_mut_ptr().cast(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 2592,
            },
            ..Default::default()
        };
        let frame =
            unsafe { VideoRef::new(Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw)) }
                .unwrap();
        assert!(frame.data().is_none());
        let owned = frame.to_owned().unwrap();
        assert_eq!(owned.data().len(), 82_176);
        assert_eq!(
            owned.line_stride_or_size(),
            LineStrideOrSize::LineStrideBytes(2568)
        );
        assert!(owned.data().iter().all(|&byte| byte == 17));
    }

    #[test]
    fn video_default_matches_builder_and_reuse_updates_preserve_pixels() {
        let default = VideoFrame::default();
        let built = VideoFrame::builder().build().unwrap();
        assert_eq!(default.scan_type(), built.scan_type());
        assert_eq!(default.scan_type(), ScanType::Progressive);
        assert_eq!(default.frame_rate_n(), built.frame_rate_n());
        assert_eq!(default.timecode(), built.timecode());
        let mut frame = VideoFrame::builder().resolution(2, 2).build().unwrap();
        let pixels = frame.data().as_ptr();
        frame.set_timecode(123);
        frame.set_timestamp(456);
        frame.set_scan_type(ScanType::Field1);
        let raw = frame.to_raw();
        assert_eq!(raw.timecode, 123);
        assert_eq!(raw.timestamp, 456);
        assert_eq!(frame.scan_type(), ScanType::Field1);
        assert_eq!(frame.data().as_ptr(), pixels);
    }

    #[test]
    fn video_builder_retains_supplied_allocation_and_rejects_wrong_lengths() {
        let data = vec![37; 16];
        let pixels = data.as_ptr();
        let frame = VideoFrame::builder()
            .resolution(2, 2)
            .data(data)
            .build()
            .unwrap();
        assert_eq!(frame.data().as_ptr(), pixels);
        assert_eq!(frame.data(), &[37; 16]);
        for len in [0, 15, 17] {
            assert!(VideoFrame::builder()
                .resolution(2, 2)
                .data(vec![0; len])
                .build()
                .is_err());
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn borrowed_video_encoding_uses_padded_pixels_without_owned_conversion() {
        use crate::capture::{FrameSyncVideoFree, Guard};
        let frame = image_test_frame(
            PixelFormat::BGRA,
            2,
            2,
            Some(12),
            vec![
                0, 0, 255, 255, 0, 255, 0, 128, 99, 99, 99, 99, 255, 0, 0, 64, 255, 255, 255, 0,
                99, 99, 99, 99,
            ],
        );
        // The null-instance FrameSync strategy never frees these test-owned
        // pixels. The owned source stays alive for the borrowed view's use.
        let guard = unsafe { Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), frame.to_raw()) };
        let borrowed = unsafe { VideoRef::new(guard) }.unwrap();
        assert!(borrowed.data().is_none());
        assert_eq!(
            borrowed.plane(0).unwrap().row(0).unwrap().as_ptr(),
            frame.data().as_ptr()
        );
        let png = borrowed.encode_png().unwrap();
        assert_eq!(
            decode_png_rgba(&png),
            (
                2,
                2,
                vec![255, 0, 0, 255, 0, 255, 0, 128, 0, 0, 255, 64, 255, 255, 255, 0,]
            )
        );
        assert_eq!(png, frame.encode_png().unwrap());
        assert_eq!(
            borrowed.encode_jpeg(85).unwrap(),
            frame.encode_jpeg(85).unwrap()
        );
        assert_eq!(
            borrowed.encode_data_url(ImageFormat::Png).unwrap(),
            frame.encode_data_url(ImageFormat::Png).unwrap()
        );
        assert_eq!(
            borrowed.encode_data_url(ImageFormat::Jpeg(85)).unwrap(),
            frame.encode_data_url(ImageFormat::Jpeg(85)).unwrap()
        );
        assert!(borrowed.encode_jpeg(0).is_err());

        let unsupported = VideoFrame::builder()
            .resolution(2, 2)
            .pixel_format(PixelFormat::UYVY)
            .build()
            .unwrap();
        let guard =
            unsafe { Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), unsupported.to_raw()) };
        let borrowed = unsafe { VideoRef::new(guard) }.unwrap();
        assert!(borrowed.encode_png().is_err());
        assert!(borrowed.encode_jpeg(85).is_err());
    }

    #[cfg(feature = "image-encoding")]
    fn image_test_frame(
        pixel_format: PixelFormat,
        width: i32,
        height: i32,
        line_stride: Option<i32>,
        data: Vec<u8>,
    ) -> VideoFrame {
        let layout =
            ValidatedVideoLayout::new_uncompressed(pixel_format, width, height, line_stride)
                .unwrap();
        assert_eq!(data.len(), layout.data_len_bytes);

        VideoFrame {
            layout,
            frame_rate_n: 60,
            frame_rate_d: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            scan_type: ScanType::Progressive,
            timecode: 0,
            data,
            metadata: None,
            timestamp: 0,
        }
    }

    #[cfg(feature = "image-encoding")]
    fn decode_png_rgba(png_bytes: &[u8]) -> (u32, u32, Vec<u8>) {
        let decoder = png::Decoder::new(std::io::Cursor::new(png_bytes));
        let mut reader = decoder.read_info().unwrap();
        let output_size = reader.output_buffer_size().unwrap();
        let mut output = vec![0; output_size];
        let info = reader.next_frame(&mut output).unwrap();
        output.truncate(info.buffer_size());

        assert_eq!(info.color_type, png::ColorType::Rgba);
        assert_eq!(info.bit_depth, png::BitDepth::Eight);

        (info.width, info.height, output)
    }

    #[cfg(feature = "image-encoding")]
    fn assert_jpeg_markers(jpeg_bytes: &[u8]) {
        assert!(jpeg_bytes.len() >= 4);
        assert_eq!(&jpeg_bytes[..2], &[0xFF, 0xD8]);
        assert_eq!(&jpeg_bytes[jpeg_bytes.len() - 2..], &[0xFF, 0xD9]);
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_png_decodes_exact_supported_pixels() {
        let cases = [
            (
                PixelFormat::RGBA,
                vec![10, 20, 30, 40, 50, 60, 70, 80],
                vec![10, 20, 30, 40, 50, 60, 70, 80],
            ),
            (
                PixelFormat::BGRA,
                vec![30, 20, 10, 40, 70, 60, 50, 80],
                vec![10, 20, 30, 40, 50, 60, 70, 80],
            ),
            (
                PixelFormat::RGBX,
                vec![10, 20, 30, 0, 50, 60, 70, 99],
                vec![10, 20, 30, 255, 50, 60, 70, 255],
            ),
            (
                PixelFormat::BGRX,
                vec![30, 20, 10, 0, 70, 60, 50, 99],
                vec![10, 20, 30, 255, 50, 60, 70, 255],
            ),
        ];

        for (pixel_format, data, expected) in cases {
            let frame = image_test_frame(pixel_format, 2, 1, None, data);
            let png = frame.encode_png().unwrap();
            let (width, height, decoded) = decode_png_rgba(&png);

            assert_eq!((width, height), (2, 1), "{pixel_format:?}");
            assert_eq!(decoded, expected, "{pixel_format:?}");
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_png_skips_padded_rows() {
        let data = vec![
            1, 2, 3, 0, 4, 5, 6, 0, 200, 201, 202, 203, 7, 8, 9, 0, 10, 11, 12, 0, 204, 205, 206,
            207,
        ];
        let frame = image_test_frame(PixelFormat::RGBX, 2, 2, Some(12), data);

        let png = frame.encode_png().unwrap();
        let (width, height, decoded) = decode_png_rgba(&png);

        assert_eq!((width, height), (2, 2));
        assert_eq!(
            decoded,
            vec![1, 2, 3, 255, 4, 5, 6, 255, 7, 8, 9, 255, 10, 11, 12, 255,]
        );
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_jpeg_accepts_supported_image_formats() {
        let cases = [
            (PixelFormat::RGBA, vec![10, 20, 30, 40]),
            (PixelFormat::BGRA, vec![30, 20, 10, 40]),
            (PixelFormat::RGBX, vec![10, 20, 30, 0]),
            (PixelFormat::BGRX, vec![30, 20, 10, 0]),
        ];

        for (pixel_format, pixel) in cases {
            let data = pixel.repeat(16);
            let frame = image_test_frame(pixel_format, 4, 4, None, data);
            let jpeg = frame.encode_jpeg(90).unwrap();
            assert_jpeg_markers(&jpeg);
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_jpeg_skips_padded_rows() {
        let data = vec![
            3, 2, 1, 0, 6, 5, 4, 0, 250, 251, 252, 253, 9, 8, 7, 0, 12, 11, 10, 0, 254, 255, 0, 1,
        ];
        let frame = image_test_frame(PixelFormat::BGRX, 2, 2, Some(12), data);

        let jpeg = frame.encode_jpeg(85).unwrap();
        assert_jpeg_markers(&jpeg);
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_jpeg_rejects_invalid_quality() {
        let frame = image_test_frame(PixelFormat::RGBA, 2, 2, None, vec![0; 16]);

        for quality in [0, 101, 255] {
            let err = frame.encode_jpeg(quality).unwrap_err();
            let err_msg = err.to_string();
            assert!(
                matches!(&err, Error::InvalidFrame(message) if message.contains("quality")),
                "unexpected error for quality {quality}: {err_msg}"
            );
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_jpeg_rejects_oversized_dimensions_before_casting() {
        let wide = image_test_frame(PixelFormat::RGBA, 65_536, 1, None, vec![0; 65_536 * 4]);
        let err = wide.encode_jpeg(85).unwrap_err();
        let err_msg = err.to_string();
        assert!(
            matches!(&err, Error::InvalidFrame(message) if message.contains("JPEG width")),
            "unexpected error: {err_msg}"
        );

        let tall = image_test_frame(PixelFormat::RGBA, 2, 65_536, None, vec![0; 65_536 * 8]);
        let err = tall.encode_jpeg(85).unwrap_err();
        let err_msg = err.to_string();
        assert!(
            matches!(&err, Error::InvalidFrame(message) if message.contains("JPEG height")),
            "unexpected error: {err_msg}"
        );
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_encode_jpeg_rejects_unsupported_format() {
        let frame = image_test_frame(PixelFormat::UYVY, 2, 2, None, vec![0; 8]);

        let err = frame.encode_jpeg(85).unwrap_err();
        let err_msg = err.to_string();
        assert!(
            matches!(&err, Error::InvalidFrame(message) if message.contains("Unsupported format")),
            "unexpected error: {err_msg}"
        );
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn png_conversion_scratch_is_bounded_by_one_row() {
        for format in [
            PixelFormat::RGBA,
            PixelFormat::BGRA,
            PixelFormat::RGBX,
            PixelFormat::BGRX,
        ] {
            for height in [1, 19, 257] {
                let frame =
                    image_test_frame(format, 18, height, Some(84), vec![42; 84 * height as usize]);
                let source = ImagePixelSource::new(frame.layout, frame.data()).unwrap();
                let (scratch, allocations) =
                    crate::test_alloc::allocation_count(|| source.png_conversion_row().unwrap());
                let expected = if format == PixelFormat::RGBA {
                    0
                } else {
                    18 * 4
                };
                assert_eq!(scratch.len(), expected);
                assert_eq!(scratch.capacity(), expected);
                assert_eq!(allocations, usize::from(expected != 0));
                // The JPEG adapter borrows only the source; all component buffers
                // belong to the codec. Pre-reserving them proves conversion itself
                // allocates nothing, independently of image height.
                let mut buffers = std::array::from_fn(|_| Vec::with_capacity(18));
                let adapter = JpegRows {
                    source: &source,
                    width: 18,
                    height: height as u16,
                };
                let (_, allocations) = crate::test_alloc::allocation_count(|| {
                    for row in 0..height as u16 {
                        for buffer in &mut buffers {
                            buffer.clear();
                        }
                        jpeg_encoder::ImageBuffer::fill_buffers(&adapter, row, &mut buffers);
                    }
                });
                assert_eq!(allocations, 0);
            }
        }
    }

    /// Manual resource comparison with the pre-2.0 row-staging implementation.
    /// `cargo test --release --lib image_encoding_resources -- --ignored --nocapture`
    #[cfg(feature = "image-encoding")]
    #[test]
    #[ignore = "Manual optimized image time/peak-allocation comparison"]
    fn image_encoding_resources() {
        use std::{hint::black_box, time::Instant};
        fn staged(source: &ImagePixelSource<'_>, format: ImageFormat) -> Vec<u8> {
            match format {
                ImageFormat::Png => {
                    let mut pixels = Vec::with_capacity(source.width * source.height * 4);
                    for row in source.plane.rows() {
                        for pixel in row.as_chunks::<4>().0 {
                            pixels.extend_from_slice(&source.pixel_format.rgba_pixel(pixel));
                        }
                    }
                    let mut output = Vec::new();
                    let mut encoder =
                        png::Encoder::new(&mut output, source.width as u32, source.height as u32);
                    encoder.set_color(png::ColorType::Rgba);
                    encoder.set_depth(png::BitDepth::Eight);
                    encoder
                        .write_header()
                        .unwrap()
                        .write_image_data(&pixels)
                        .unwrap();
                    output
                }
                ImageFormat::Jpeg(quality) => {
                    let mut pixels = Vec::with_capacity(source.width * source.height * 3);
                    for row in source.plane.rows() {
                        for pixel in row.as_chunks::<4>().0 {
                            pixels.extend_from_slice(&source.pixel_format.rgb_pixel(pixel));
                        }
                    }
                    let mut output = Vec::new();
                    jpeg_encoder::Encoder::new(&mut output, quality)
                        .encode(
                            &pixels,
                            source.width as u16,
                            source.height as u16,
                            jpeg_encoder::ColorType::Rgb,
                        )
                        .unwrap();
                    output
                }
            }
        }
        eprintln!(
            "width,height,padding,entropy,format,path,median_ms,peak_encode_bytes,output_bytes"
        );
        for (width, height) in [(1920, 1080), (3840, 2160), (7680, 4320)] {
            for padding in [0, 64] {
                for entropy in [false, true] {
                    let stride = width * 4 + padding;
                    let mut data = vec![42; stride * height];
                    if entropy {
                        let mut seed = 118u64;
                        for row in data.chunks_exact_mut(stride) {
                            for pixel in row[..width * 4].as_chunks_mut::<4>().0 {
                                for byte in &mut pixel[..3] {
                                    seed ^= seed << 13;
                                    seed ^= seed >> 7;
                                    seed ^= seed << 17;
                                    *byte = seed as u8;
                                }
                                pixel[3] = 255;
                            }
                        }
                    }
                    let frame = image_test_frame(
                        PixelFormat::BGRA,
                        width as i32,
                        height as i32,
                        Some(stride as i32),
                        data,
                    );
                    let source = ImagePixelSource::new(frame.layout, frame.data()).unwrap();
                    for format in [
                        ImageFormat::Png,
                        ImageFormat::Jpeg(1),
                        ImageFormat::Jpeg(85),
                        ImageFormat::Jpeg(100),
                    ] {
                        for old in [true, false] {
                            let mut times = [0.0f64; 3];
                            let mut peak = 0;
                            let mut output_bytes = 0;
                            for time in &mut times {
                                let start = Instant::now();
                                let (output, bytes) = crate::test_alloc::peak_bytes(|| {
                                    if old {
                                        staged(black_box(&source), format)
                                    } else {
                                        match format {
                                            ImageFormat::Png => source.encode_png().unwrap(),
                                            ImageFormat::Jpeg(q) => source.encode_jpeg(q).unwrap(),
                                        }
                                    }
                                });
                                *time = start.elapsed().as_secs_f64() * 1000.0;
                                peak = peak.max(bytes);
                                output_bytes = output.len();
                                black_box(output);
                            }
                            times.sort_by(f64::total_cmp);
                            eprintln!("{width},{height},{padding},{entropy},{format:?},{},{:.3},{peak},{output_bytes}", if old { "staged" } else { "rows" }, times[1]);
                        }
                    }
                }
            }
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn streamed_images_match_independently_packed_pixels() {
        for format in [
            PixelFormat::RGBA,
            PixelFormat::BGRA,
            PixelFormat::RGBX,
            PixelFormat::BGRX,
        ] {
            for (width, height) in [(2, 1), (2, 2), (18, 19), (64, 33)] {
                for padding in [0, 12] {
                    let stride = width * 4 + padding;
                    let mut data = vec![0xCD; stride * height];
                    let mut rgba = Vec::new();
                    let mut rgb = Vec::new();
                    for y in 0..height {
                        for x in 0..width {
                            let r = (x * 17 + y * 7) as u8;
                            let g = (x * 31 + y * 13) as u8;
                            let b = (x * 43 + y * 19) as u8;
                            let a = (x * 59 + y * 23) as u8;
                            let pixel = if matches!(format, PixelFormat::BGRA | PixelFormat::BGRX) {
                                [b, g, r, a]
                            } else {
                                [r, g, b, a]
                            };
                            data[y * stride + x * 4..y * stride + x * 4 + 4]
                                .copy_from_slice(&pixel);
                            rgba.extend_from_slice(&[
                                r,
                                g,
                                b,
                                if matches!(format, PixelFormat::RGBX | PixelFormat::BGRX) {
                                    255
                                } else {
                                    a
                                },
                            ]);
                            rgb.extend_from_slice(&[r, g, b]);
                        }
                    }
                    let frame = image_test_frame(
                        format,
                        width as i32,
                        height as i32,
                        Some(stride as i32),
                        data,
                    );
                    assert_eq!(
                        decode_png_rgba(&frame.encode_png().unwrap()),
                        (width as u32, height as u32, rgba)
                    );
                    for quality in [1, 85, 100] {
                        let mut baseline = Vec::new();
                        jpeg_encoder::Encoder::new(&mut baseline, quality)
                            .encode(
                                &rgb,
                                width as u16,
                                height as u16,
                                jpeg_encoder::ColorType::Rgb,
                            )
                            .unwrap();
                        assert_eq!(
                            frame.encode_jpeg(quality).unwrap(),
                            baseline,
                            "{format:?} {width}x{height} padding={padding} quality={quality}"
                        );
                    }
                    // X and row padding have no effect on any encoded pixels.
                    let mut changed = image_test_frame(
                        format,
                        width as i32,
                        height as i32,
                        Some(stride as i32),
                        frame.data().to_vec(),
                    );
                    for y in 0..height {
                        changed.data_mut()[y * stride + width * 4..(y + 1) * stride].fill(0x12);
                        if matches!(format, PixelFormat::RGBX | PixelFormat::BGRX) {
                            for x in 0..width {
                                changed.data_mut()[y * stride + x * 4 + 3] ^= 0xFF;
                            }
                        }
                    }
                    assert_eq!(frame.encode_png().unwrap(), changed.encode_png().unwrap());
                    assert_eq!(
                        frame.encode_jpeg(85).unwrap(),
                        changed.encode_jpeg(85).unwrap()
                    );
                }
            }
        }
    }

    #[cfg(feature = "image-encoding")]
    #[test]
    fn test_image_pixel_source_rejects_bad_data_len() {
        let layout = ValidatedVideoLayout::new_uncompressed(PixelFormat::RGBA, 2, 1, None).unwrap();
        let err = ImagePixelSource::new(layout, &[0; 7]).unwrap_err();
        let err_msg = err.to_string();
        assert!(
            matches!(&err, Error::InvalidFrame(message) if message.contains("Video data length")),
            "unexpected error: {err_msg}"
        );
    }

    /// Test PixelFormatInfo for packed RGB formats (32 bpp)
    #[test]
    fn test_pixel_format_info_packed_rgb() {
        let formats = [
            PixelFormat::BGRA,
            PixelFormat::BGRX,
            PixelFormat::RGBA,
            PixelFormat::RGBX,
        ];

        for fmt in formats {
            let info = fmt.info();
            assert_eq!(
                info.bytes_per_pixel(),
                4,
                "Format {:?} bytes per pixel",
                fmt
            );
            assert_eq!(
                info.category(),
                FormatCategory::Packed,
                "Format {:?} category",
                fmt
            );
            assert!(
                !info.is_planar_420(),
                "Format {:?} should not be planar",
                fmt
            );

            // 1920x1080, stride = 1920 * 4 = 7680
            let len = info.try_buffer_len(7680, 1080).unwrap();
            assert_eq!(len, 7680 * 1080, "Format {:?} even dimensions", fmt);

            // Odd dimensions: 1921x1081
            let len = info.try_buffer_len(7684, 1081).unwrap();
            assert_eq!(len, 7684 * 1081, "Format {:?} odd dimensions", fmt);
        }
    }

    /// Test PixelFormatInfo for packed YUV formats
    #[test]
    fn test_pixel_format_info_packed_yuv() {
        // UYVY: 16 bpp = 2 bytes per pixel
        let info = PixelFormat::UYVY.info();
        assert_eq!(info.bytes_per_pixel(), 2);
        assert_eq!(info.category(), FormatCategory::Packed);
        let len = info.try_buffer_len(3840, 1080).unwrap();
        assert_eq!(len, 3840 * 1080);

        // UYVA: UYVY plane (2 bytes per pixel) + alpha plane at half stride
        let info = PixelFormat::UYVA.info();
        assert_eq!(info.bytes_per_pixel(), 2);
        assert_eq!(info.category(), FormatCategory::PackedAlpha);
        assert!(!info.is_planar_420());
        let len = info.try_buffer_len(3840, 1080).unwrap();
        assert_eq!(len, 3840 * 1080 + 1920 * 1080);
        // Padded stride: alpha plane follows at stride / 2
        let len = info.try_buffer_len(4096, 1080).unwrap();
        assert_eq!(len, 4096 * 1080 + 2048 * 1080);
        assert!(info.try_buffer_len(3841, 1080).is_err());

        // P216: 16-bit Y plane + 16-bit CbCr plane, both at the line stride
        let info = PixelFormat::P216.info();
        assert_eq!(info.bytes_per_pixel(), 2);
        assert_eq!(info.category(), FormatCategory::SemiPlanar422);
        assert!(!info.is_planar_420());
        let len = info.try_buffer_len(3840, 1080).unwrap();
        assert_eq!(len, 3840 * 1080 * 2);

        // PA16: P216 + 16-bit alpha plane at the line stride
        let info = PixelFormat::PA16.info();
        assert_eq!(info.bytes_per_pixel(), 2);
        assert_eq!(info.category(), FormatCategory::SemiPlanar422Alpha);
        assert!(!info.is_planar_420());
        let len = info.try_buffer_len(3840, 1080).unwrap();
        assert_eq!(len, 3840 * 1080 * 3);
    }

    /// Test PixelFormatInfo for planar YV12/I420 with even dimensions
    #[test]
    fn test_pixel_format_info_planar_420_even() {
        // 1920x1080 YV12/I420
        // Y: 1920 * 1080 = 2,073,600
        // U: (1920/2) * (1080/2) = 960 * 540 = 518,400
        // V: (1920/2) * (1080/2) = 960 * 540 = 518,400
        // Total: 2,073,600 + 518,400 + 518,400 = 3,110,400
        let y_stride = 1920;

        let info = PixelFormat::YV12.info();
        assert_eq!(info.bytes_per_pixel(), 1);
        assert_eq!(info.category(), FormatCategory::Planar420);
        assert!(info.is_planar_420());
        let len = info.try_buffer_len(y_stride, 1080).unwrap();
        assert_eq!(len, 3_110_400, "YV12 1920x1080");

        let info = PixelFormat::I420.info();
        assert_eq!(info.category(), FormatCategory::Planar420);
        let len = info.try_buffer_len(y_stride, 1080).unwrap();
        assert_eq!(len, 3_110_400, "I420 1920x1080");
    }

    /// Test PixelFormatInfo rejects planar YV12/I420 with odd layout inputs
    #[test]
    fn test_pixel_format_info_planar_420_odd() {
        let y_stride = 1921;

        assert!(PixelFormat::YV12
            .info()
            .try_buffer_len(y_stride, 1081)
            .is_err());
        assert!(PixelFormat::I420
            .info()
            .try_buffer_len(y_stride, 1081)
            .is_err());
    }

    /// Test PixelFormatInfo for semi-planar NV12 with even dimensions
    #[test]
    fn test_pixel_format_info_nv12_even() {
        // 1920x1080 NV12
        // Y: 1920 * 1080 = 2,073,600
        // UV: 1920 * (1080/2) = 1920 * 540 = 1,036,800
        // Total: 2,073,600 + 1,036,800 = 3,110,400
        let y_stride = 1920;

        let info = PixelFormat::NV12.info();
        assert_eq!(info.bytes_per_pixel(), 1);
        assert_eq!(info.category(), FormatCategory::SemiPlanar420);
        assert!(info.is_planar_420());
        let len = info.try_buffer_len(y_stride, 1080).unwrap();
        assert_eq!(len, 3_110_400, "NV12 1920x1080");
    }

    /// Test PixelFormatInfo rejects semi-planar NV12 with odd layout inputs
    #[test]
    fn test_pixel_format_info_nv12_odd() {
        let y_stride = 1921;
        assert!(PixelFormat::NV12
            .info()
            .try_buffer_len(y_stride, 1081)
            .is_err());
    }

    /// Test PixelFormat::line_stride for all formats
    #[test]
    fn test_pixel_format_line_stride() {
        // Packed RGB: 4 bytes per pixel
        assert_eq!(PixelFormat::BGRA.try_line_stride(1920).unwrap(), 7680);
        assert_eq!(PixelFormat::BGRX.try_line_stride(1920).unwrap(), 7680);
        assert_eq!(PixelFormat::RGBA.try_line_stride(1920).unwrap(), 7680);
        assert_eq!(PixelFormat::RGBX.try_line_stride(1920).unwrap(), 7680);

        // UYVY: 2 bytes per pixel
        assert_eq!(PixelFormat::UYVY.try_line_stride(1920).unwrap(), 3840);

        // UYVA: UYVY plane stride = 2 bytes per pixel
        assert_eq!(PixelFormat::UYVA.try_line_stride(1920).unwrap(), 3840);

        // P216/PA16: Y-plane stride = 2 bytes per pixel
        assert_eq!(PixelFormat::P216.try_line_stride(1920).unwrap(), 3840);
        assert_eq!(PixelFormat::PA16.try_line_stride(1920).unwrap(), 3840);

        // Planar 4:2:0: Y-plane stride = 1 byte per pixel
        assert_eq!(PixelFormat::YV12.try_line_stride(1920).unwrap(), 1920);
        assert_eq!(PixelFormat::I420.try_line_stride(1920).unwrap(), 1920);
        assert_eq!(PixelFormat::NV12.try_line_stride(1920).unwrap(), 1920);
    }

    /// Test PixelFormat::buffer_size for all formats
    #[test]
    fn test_pixel_format_buffer_size() {
        // Packed RGB: width * 4 * height
        assert_eq!(
            PixelFormat::BGRA.try_buffer_size(1920, 1080).unwrap(),
            8_294_400
        );
        assert_eq!(
            PixelFormat::RGBA.try_buffer_size(1920, 1080).unwrap(),
            8_294_400
        );

        // Planar 4:2:0: Y + U + V = 1.5 * width * height
        assert_eq!(
            PixelFormat::YV12.try_buffer_size(1920, 1080).unwrap(),
            3_110_400
        );
        assert_eq!(
            PixelFormat::I420.try_buffer_size(1920, 1080).unwrap(),
            3_110_400
        );

        // Semi-planar 4:2:0: Y + UV = 1.5 * width * height
        assert_eq!(
            PixelFormat::NV12.try_buffer_size(1920, 1080).unwrap(),
            3_110_400
        );

        // UYVA: UYVY + alpha = 3 * width * height
        assert_eq!(
            PixelFormat::UYVA.try_buffer_size(1920, 1080).unwrap(),
            6_220_800
        );

        // Semi-planar 4:2:2 16-bit: Y + CbCr = 4 * width * height
        assert_eq!(
            PixelFormat::P216.try_buffer_size(1920, 1080).unwrap(),
            8_294_400
        );

        // Semi-planar 4:2:2 16-bit with alpha: Y + CbCr + A = 6 * width * height
        assert_eq!(
            PixelFormat::PA16.try_buffer_size(1920, 1080).unwrap(),
            12_441_600
        );
    }

    /// Test PixelFormatInfo::is_planar_420 helper
    #[test]
    fn test_pixel_format_info_is_planar_420() {
        assert!(PixelFormat::YV12.info().is_planar_420());
        assert!(PixelFormat::I420.info().is_planar_420());
        assert!(PixelFormat::NV12.info().is_planar_420());

        assert!(!PixelFormat::BGRA.info().is_planar_420());
        assert!(!PixelFormat::RGBA.info().is_planar_420());
        assert!(!PixelFormat::UYVY.info().is_planar_420());
        assert!(!PixelFormat::UYVA.info().is_planar_420());
    }

    /// Test VideoFrame builder with planar formats produces correct buffer sizes
    #[test]
    fn test_videoframe_builder_planar_even() {
        let frame = VideoFrame::builder()
            .resolution(1920, 1080)
            .pixel_format(PixelFormat::NV12)
            .build()
            .expect("Builder should succeed");

        assert_eq!(frame.width(), 1920);
        assert_eq!(frame.height(), 1080);
        assert_eq!(frame.pixel_format(), PixelFormat::NV12);
        assert_eq!(frame.data().len(), 3_110_400, "NV12 1920x1080 buffer size");
    }

    #[test]
    fn test_video_dimensions_across_all_formats() {
        let formats = [
            PixelFormat::BGRA,
            PixelFormat::BGRX,
            PixelFormat::RGBA,
            PixelFormat::RGBX,
            PixelFormat::UYVY,
            PixelFormat::UYVA,
            PixelFormat::P216,
            PixelFormat::PA16,
            PixelFormat::YV12,
            PixelFormat::I420,
            PixelFormat::NV12,
        ];
        let mut data = vec![0u8; 4096];
        for format in formats {
            for (width, height) in [(0, 2), (-2, 2), (1, 2), (3, 2), (2, 0), (2, -1)] {
                assert!(
                    format.try_buffer_size(width, height).is_err(),
                    "{format:?} {width}x{height}"
                );
                assert!(VideoFrame::builder()
                    .resolution(width, height)
                    .pixel_format(format)
                    .build()
                    .is_err());
                assert!(crate::BorrowedVideoFrame::try_from_uncompressed(
                    &data, width, height, format, 30, 1
                )
                .is_err());
                let raw = NDIlib_video_frame_v2_t {
                    xres: width,
                    yres: height,
                    FourCC: format.into(),
                    frame_rate_N: 30,
                    frame_rate_D: 1,
                    picture_aspect_ratio: 0.0,
                    frame_format_type: ScanType::Progressive.into(),
                    timecode: 0,
                    p_data: data.as_mut_ptr(),
                    __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                        line_stride_in_bytes: 128,
                    },
                    p_metadata: ptr::null(),
                    timestamp: 0,
                };
                assert!(matches!(
                    validate_video_layout(&raw),
                    Err(Error::InvalidFrame(_))
                ));
                // Reject before forming a slice or copying received bytes.
                assert!(unsafe { VideoFrame::from_raw(&raw) }.is_err());
            }
            for width in [0, -2, 1, 3] {
                assert!(
                    format.try_line_stride(width).is_err(),
                    "{format:?} width={width}"
                );
            }
            for height in [1, 2, 3] {
                let valid = !format.info().is_planar_420() || height % 2 == 0;
                assert_eq!(format.try_buffer_size(2, height).is_ok(), valid);
                assert_eq!(
                    VideoFrame::builder()
                        .resolution(2, height)
                        .pixel_format(format)
                        .build()
                        .is_ok(),
                    valid
                );
                assert_eq!(
                    crate::BorrowedVideoFrame::try_from_uncompressed(
                        &data, 2, height, format, 30, 1
                    )
                    .is_ok(),
                    valid
                );
            }
            // Even width does not imply a larger alignment requirement.
            assert!(format.try_line_stride(6).is_ok());
            assert!(ValidatedVideoLayout::new_uncompressed(format, 6, 2, Some(128)).is_ok());
        }
        // RGB row padding need not be divisible by two or by a pixel size.
        assert!(ValidatedVideoLayout::new_uncompressed(PixelFormat::BGRA, 2, 3, Some(9)).is_ok());
    }

    /// Test VideoFrame builder rejects planar formats with odd dimensions
    #[test]
    fn test_videoframe_builder_planar_odd() {
        let result = VideoFrame::builder()
            .resolution(1921, 1081)
            .pixel_format(PixelFormat::I420)
            .build();

        assert!(
            matches!(result, Err(Error::InvalidFrame(_))),
            "Planar 4:2:0 odd dimensions should be rejected"
        );
    }

    /// Test VideoFrame builder with packed format (regression test)
    #[test]
    fn test_videoframe_builder_packed() {
        let frame = VideoFrame::builder()
            .resolution(1920, 1080)
            .pixel_format(PixelFormat::BGRA)
            .build()
            .expect("Builder should succeed");

        assert_eq!(frame.width(), 1920);
        assert_eq!(frame.height(), 1080);
        assert_eq!(frame.pixel_format(), PixelFormat::BGRA);
        assert_eq!(
            frame.data().len(),
            1920 * 1080 * 4,
            "BGRA buffer size unchanged"
        );
    }

    /// Test VideoFrame builder hands the SDK the first-plane stride for 4:2:2
    /// formats with extra planes
    #[test]
    fn test_videoframe_builder_semi_planar_422_and_alpha() {
        for (format, expected_len) in [
            (PixelFormat::UYVA, 256 * 2 * 64 + 256 * 64),
            (PixelFormat::P216, 256 * 2 * 64 * 2),
            (PixelFormat::PA16, 256 * 2 * 64 * 3),
        ] {
            let frame = VideoFrame::builder()
                .resolution(256, 64)
                .pixel_format(format)
                .build()
                .expect("Builder should succeed");

            assert_eq!(
                frame.line_stride_or_size(),
                LineStrideOrSize::LineStrideBytes(256 * 2),
                "{format:?} line stride"
            );
            assert_eq!(frame.data().len(), expected_len, "{format:?} buffer size");
        }
    }

    /// Test VideoFrame::from_raw with synthetic NV12 frame
    #[test]
    fn test_videoframe_from_raw_nv12() {
        // Create a synthetic NV12 frame
        let width = 1920;
        let height = 1080;
        let y_stride = 1920;
        let expected_size = 3_110_400; // Y + UV for NV12

        let mut data = vec![0u8; expected_size];
        // Mark the last byte to verify it's copied
        data[expected_size - 1] = 0xFF;

        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::NV12.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: y_stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let frame = unsafe { VideoFrame::from_raw(&c_frame) }.expect("from_raw should succeed");

        assert_eq!(frame.width(), width);
        assert_eq!(frame.height(), height);
        assert_eq!(frame.pixel_format(), PixelFormat::NV12);
        assert_eq!(
            frame.data().len(),
            expected_size,
            "Should copy full Y+UV buffer"
        );
        assert_eq!(
            frame.data()[expected_size - 1],
            0xFF,
            "Last byte should be copied"
        );
    }

    /// Test VideoFrame::from_raw rejects synthetic I420 frame with odd dimensions
    #[test]
    fn test_videoframe_from_raw_i420_odd() {
        let width = 1921;
        let height = 1081;
        let y_stride = 1921;
        let expected_size = 3_116_403; // Y + U + V with ceiling division

        let mut data = vec![0u8; expected_size];

        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::I420.into(),
            frame_rate_N: 30,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: y_stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = unsafe { VideoFrame::from_raw(&c_frame) };
        assert!(
            matches!(result, Err(Error::InvalidFrame(_))),
            "Planar 4:2:0 odd dimensions should be rejected"
        );
    }

    /// Regression test: VideoFrame::from_raw with packed format should be unchanged
    #[test]
    fn test_videoframe_from_raw_packed_regression() {
        let width = 1920;
        let height = 1080;
        let stride = 1920 * 4; // BGRA
        let expected_size = (stride * height) as usize;

        let mut data = vec![0u8; expected_size];

        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let frame = unsafe { VideoFrame::from_raw(&c_frame) }.expect("from_raw should succeed");
        assert_eq!(
            frame.data().len(),
            expected_size,
            "BGRA buffer size unchanged"
        );
    }

    /// Test that VideoFrameRef::new rejects unknown FourCC
    #[test]
    fn test_videoframeref_unknown_fourcc() {
        use crate::capture::{Guard, VideoKind};

        let width = 1920;
        let height = 1080;
        let stride = 1920 * 4;
        let expected_size = (stride * height) as usize;
        let mut data = vec![0u8; expected_size];

        // Use an unknown FourCC value (0xDEADBEEF)
        // On Windows FourCC is i32, on Linux it's u32
        #[allow(clippy::unnecessary_cast)]
        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            #[cfg(target_os = "windows")]
            FourCC: 0xDEADBEEFu32 as i32, // Unknown FourCC
            #[cfg(not(target_os = "windows"))]
            FourCC: 0xDEADBEEF, // Unknown FourCC
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        // Create a mock receiver instance (null is fine for this test since we don't free)
        let mock_instance = ptr::null_mut();
        let guard = unsafe { Guard::<VideoKind>::new(mock_instance, c_frame) };

        // VideoFrameRef::new should return an error for unknown FourCC
        let result = unsafe { VideoFrameRef::new(guard) };
        assert!(result.is_err(), "Should reject unknown FourCC");

        if let Err(Error::InvalidFrame(ref msg)) = result {
            assert!(
                msg.contains("0xDEADBEEF"),
                "Error message should include FourCC: {}",
                msg
            );
        } else {
            panic!("Expected InvalidFrame error");
        }

        // Manually free to prevent guard from calling NDI free on null instance
        std::mem::forget(result);
    }

    /// Test that VideoFrameRef::new accepts known FourCC and stores validated format
    #[test]
    fn test_videoframeref_known_fourcc() {
        use crate::capture::{Guard, VideoKind};

        let width = 1920;
        let height = 1080;
        let stride = 1920 * 4;
        let expected_size = (stride * height) as usize;
        let mut data = vec![0u8; expected_size];

        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let mock_instance = ptr::null_mut();
        let guard = unsafe { Guard::<VideoKind>::new(mock_instance, c_frame) };

        let frame_ref = unsafe { VideoFrameRef::new(guard) }.expect("Should accept BGRA FourCC");
        assert_eq!(
            frame_ref.pixel_format(),
            PixelFormat::BGRA,
            "Should store validated pixel format"
        );

        // Manually free to prevent guard from calling NDI free on null instance
        std::mem::forget(frame_ref);
    }

    /// Test that AudioFrameRef::new rejects unknown FourCC
    #[test]
    fn test_audioframeref_unknown_fourcc() {
        use crate::recv_guard::RecvAudioGuard;

        let num_samples = 1024;
        let num_channels = 2;
        let sample_count = (num_samples * num_channels) as usize;
        let mut data = vec![0.0f32; sample_count];

        // Use an unknown FourCC value (0xBADC0DE)
        let c_frame = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: num_channels,
            no_samples: num_samples,
            timecode: 0,
            FourCC: 0xBADC0DE, // Unknown audio FourCC
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: num_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let mock_instance = ptr::null_mut();
        let guard = unsafe { RecvAudioGuard::new(mock_instance, c_frame) };

        let result = unsafe { AudioFrameRef::new(guard) };
        assert!(result.is_err(), "Should reject unknown audio FourCC");

        if let Err(Error::InvalidFrame(ref msg)) = result {
            assert!(
                msg.contains("0x0BADC0DE"),
                "Error message should include FourCC: {}",
                msg
            );
        } else {
            panic!("Expected InvalidFrame error");
        }

        std::mem::forget(result);
    }

    /// Test that AudioFrameRef::new accepts known FourCC and stores validated format
    #[test]
    fn test_audioframeref_known_fourcc() {
        use crate::recv_guard::RecvAudioGuard;

        let num_samples = 1024;
        let num_channels = 2;
        let sample_count = (num_samples * num_channels) as usize;
        let mut data = vec![0.0f32; sample_count];

        let c_frame = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: num_channels,
            no_samples: num_samples,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: num_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let mock_instance = ptr::null_mut();
        let guard = unsafe { RecvAudioGuard::new(mock_instance, c_frame) };

        let frame_ref = unsafe { AudioFrameRef::new(guard) }.expect("Should accept FLTP FourCC");
        assert_eq!(
            frame_ref.format(),
            AudioFormat::FLTP,
            "Should store validated audio format"
        );

        std::mem::forget(frame_ref);
    }

    /// Test that VideoFrameRef correctly uses validated format for data size calculation
    #[test]
    fn test_videoframeref_data_uses_validated_format() {
        use crate::capture::{Guard, VideoKind};

        // Test with uncompressed format (BGRA)
        let width = 1920;
        let height = 1080;
        let stride = 1920 * 4;
        let expected_size = (stride * height) as usize;
        let mut data = vec![0xAB_u8; expected_size];

        let c_frame = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let mock_instance = ptr::null_mut();
        let guard = unsafe { Guard::<VideoKind>::new(mock_instance, c_frame) };
        let frame_ref = unsafe { VideoFrameRef::new(guard) }.expect("Should create frame ref");

        // Verify data() returns correct size based on validated format
        assert_eq!(
            frame_ref.data().unwrap().len(),
            expected_size,
            "data() should use validated pixel format for size calculation"
        );

        // Verify line_stride_or_size() uses validated format
        assert_eq!(
            frame_ref.line_stride_or_size(),
            LineStrideOrSize::LineStrideBytes(stride),
            "line_stride_or_size() should use validated format"
        );

        std::mem::forget(frame_ref);
    }

    /// Regression lock against the receiver and FrameSync video refs re-diverging:
    /// given byte-identical raw frames, every shared accessor (including the
    /// previously-divergent `scan_type`) must return identical results now that
    /// both spellings share one [`VideoRef`] core.
    #[test]
    fn test_receiver_and_framesync_video_refs_agree() {
        use crate::capture::{FrameSyncVideoFree, Guard, VideoKind};

        let width = 16;
        let height = 8;
        let stride = width * 4;
        let len = (stride * height) as usize;

        // Two independent buffers with identical content, so each ref owns a
        // distinct (non-aliasing) frame while still comparing equal.
        let mut recv_data: Vec<u8> = (0..len).map(|i| (i % 251) as u8).collect();
        let mut fs_data = recv_data.clone();
        let mut recv_meta = b"shared frame\0".to_vec();
        let mut fs_meta = recv_meta.clone();

        let raw = |data: &mut [u8], meta: &mut [u8]| NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 30,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            // A non-default scan type: the old FrameSync copy used
            // `unwrap_or(Progressive)`, so this also guards that divergence.
            frame_format_type: ScanType::Interlaced.into(),
            timecode: 123,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: meta.as_mut_ptr().cast(),
            timestamp: 456,
        };

        let recv_raw = raw(&mut recv_data, &mut recv_meta);
        let fs_raw = raw(&mut fs_data, &mut fs_meta);

        let recv_guard = unsafe { Guard::<VideoKind>::new(ptr::null_mut(), recv_raw) };
        let recv = unsafe { VideoFrameRef::new(recv_guard) }.expect("receiver video ref");
        let fs_guard = unsafe { Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), fs_raw) };
        let fs =
            unsafe { VideoRef::<FrameSyncVideoFree>::new(fs_guard) }.expect("framesync video ref");

        assert_eq!(recv.width(), fs.width());
        assert_eq!(recv.height(), fs.height());
        assert_eq!(recv.pixel_format(), fs.pixel_format());
        assert_eq!(recv.frame_rate_n(), fs.frame_rate_n());
        assert_eq!(recv.frame_rate_d(), fs.frame_rate_d());
        assert_eq!(recv.picture_aspect_ratio(), fs.picture_aspect_ratio());
        assert_eq!(recv.scan_type(), fs.scan_type());
        assert_eq!(recv.scan_type(), ScanType::Interlaced);
        assert_eq!(recv.timecode(), fs.timecode());
        assert_eq!(recv.timestamp(), fs.timestamp());
        assert_eq!(recv.line_stride_or_size(), fs.line_stride_or_size());
        assert_eq!(recv.metadata(), fs.metadata());
        assert_eq!(recv.data(), fs.data());

        // The receiver guard would call the SDK free with a null instance; leak
        // both refs to keep the unit test off the FFI free path.
        std::mem::forget(recv);
        std::mem::forget(fs);
    }

    /// An out-of-range `frame_format_type` must be rejected by `validate_video_layout`
    /// before either video ref is constructed. This is what makes the unified
    /// `scan_type()` `.expect(...)` policy sound: the unknown branch is unreachable.
    #[test]
    fn test_video_ref_rejects_out_of_range_scan_type() {
        use crate::capture::{FrameSyncVideoFree, Guard, VideoKind};

        let width = 16;
        let height = 8;
        let stride = width * 4;
        let len = (stride * height) as usize;
        let mut recv_data = vec![0u8; len];
        let mut fs_data = vec![0u8; len];

        let raw = |data: &mut [u8]| NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 30,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: 0x0BAD_F00D, // not a valid NDIlib_frame_format_type_e
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        // Layout validation rejects it directly...
        assert!(matches!(
            validate_video_layout(&raw(&mut recv_data)),
            Err(Error::InvalidFrame(_))
        ));

        // ...and so both ref constructors fail before any `scan_type()` call.
        let recv_guard = unsafe { Guard::<VideoKind>::new(ptr::null_mut(), raw(&mut recv_data)) };
        assert!(matches!(
            unsafe { VideoFrameRef::new(recv_guard) },
            Err(Error::InvalidFrame(_))
        ));

        let fs_guard =
            unsafe { Guard::<FrameSyncVideoFree>::new(ptr::null_mut(), raw(&mut fs_data)) };
        assert!(matches!(
            unsafe { VideoRef::<FrameSyncVideoFree>::new(fs_guard) },
            Err(Error::InvalidFrame(_))
        ));
    }

    /// Test that MAX_VIDEO_BYTES constant is properly defined
    #[test]
    fn test_max_video_bytes_constant() {
        // Verify the crate resource cap is set to 256 MiB
        assert_eq!(MAX_VIDEO_BYTES, 256 * 1024 * 1024);
    }

    /// Test that MAX_AUDIO_BYTES constant is properly defined
    #[test]
    fn test_max_audio_bytes_constant() {
        // Verify the constant is set to 64 MiB as specified
        assert_eq!(MAX_AUDIO_BYTES, 64 * 1024 * 1024);
    }

    /// Test that MAX_METADATA_BYTES constant is properly defined.
    #[test]
    fn test_max_metadata_bytes_constant() {
        assert_eq!(MAX_METADATA_BYTES, 4 * 1024 * 1024);
    }

    fn metadata_raw_from_bytes(data: &mut [u8], length: i32) -> NDIlib_metadata_frame_t {
        NDIlib_metadata_frame_t {
            length,
            timecode: 12345,
            p_data: data.as_mut_ptr().cast::<c_char>(),
        }
    }

    fn null_metadata_raw(length: i32) -> NDIlib_metadata_frame_t {
        NDIlib_metadata_frame_t {
            length,
            timecode: 12345,
            p_data: ptr::null_mut(),
        }
    }

    #[test]
    fn test_validate_metadata_layout_accepts_empty_null_frame() {
        let raw = null_metadata_raw(0);
        let layout = unsafe { validate_metadata_layout(&raw) }.expect("empty null frame is valid");

        assert_eq!(
            layout,
            ValidatedMetadataLayout {
                len_with_nul: 0,
                text_len: 0,
            }
        );
    }

    #[test]
    fn test_validate_metadata_layout_accepts_one_byte_empty_payload() {
        let mut data = vec![0u8];
        let raw = metadata_raw_from_bytes(&mut data, 1);
        let layout =
            unsafe { validate_metadata_layout(&raw) }.expect("explicit empty payload is valid");

        assert_eq!(layout.len_with_nul, 1);
        assert_eq!(layout.text_len, 0);
    }

    #[test]
    fn test_validate_metadata_layout_accepts_utf8_with_bounded_length() {
        let mut data = "<ndi tally=\"preview\"/>".as_bytes().to_vec();
        data.push(0);
        let length = data.len() as i32;
        let raw = metadata_raw_from_bytes(&mut data, length);
        let layout = unsafe { validate_metadata_layout(&raw) }.expect("valid UTF-8 metadata");

        assert_eq!(layout.len_with_nul, data.len());
        assert_eq!(layout.text_len, data.len() - 1);
    }

    #[test]
    fn test_validate_metadata_layout_ignores_bytes_after_length() {
        let mut data = b"ok\0\0\xFF".to_vec();
        let raw = metadata_raw_from_bytes(&mut data, 3);
        let layout =
            unsafe { validate_metadata_layout(&raw) }.expect("extra bytes after length ignored");

        assert_eq!(layout.text_len, 2);
        let owned = unsafe { MetadataFrame::from_raw_validated(&raw, layout) };
        assert_eq!(owned.data(), "ok");
    }

    #[test]
    fn test_validate_metadata_layout_rejects_negative_length() {
        let raw = null_metadata_raw(-1);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_metadata_layout_accepts_lengthless_non_null_data() {
        let mut data = b"<ndi/>\0ignored".to_vec();
        let raw = metadata_raw_from_bytes(&mut data, 0);
        let layout = unsafe { validate_metadata_layout(&raw) }.expect("SDK C-string sentinel");
        assert_eq!(layout.text_len, 6);
        assert_eq!(layout.len_with_nul, 7);
        let owned = unsafe { MetadataFrame::from_raw_validated(&raw, layout) };
        assert_eq!(owned.data(), "<ndi/>");
    }

    #[test]
    fn test_lengthless_metadata_rejects_invalid_utf8_and_missing_nul() {
        let mut invalid = vec![0xff, 0];
        assert!(matches!(
            unsafe { validate_metadata_layout(&metadata_raw_from_bytes(&mut invalid, 0)) },
            Err(Error::InvalidUtf8(_))
        ));
        let mut unterminated = vec![b'x'; MAX_METADATA_BYTES];
        assert!(unsafe {
            validate_metadata_layout(&metadata_raw_from_bytes(&mut unterminated, 0))
        }
        .is_err());
    }

    #[test]
    fn test_validate_metadata_layout_rejects_nonzero_length_null_data() {
        let raw = null_metadata_raw(1);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_metadata_layout_rejects_missing_trailing_nul() {
        let mut data = b"abc".to_vec();
        let length = data.len() as i32;
        let raw = metadata_raw_from_bytes(&mut data, length);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_metadata_layout_rejects_interior_nul() {
        let mut data = b"a\0b\0".to_vec();
        let length = data.len() as i32;
        let raw = metadata_raw_from_bytes(&mut data, length);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_metadata_layout_rejects_oversized_length_before_reading() {
        let mut data = vec![0u8];
        let raw = metadata_raw_from_bytes(&mut data, (MAX_METADATA_BYTES + 1) as i32);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_metadata_layout_rejects_invalid_utf8() {
        let mut data = vec![0xFF, 0];
        let length = data.len() as i32;
        let raw = metadata_raw_from_bytes(&mut data, length);

        assert!(matches!(
            unsafe { validate_metadata_layout(&raw) },
            Err(Error::InvalidUtf8(_))
        ));
    }

    #[test]
    fn test_metadata_frame_constructor_and_accessors_preserve_text() {
        let frame = MetadataFrame::with_data("<ndi_product/>", 9876).unwrap();

        assert_eq!(frame.data(), "<ndi_product/>");
        assert_eq!(frame.timecode(), 9876);
        assert_eq!(frame.clone().into_data(), "<ndi_product/>");
    }

    #[test]
    fn test_metadata_frame_rejects_interior_nul_input() {
        assert!(matches!(
            MetadataFrame::with_data("bad\0metadata", 0),
            Err(Error::InvalidCString(_))
        ));

        let mut frame = MetadataFrame::new();
        assert!(matches!(
            frame.set_data("bad\0metadata"),
            Err(Error::InvalidCString(_))
        ));
    }

    #[test]
    fn test_metadata_frame_rejects_oversized_input() {
        let oversized = "x".repeat(MAX_METADATA_BYTES);

        assert!(matches!(
            MetadataFrame::with_data(oversized, 0),
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_metadata_frame_setters_preserve_invariants() {
        let mut frame = MetadataFrame::new();

        frame.set_data("updated").unwrap();
        frame.set_timecode(42);

        assert_eq!(frame.data(), "updated");
        assert_eq!(frame.timecode(), 42);
        assert_eq!(MetadataFrame::new().with_timecode(7).timecode(), 7);
        assert!(frame.set_data("bad\0text").is_err());
        assert_eq!(frame.data(), "updated");
    }

    #[test]
    fn validated_metadata_reuses_storage_and_copies_once() {
        let text = "é".repeat(550);
        let frame = MetadataFrame::with_data(text, 9).unwrap();
        let expected = frame.data.as_ptr() as *mut c_char;
        let ((), allocations) = crate::test_alloc::allocation_count(|| {
            for _ in 0..100 {
                let raw = frame.to_raw();
                assert_eq!(raw.p_data, expected);
                assert_eq!(raw.length, 1101);
                assert_eq!(frame.data().len(), 1100);
            }
        });
        assert_eq!(allocations, 0);

        let bytes = frame.data.inner.as_bytes_with_nul();
        let layout = ValidatedFrameMetadata {
            len_with_nul: NonZeroUsize::new(bytes.len()),
            text_len: bytes.len() - 1,
        };
        let (copy, allocations) = crate::test_alloc::allocation_count(|| unsafe {
            FrameMetadata::copy_from_raw_validated(bytes.as_ptr().cast(), layout).unwrap()
        });
        assert_eq!(allocations, 1);
        assert_eq!(copy.as_str(), frame.data());
        let (text, allocations) = crate::test_alloc::allocation_count(|| copy.into_string());
        assert_eq!(allocations, 0);
        assert_eq!(text, frame.data());
    }

    #[test]
    fn test_metadata_frame_from_raw_validated_copies_only_payload() {
        let mut data = b"copy-me\0\0\xFF".to_vec();
        let raw = metadata_raw_from_bytes(&mut data, 8);
        let layout = unsafe { validate_metadata_layout(&raw) }.unwrap();
        let frame = unsafe { MetadataFrame::from_raw_validated(&raw, layout) };

        assert_eq!(frame.data(), "copy-me");
        assert_eq!(frame.timecode(), 12345);
    }

    #[test]
    fn test_metadata_frame_from_raw_reports_invalid_utf8() {
        let mut data = vec![0xFF, 0];
        let raw = metadata_raw_from_bytes(&mut data, 2);

        assert!(matches!(
            unsafe { MetadataFrame::from_raw(&raw) },
            Err(Error::InvalidUtf8(_))
        ));
    }

    #[test]
    fn test_metadata_frame_to_raw_includes_trailing_nul() {
        let frame = MetadataFrame::with_data("abc", 101).unwrap();
        let raw = frame.to_raw();

        assert_eq!(raw.length, 4);
        assert_eq!(raw.timecode, 101);
        assert_eq!(raw.p_data, frame.data.as_ptr() as *mut c_char);
        assert_eq!(frame.data.inner.as_bytes_with_nul(), b"abc\0");
    }

    #[test]
    fn test_empty_metadata_frame_to_raw_sends_explicit_nul() {
        let frame = MetadataFrame::new();
        let raw = frame.to_raw();

        assert_eq!(raw.length, 1);
        assert_eq!(frame.data.inner.as_bytes_with_nul(), b"\0");
    }

    #[test]
    fn test_metadata_raw_length_conversion_is_checked() {
        assert!(metadata_len_to_i32(i32::MAX as usize).is_ok());
        assert!(matches!(
            metadata_len_to_i32(i32::MAX as usize + 1),
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_metadata_frame_ref_uses_cached_layout() {
        use crate::capture::RecvMetadataGuard;

        let mut data = b"zero-copy\0\0\xFF".to_vec();
        let raw = metadata_raw_from_bytes(&mut data, 10);
        let guard = unsafe { RecvMetadataGuard::new(ptr::null_mut(), raw) };
        let frame_ref = unsafe { MetadataFrameRef::new(guard) }.expect("valid metadata ref");

        assert_eq!(frame_ref.data(), "zero-copy");
        assert_eq!(frame_ref.as_bytes(), b"zero-copy");
        assert_eq!(frame_ref.layout.text_len, 9);

        let owned = frame_ref.to_owned();
        assert_eq!(owned.data(), "zero-copy");
        assert_eq!(owned.timecode(), 12345);

        std::mem::forget(frame_ref);
    }

    #[test]
    fn test_validate_frame_metadata_accepts_null_without_allocation_state() {
        let layout = unsafe { validate_frame_metadata(ptr::null()) }.expect("null is valid");

        assert_eq!(
            layout,
            ValidatedFrameMetadata {
                len_with_nul: None,
                text_len: 0,
            }
        );
    }

    #[test]
    fn test_validate_frame_metadata_accepts_explicit_empty() {
        let mut data = b"\0".to_vec();
        let layout = unsafe { validate_frame_metadata(data.as_mut_ptr().cast::<c_char>()) }
            .expect("explicit empty metadata is valid");

        assert_eq!(layout.len_with_nul.unwrap().get(), 1);
        assert_eq!(layout.text_len, 0);
        assert_eq!(
            unsafe { frame_metadata_str(data.as_ptr().cast::<c_char>(), layout) },
            Some("")
        );
    }

    #[test]
    fn test_validate_frame_metadata_accepts_utf8_and_ignores_after_first_nul() {
        let mut data = b"hello metadata\0\0\xFF".to_vec();
        let layout = unsafe { validate_frame_metadata(data.as_mut_ptr().cast::<c_char>()) }
            .expect("valid UTF-8 metadata");

        assert_eq!(layout.text_len, "hello metadata".len());
        assert_eq!(
            unsafe { frame_metadata_str(data.as_ptr().cast::<c_char>(), layout) },
            Some("hello metadata")
        );
    }

    #[test]
    fn test_validate_frame_metadata_accepts_max_boundary() {
        let mut data = vec![b'x'; MAX_METADATA_BYTES];
        data[MAX_METADATA_BYTES - 1] = 0;

        let layout = unsafe { validate_frame_metadata(data.as_mut_ptr().cast::<c_char>()) }
            .expect("metadata exactly at cap including terminator is valid");

        assert_eq!(layout.len_with_nul.unwrap().get(), MAX_METADATA_BYTES);
        assert_eq!(layout.text_len, MAX_METADATA_BYTES - 1);
    }

    #[test]
    fn test_validate_frame_metadata_rejects_missing_nul_within_cap() {
        let mut data = vec![b'x'; MAX_METADATA_BYTES];

        assert!(matches!(
            unsafe { validate_frame_metadata(data.as_mut_ptr().cast::<c_char>()) },
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_validate_frame_metadata_rejects_invalid_utf8_before_nul() {
        let mut data = vec![0xFF, 0];

        assert!(matches!(
            unsafe { validate_frame_metadata(data.as_mut_ptr().cast::<c_char>()) },
            Err(Error::InvalidUtf8(_))
        ));
    }

    #[test]
    fn test_video_frame_ref_metadata_is_cached_and_owned_conversion_appends_nul() {
        use crate::capture::{Guard, VideoKind};

        let width = 16;
        let height = 8;
        let stride = width * 4;
        let expected_len = (stride * height) as usize;
        let data = vec![0u8; expected_len];
        let mut metadata = b"cached\0\xFF".to_vec();

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 123,
            p_data: data.as_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: metadata.as_mut_ptr().cast::<c_char>(),
            timestamp: 456,
        };

        let guard = unsafe { Guard::<VideoKind>::new(ptr::null_mut(), raw) };
        let frame_ref = unsafe { VideoFrameRef::new(guard) }.expect("valid video ref");

        assert_eq!(frame_ref.metadata(), Some("cached"));
        metadata[6] = b'!';
        assert_eq!(frame_ref.metadata(), Some("cached"));
        assert!(format!("{frame_ref:?}").contains("metadata: Some(\"cached\")"));

        let owned = frame_ref.to_owned().expect("owned conversion");
        assert_eq!(owned.metadata(), Some("cached"));
        assert_eq!(owned.data().len(), expected_len);

        std::mem::forget(frame_ref);
    }

    #[test]
    fn test_audio_frame_ref_metadata_is_text_and_owned_conversion_preserves_it() {
        use crate::capture::RecvAudioGuard;

        let no_samples = 4;
        let no_channels = 2;
        let sample_count = (no_samples * no_channels) as usize;
        let data = vec![0.25f32; sample_count];
        let mut metadata = b"audio meta\0".to_vec();

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels,
            no_samples,
            timecode: 123,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: no_samples * 4,
            },
            p_metadata: metadata.as_mut_ptr().cast::<c_char>(),
            timestamp: 456,
        };

        let guard = unsafe { RecvAudioGuard::new(ptr::null_mut(), raw) };
        let frame_ref = unsafe { AudioFrameRef::new(guard) }.expect("valid audio ref");

        assert_eq!(frame_ref.metadata(), Some("audio meta"));
        let owned = frame_ref.to_owned().expect("owned conversion");
        assert_eq!(owned.metadata(), Some("audio meta"));
        assert_eq!(owned.data().len(), sample_count);

        std::mem::forget(frame_ref);
    }

    #[test]
    fn test_owned_video_from_raw_rejects_malformed_frame_metadata() {
        let width = 16;
        let height = 8;
        let stride = width * 4;
        let expected_len = (stride * height) as usize;
        let mut data = vec![0u8; expected_len];
        let mut metadata = vec![b'x'; MAX_METADATA_BYTES];

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: metadata.as_mut_ptr().cast::<c_char>(),
            timestamp: 0,
        };

        assert!(matches!(
            unsafe { VideoFrame::from_raw(&raw) },
            Err(Error::InvalidFrame(_))
        ));

        metadata[0] = 0xFF;
        metadata[1] = 0;
        assert!(matches!(
            unsafe { VideoFrame::from_raw(&raw) },
            Err(Error::InvalidUtf8(_))
        ));
    }

    #[test]
    fn test_owned_frame_metadata_builders_setters_and_raw_conversion() {
        let mut video = VideoFrame::builder().metadata("").build().unwrap();
        assert_eq!(video.metadata(), Some(""));
        let raw = video.to_raw();
        assert!(!raw.p_metadata.is_null());
        assert_eq!(
            unsafe { slice::from_raw_parts(raw.p_metadata.cast::<u8>(), 1) },
            b"\0"
        );

        video.set_metadata(Some("video meta")).unwrap();
        assert_eq!(video.metadata(), Some("video meta"));
        let raw = video.to_raw();
        assert_eq!(
            unsafe { slice::from_raw_parts(raw.p_metadata.cast::<u8>(), 11) },
            b"video meta\0"
        );

        video.set_metadata(Option::<String>::None).unwrap();
        assert!(video.metadata().is_none());
        assert!(video.to_raw().p_metadata.is_null());

        let mut audio = AudioFrame::builder().metadata("").build().unwrap();
        assert_eq!(audio.metadata(), Some(""));
        assert!(!audio.to_raw().p_metadata.is_null());
        audio.set_metadata(Some("audio meta")).unwrap();
        assert_eq!(audio.metadata(), Some("audio meta"));

        assert!(matches!(
            VideoFrame::builder().metadata("bad\0metadata").build(),
            Err(Error::InvalidCString(_))
        ));
        assert!(matches!(
            AudioFrame::builder().metadata("bad\0metadata").build(),
            Err(Error::InvalidCString(_))
        ));
        assert!(matches!(
            video.set_metadata(Some("bad\0metadata")),
            Err(Error::InvalidCString(_))
        ));
        assert!(matches!(
            audio.set_metadata(Some("bad\0metadata")),
            Err(Error::InvalidCString(_))
        ));

        let oversized = "x".repeat(MAX_METADATA_BYTES);
        assert!(matches!(
            VideoFrame::builder().metadata(oversized.clone()).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            AudioFrame::builder().metadata(oversized.clone()).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            video.set_metadata(Some(oversized.clone())),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            audio.set_metadata(Some(oversized)),
            Err(Error::InvalidFrame(_))
        ));
    }

    /// Test that audio frames with overflow in checked_mul are rejected
    #[test]
    fn test_audio_overflow_checked_mul() {
        // Use an extreme channel count to exceed the maximum backing buffer size.
        let no_samples = 1024;
        let no_channels = i32::MAX;
        let mut dummy_data = vec![0f32; 1024]; // Small buffer, won't be used due to guard

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels,
            no_samples,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: dummy_data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: no_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = unsafe { AudioFrame::from_raw(raw) };
        assert!(
            result.is_err(),
            "Should reject audio frame with sample count overflow or exceeding size limit"
        );

        if let Err(Error::InvalidFrame(msg)) = result {
            // Accept either overflow or size limit error - both are correct guards
            assert!(
                msg.contains("overflow") || msg.contains("exceeds maximum size"),
                "Error message should mention overflow or size limit, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test that normal audio frames within bounds succeed
    #[test]
    fn test_audio_within_bounds_succeeds() {
        // Typical audio frame: 48kHz, 2 channels, 1024 samples
        let sample_rate = 48000;
        let no_channels = 2;
        let no_samples = 1024;
        let sample_count = (no_samples * no_channels) as usize;
        let mut data = vec![0.5f32; sample_count];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate,
            no_channels,
            no_samples,
            timecode: 12345,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: no_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 67890,
        };

        let result = unsafe { AudioFrame::from_raw(raw) };
        assert!(
            result.is_ok(),
            "Should accept normal audio frame within bounds"
        );

        let frame = result.unwrap();
        assert_eq!(frame.data().len(), sample_count);
        assert_eq!(frame.num_samples(), no_samples);
        assert_eq!(frame.num_channels(), no_channels);
    }

    #[test]
    fn test_audio_builder_rejects_invalid_dimensions() {
        assert!(matches!(
            AudioFrame::builder().sample_rate(0).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            AudioFrame::builder().channels(0).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            AudioFrame::builder().samples(0).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            AudioFrame::builder().samples(-1).build(),
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_audio_builder_rejects_oversized_layout() {
        let samples = (MAX_AUDIO_BYTES / std::mem::size_of::<f32>()) as i32 + 1;
        let result = AudioFrame::builder().channels(1).samples(samples).build();

        assert!(matches!(result, Err(Error::InvalidFrame(_))));
    }

    #[test]
    fn test_default_outbound_timecodes_are_synthesized() {
        assert_eq!(
            VideoFrame::builder()
                .resolution(16, 16)
                .build()
                .unwrap()
                .timecode(),
            NDIlib_send_timecode_synthesize
        );
        assert_eq!(
            AudioFrame::builder().samples(1).build().unwrap().timecode(),
            NDIlib_send_timecode_synthesize
        );
        assert_eq!(
            MetadataFrame::new().timecode(),
            NDIlib_send_timecode_synthesize
        );
        assert_eq!(
            VideoFrame::builder()
                .resolution(16, 16)
                .timecode(0)
                .build()
                .unwrap()
                .timecode(),
            0
        );
        assert_eq!(
            AudioFrame::builder()
                .samples(1)
                .timecode(0)
                .build()
                .unwrap()
                .timecode(),
            0
        );
        assert_eq!(MetadataFrame::with_data("<x/>", 0).unwrap().timecode(), 0);
    }

    #[test]
    fn test_video_builder_rejects_invalid_send_metadata() {
        assert!(matches!(
            VideoFrame::builder().frame_rate(0, 1).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            VideoFrame::builder().frame_rate(30, 0).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            VideoFrame::builder().aspect_ratio(f32::NAN).build(),
            Err(Error::InvalidFrame(_))
        ));
        assert!(matches!(
            VideoFrame::builder().aspect_ratio(-1.0).build(),
            Err(Error::InvalidFrame(_))
        ));
    }

    #[test]
    fn test_zero_aspect_ratio_uses_sdk_square_pixel_sentinel() {
        let frame = VideoFrame::builder()
            .resolution(16, 16)
            .aspect_ratio(0.0)
            .build()
            .unwrap();
        assert_eq!(frame.picture_aspect_ratio(), 0.0);
        assert_eq!(frame.to_raw().picture_aspect_ratio, 0.0);
    }

    #[test]
    fn test_owned_frame_data_replacement_preserves_layout_size() {
        let mut video = VideoFrame::builder()
            .resolution(16, 16)
            .pixel_format(PixelFormat::BGRA)
            .build()
            .unwrap();
        assert!(video.replace_data(vec![0; video.data().len() - 1]).is_err());

        let mut audio = AudioFrame::builder()
            .channels(2)
            .samples(16)
            .build()
            .unwrap();
        assert!(audio
            .replace_data(vec![0.0; audio.data().len() + 1])
            .is_err());
    }

    #[test]
    fn test_video_cap_allows_8k_bgra_without_allocating() {
        let layout =
            ValidatedVideoLayout::new_uncompressed(PixelFormat::BGRA, 7680, 4320, None).unwrap();
        assert_eq!(layout.data_len_bytes, 132_710_400);
        assert!(matches!(
            ValidatedVideoLayout::new_uncompressed(PixelFormat::BGRA, 16_384, 8_640, None),
            Err(Error::InvalidFrame(_))
        ));
    }

    // =========================================================================
    // Tests for frame layout validation helpers
    // =========================================================================

    /// Test validate_video_layout with valid uncompressed frame
    #[test]
    fn test_validate_video_layout_valid_uncompressed() {
        let width = 1920;
        let height = 1080;
        let stride = width * 4; // BGRA
        let expected_size = (stride * height) as usize;
        let mut data = vec![0u8; expected_size];

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(result.is_ok(), "Should validate valid uncompressed frame");

        let layout = result.unwrap();
        assert_eq!(layout.pixel_format, PixelFormat::BGRA);
        assert_eq!(layout.data_len_bytes, expected_size);
        assert_eq!(
            layout.line_stride_or_size,
            LineStrideOrSize::LineStrideBytes(stride)
        );
    }

    /// Test validate_video_layout accepts the first-plane strides the SDK
    /// delivers for UYVA, P216 and PA16
    #[test]
    fn test_validate_video_layout_semi_planar_422_and_alpha() {
        let width = 256;
        let height = 64;
        let stride = width * 2;
        let plane = (stride * height) as usize;

        for (format, expected_size) in [
            (PixelFormat::UYVA, plane + plane / 2),
            (PixelFormat::P216, plane * 2),
            (PixelFormat::PA16, plane * 3),
        ] {
            let mut data = vec![0u8; expected_size];

            let raw = NDIlib_video_frame_v2_t {
                xres: width,
                yres: height,
                FourCC: format.into(),
                frame_rate_N: 60,
                frame_rate_D: 1,
                picture_aspect_ratio: 16.0 / 9.0,
                frame_format_type: ScanType::Progressive.into(),
                timecode: 0,
                p_data: data.as_mut_ptr(),
                __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                    line_stride_in_bytes: stride,
                },
                p_metadata: ptr::null(),
                timestamp: 0,
            };

            let layout = validate_video_layout(&raw)
                .unwrap_or_else(|e| panic!("{format:?} stride {stride} rejected: {e}"));
            assert_eq!(layout.pixel_format, format);
            assert_eq!(layout.data_len_bytes, expected_size, "{format:?}");
            assert_eq!(
                layout.line_stride_or_size,
                LineStrideOrSize::LineStrideBytes(stride)
            );
        }
    }

    /// Test validate_video_layout rejects an odd UYVA stride, since the alpha
    /// plane stride is half the line stride
    #[test]
    fn test_validate_video_layout_rejects_odd_uyva_stride() {
        let width = 256;
        let height = 64;
        let stride = width * 2 + 1;
        let mut data = vec![0u8; (stride * height * 2) as usize];

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::UYVA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        assert!(matches!(
            validate_video_layout(&raw),
            Err(Error::InvalidFrame(_))
        ));
    }

    /// Test validate_video_layout rejects null data pointer
    #[test]
    fn test_validate_video_layout_null_pointer() {
        let raw = NDIlib_video_frame_v2_t {
            xres: 1920,
            yres: 1080,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: ptr::null_mut(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 7680,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(result.is_err(), "Should reject null data pointer");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("null data pointer"),
                "Error should mention null pointer, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test validate_video_layout rejects invalid line_stride
    #[test]
    fn test_validate_video_layout_invalid_stride() {
        let mut data = vec![0u8; 1024];

        let raw = NDIlib_video_frame_v2_t {
            xres: 1920,
            yres: 1080,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: -1, // Invalid stride
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(result.is_err(), "Should reject negative line_stride");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("invalid line_stride_in_bytes"),
                "Error should mention invalid stride, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    #[test]
    fn test_validate_video_layout_accepts_default_zero_stride() {
        let mut data = vec![0u8; 16 * 16 * 4];
        let raw = NDIlib_video_frame_v2_t {
            xres: 16,
            yres: 16,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 1.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 0,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };
        let layout = validate_video_layout(&raw).unwrap();
        assert_eq!(layout.data_len_bytes, data.len());
        assert_eq!(
            layout.line_stride_or_size,
            LineStrideOrSize::LineStrideBytes(64)
        );
        let owned = unsafe { VideoFrame::from_raw(&raw) }.unwrap();
        assert_eq!(owned.data().len(), data.len());
    }

    /// Test validate_video_layout rejects strides smaller than one row.
    #[test]
    fn test_validate_video_layout_rejects_short_stride() {
        let mut data = vec![0u8; 1024];

        let raw = NDIlib_video_frame_v2_t {
            xres: 1920,
            yres: 1080,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 1919 * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(matches!(result, Err(Error::InvalidFrame(_))));
    }

    /// Test validate_video_layout rejects odd dimensions for planar 4:2:0.
    #[test]
    fn test_validate_video_layout_rejects_planar_odd_dimensions() {
        let mut data = vec![0u8; 4096];

        let raw = NDIlib_video_frame_v2_t {
            xres: 641,
            yres: 480,
            FourCC: PixelFormat::I420.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 4.0 / 3.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 642,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(matches!(result, Err(Error::InvalidFrame(_))));
    }

    /// Test validate_video_layout rejects negative dimensions
    #[test]
    fn test_validate_video_layout_negative_dimensions() {
        let mut data = vec![0u8; 1024];

        let raw = NDIlib_video_frame_v2_t {
            xres: 1920,
            yres: -1, // Negative height
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: 7680,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(result.is_err(), "Should reject negative height");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("invalid height"),
                "Error should mention invalid height, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test validate_video_layout rejects oversized frames
    #[test]
    fn test_validate_video_layout_exceeds_max() {
        // Validation rejects before reading data, so no large allocation is needed.
        let width = 16_384;
        let height = 8_640;
        let stride = width * 4;
        let mut data = [0u8; 1];

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 0,
            p_data: data.as_mut_ptr(),
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_video_layout(&raw);
        assert!(result.is_err(), "Should reject oversized frame");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("exceeds maximum size"),
                "Error should mention size limit, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test validate_audio_layout with valid frame
    #[test]
    fn test_validate_audio_layout_valid() {
        let no_samples = 1024;
        let no_channels = 2;
        let sample_count = (no_samples * no_channels) as usize;
        let mut data = vec![0.0f32; sample_count];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels,
            no_samples,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: no_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout(&raw);
        assert!(result.is_ok(), "Should validate valid audio frame");

        let layout = result.unwrap();
        assert_eq!(layout.format, Some(AudioFormat::FLTP));
        assert_eq!(layout.sample_count, sample_count);
    }

    #[test]
    fn test_audio_channel_views_and_owned_conversion_skip_padding() {
        use crate::capture::FrameSyncAudioFree;
        use std::mem::MaybeUninit;
        // Only samples are initialized; gap slots are not audio data.
        let mut storage = [MaybeUninit::<f32>::uninit(); 10];
        for (index, value) in [(0, 1.0), (1, 2.0), (2, 3.0), (6, 4.0), (7, 5.0), (8, 6.0)] {
            storage[index].write(value);
        }
        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 2,
            no_samples: 3,
            FourCC: AudioFormat::FLTP.into(),
            p_data: storage.as_mut_ptr().cast(),
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 24,
            },
            timecode: 123,
            timestamp: 456,
            p_metadata: ptr::null(),
        };
        let guard = unsafe { Guard::<FrameSyncAudioFree>::new(ptr::null_mut(), raw) };
        let frame = unsafe { AudioRef::<FrameSyncAudioFree>::new(guard, false) }.unwrap();
        assert!(frame.data().is_none());
        assert_eq!(frame.channel_data(0).unwrap(), &[1.0, 2.0, 3.0]);
        assert_eq!(frame.channel_data(1).unwrap(), &[4.0, 5.0, 6.0]);
        assert_eq!(frame.channel_data(1).unwrap().as_ptr(), unsafe {
            storage.as_ptr().add(6).cast::<f32>()
        });
        assert!(frame.channel_data(2).is_none());
        assert_eq!(frame.channels().len(), 2);
        assert_eq!(
            frame.channels().flatten().copied().collect::<Vec<_>>(),
            vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
        );
        let mut owned = frame.to_owned().unwrap().unwrap();
        assert_eq!(owned.channel_stride_in_bytes(), 12);
        assert_eq!(owned.data(), &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
        assert_eq!(owned.timecode(), 123);
        assert_eq!(owned.timestamp(), 456);
        assert_eq!(owned.channel_data(1).unwrap().as_ptr(), unsafe {
            owned.data().as_ptr().add(3)
        });
        owned.channel_data_mut(1).unwrap()[0] = 99.0;
        assert_eq!(owned.data()[3], 99.0);
        assert!(owned.channel_data_mut(2).is_none());
        assert!(owned.replace_data(vec![0.0; 10]).is_err());
    }

    #[test]
    fn test_audio_rejects_unaligned_float_pointer_before_access() {
        let mut storage = [0.0f32; 4];
        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 1,
            no_samples: 1,
            FourCC: AudioFormat::FLTP.into(),
            p_data: unsafe { storage.as_mut_ptr().cast::<u8>().add(1) },
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 4,
            },
            timecode: 0,
            timestamp: 0,
            p_metadata: ptr::null(),
        };
        assert!(matches!(
            validate_audio_layout(&raw),
            Err(Error::InvalidFrame(_))
        ));
    }

    /// Test validate_audio_layout supports strided planar FLTP audio.
    #[test]
    fn test_validate_audio_layout_strided_planar() {
        let no_samples = 4;
        let no_channels = 2;
        let stride_samples = 6;
        let backing_samples = (stride_samples + no_samples) as usize;
        let mut data = vec![0.0f32; backing_samples];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels,
            no_samples,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: stride_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let layout = validate_audio_layout(&raw).expect("strided FLTP should validate");
        assert_eq!(layout.sample_count, backing_samples);
        assert_eq!(layout.channel_stride_samples, stride_samples as usize);
        assert_eq!(layout.channel_range(1), Some(6..10));
    }

    /// Test validate_audio_layout_allow_empty accepts the documented no-source query state.
    #[test]
    fn test_validate_audio_layout_empty_query_no_source() {
        let raw = NDIlib_audio_frame_v3_t::default();

        let layout =
            validate_audio_layout_allow_empty(&raw).expect("all-zero query state should validate");
        assert!(layout.is_empty());
        assert_eq!(layout.format(), None);
        assert_eq!(layout.sample_count, 0);
    }

    /// Test validate_audio_layout_allow_empty accepts source-format query without samples.
    #[test]
    fn test_validate_audio_layout_empty_query_with_source_format() {
        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 2,
            no_samples: 0,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: ptr::null_mut(),
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 0,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let layout = validate_audio_layout_allow_empty(&raw)
            .expect("query source format should validate without samples");
        assert!(layout.is_empty());
        assert_eq!(layout.format(), Some(AudioFormat::FLTP));
        assert_eq!(layout.sample_rate, 48000);
        assert_eq!(layout.no_channels, 2);
    }

    /// Test empty audio validation rejects partial query/no-source states.
    #[test]
    fn test_validate_audio_layout_rejects_partial_empty_query() {
        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 0,
            no_samples: 0,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: ptr::null_mut(),
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 0,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout_allow_empty(&raw);
        assert!(matches!(result, Err(Error::InvalidFrame(_))));
    }

    /// Test validate_audio_layout rejects invalid channel stride.
    #[test]
    fn test_validate_audio_layout_rejects_invalid_channel_stride() {
        let mut data = vec![0.0f32; 2048];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 2,
            no_samples: 1024,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 1024 * 4 - 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout(&raw);
        assert!(matches!(result, Err(Error::InvalidFrame(_))));
    }

    /// Test validate_audio_layout rejects null data pointer
    #[test]
    fn test_validate_audio_layout_null_pointer() {
        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 2,
            no_samples: 1024,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: ptr::null_mut(),
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 1024 * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout(&raw);
        assert!(result.is_err(), "Should reject null data pointer");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("null data pointer"),
                "Error should mention null pointer, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test validate_audio_layout rejects negative sample count
    #[test]
    fn test_validate_audio_layout_negative_samples() {
        let mut data = vec![0.0f32; 1024];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: 2,
            no_samples: -1, // Negative
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 1024 * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout(&raw);
        assert!(result.is_err(), "Should reject negative sample count");

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("Invalid number of samples"),
                "Error should mention invalid samples, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test validate_audio_layout rejects overflow scenario
    #[test]
    fn test_validate_audio_layout_overflow() {
        let mut data = vec![0.0f32; 1024];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels: i32::MAX,
            no_samples: 1024,
            timecode: 0,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_mut_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: 1024 * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 0,
        };

        let result = validate_audio_layout(&raw);
        assert!(
            result.is_err(),
            "Should reject audio frame with overflow potential"
        );

        if let Err(Error::InvalidFrame(msg)) = result {
            assert!(
                msg.contains("overflow") || msg.contains("exceeds maximum size"),
                "Error should mention overflow or size limit, got: {msg}"
            );
        } else {
            panic!("Expected InvalidFrame error");
        }
    }

    /// Test calculate_buffer_len_checked matches PixelFormatInfo::try_buffer_len for valid inputs
    #[test]
    fn test_calculate_buffer_len_checked_matches_public_helper() {
        let test_cases = [
            (PixelFormat::BGRA, 7680usize, 1080usize),
            (PixelFormat::UYVY, 3840usize, 1080usize),
            (PixelFormat::NV12, 1920usize, 1080usize),
            (PixelFormat::YV12, 1920usize, 1080usize),
            (PixelFormat::I420, 1920usize, 1080usize),
        ];

        for (format, stride, height) in test_cases {
            let expected = format
                .info()
                .try_buffer_len(stride as i32, height as i32)
                .unwrap();
            let result = calculate_buffer_len_checked(format, stride, height);

            assert!(
                result.is_ok(),
                "Should succeed for valid inputs: {:?}",
                format
            );
            assert_eq!(
                result.unwrap(),
                expected,
                "Checked calculation should match unchecked for {:?}",
                format
            );
        }
    }

    /// Test that VideoFrameRef::data() uses cached length
    #[test]
    fn test_video_frame_ref_uses_cached_length() {
        use crate::capture::{Guard, VideoKind};

        // Create a mock video frame for testing
        let width = 1920;
        let height = 1080;
        let stride = width * 4;
        let expected_size = (stride * height) as usize;
        let data = vec![0u8; expected_size];

        let raw = NDIlib_video_frame_v2_t {
            xres: width,
            yres: height,
            FourCC: PixelFormat::BGRA.into(),
            frame_rate_N: 60,
            frame_rate_D: 1,
            picture_aspect_ratio: 16.0 / 9.0,
            frame_format_type: ScanType::Progressive.into(),
            timecode: 12345,
            p_data: data.as_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_video_frame_v2_t__bindgen_ty_1 {
                line_stride_in_bytes: stride,
            },
            p_metadata: ptr::null(),
            timestamp: 67890,
        };

        // Create a guard with a null receiver instance (we won't use the free function)
        // This is safe because we'll forget the guard before it drops
        let guard = unsafe { Guard::<VideoKind>::new(ptr::null_mut(), raw) };

        // Create the VideoFrameRef
        let frame_ref = unsafe { VideoFrameRef::new(guard) };
        assert!(frame_ref.is_ok(), "Should create valid VideoFrameRef");

        let frame_ref = frame_ref.unwrap();

        // Verify the cached length is used
        assert_eq!(
            frame_ref.data().unwrap().len(),
            expected_size,
            "data() should return slice with cached length"
        );
        assert_eq!(
            frame_ref.layout.data_len_bytes, expected_size,
            "Cached data_len_bytes should match expected"
        );

        // Forget the guard to prevent calling the free function with null instance
        std::mem::forget(frame_ref);
    }

    /// Test that AudioFrameRef::data() uses cached sample count
    #[test]
    fn test_audio_frame_ref_uses_cached_sample_count() {
        use crate::capture::RecvAudioGuard;

        let no_samples = 1024;
        let no_channels = 2;
        let sample_count = (no_samples * no_channels) as usize;
        let data = vec![0.5f32; sample_count];

        let raw = NDIlib_audio_frame_v3_t {
            sample_rate: 48000,
            no_channels,
            no_samples,
            timecode: 12345,
            FourCC: NDIlib_FourCC_audio_type_e_NDIlib_FourCC_audio_type_FLTP,
            p_data: data.as_ptr() as *mut u8,
            __bindgen_anon_1: NDIlib_audio_frame_v3_t__bindgen_ty_1 {
                channel_stride_in_bytes: no_samples * 4,
            },
            p_metadata: ptr::null(),
            timestamp: 67890,
        };

        // Create a guard with a null receiver instance (we won't use the free function)
        let guard = unsafe { RecvAudioGuard::new(ptr::null_mut(), raw) };

        // Create the AudioFrameRef
        let frame_ref = unsafe { AudioFrameRef::new(guard) };
        assert!(frame_ref.is_ok(), "Should create valid AudioFrameRef");

        let frame_ref = frame_ref.unwrap();

        // Verify the cached sample count is used
        assert_eq!(
            frame_ref.data().unwrap().len(),
            sample_count,
            "data() should return slice with cached sample count"
        );
        assert_eq!(
            frame_ref.layout.sample_count, sample_count,
            "Cached sample_count should match expected"
        );

        // Forget the guard to prevent calling the free function with null instance
        std::mem::forget(frame_ref);
    }
}