mp4_atom/moov/trak/mdia/minf/stbl/

sgpd.rs

use crate::*;

/// SampleGroupDescriptionBox, ISO/IEC 14496-12:2024 Sect 8.9.3
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Sgpd {
    pub grouping_type: FourCC,
    pub default_length: Option<u32>,
    pub default_group_description_index: Option<u32>,
    pub static_group_description: bool,
    pub static_mapping: bool,
    pub essential: bool,
    pub entries: Vec<SgpdEntry>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct SgpdEntry {
    pub description_length: Option<u32>,
    pub entry: AnySampleGroupEntry,
}

ext!(
    name: Sgpd,
    versions: [0, 1, 2, 3],
    flags: {
        static_group_description = 0,
        static_mapping = 1,
    }
);

impl PartialOrd for SgpdVersion {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        match (self, other) {
            (SgpdVersion::V0, SgpdVersion::V0) => Some(std::cmp::Ordering::Equal),
            (SgpdVersion::V0, _) => Some(std::cmp::Ordering::Less),
            (SgpdVersion::V1, SgpdVersion::V0) => Some(std::cmp::Ordering::Greater),
            (SgpdVersion::V1, SgpdVersion::V1) => Some(std::cmp::Ordering::Equal),
            (SgpdVersion::V1, _) => Some(std::cmp::Ordering::Less),
            (SgpdVersion::V2, SgpdVersion::V2) => Some(std::cmp::Ordering::Equal),
            (SgpdVersion::V2, SgpdVersion::V3) => Some(std::cmp::Ordering::Less),
            (SgpdVersion::V2, _) => Some(std::cmp::Ordering::Greater),
            (SgpdVersion::V3, SgpdVersion::V3) => Some(std::cmp::Ordering::Equal),
            (SgpdVersion::V3, _) => Some(std::cmp::Ordering::Greater),
        }
    }
}

impl AtomExt for Sgpd {
    type Ext = SgpdExt;

    const KIND_EXT: FourCC = FourCC::new(b"sgpd");

    fn decode_body_ext<B: Buf>(buf: &mut B, ext: Self::Ext) -> Result<Self> {
        let grouping_type = FourCC::decode(buf)?;
        let default_length = if ext.version >= SgpdVersion::V1 {
            Some(u32::decode(buf)?)
        } else {
            None
        };
        let default_group_description_index = if ext.version >= SgpdVersion::V2 {
            Some(u32::decode(buf)?)
        } else {
            None
        };
        let entry_count = u32::decode(buf)?;
        // Every entry takes at least a byte, so reject counts that cannot fit before
        // looping: a version 0 entry of an unknown grouping type reads to the end of the
        // box, leaving every later entry empty and free to decode, so a 20-byte box could
        // otherwise push billions of them.
        if entry_count as u64 > buf.remaining() as u64 {
            return Err(Error::OutOfBounds);
        }
        let mut entries = Vec::with_capacity((entry_count as usize).min(1024));
        for _ in 0..entry_count {
            // Spec states: if version>=1 && default_length==0
            // But, default_length.is_some(), if and only if version>=1, so fine to just check for
            // `Some(0)`.
            let description_length = if default_length == Some(0) {
                Some(u32::decode(buf)?)
            } else {
                default_length
            };
            let entry = AnySampleGroupEntry::decode(grouping_type, description_length, buf)?;
            entries.push(SgpdEntry {
                description_length,
                entry,
            });
        }
        let static_group_description = ext.static_group_description;
        let static_mapping = ext.static_mapping;
        let essential = ext.version == SgpdVersion::V3;
        Ok(Self {
            grouping_type,
            default_length,
            default_group_description_index,
            static_group_description,
            static_mapping,
            essential,
            entries,
        })
    }

    fn encode_body_ext<B: BufMut>(&self, buf: &mut B) -> Result<Self::Ext> {
        let version = if self.essential {
            SgpdVersion::V3
        } else if self.default_group_description_index.is_some() {
            SgpdVersion::V2
        } else if self.default_length.is_some() {
            SgpdVersion::V1
        } else {
            SgpdVersion::V0
        };
        let ext = SgpdExt {
            version,
            static_group_description: self.static_group_description,
            static_mapping: self.static_mapping,
        };
        self.grouping_type.encode(buf)?;
        if version >= SgpdVersion::V1 {
            self.default_length
                .ok_or(Error::MissingContent("sgpd default_length"))?
                .encode(buf)?;
        }
        if version >= SgpdVersion::V2 {
            self.default_group_description_index
                .ok_or(Error::MissingContent(
                    "sgpd default_group_description_index",
                ))?
                .encode(buf)?;
        }
        (self.entries.len() as u32).encode(buf)?;
        for entry in &self.entries {
            if self.default_length == Some(0) {
                if let Some(description_length) = entry.description_length {
                    description_length.encode(buf)?
                }
            }
            entry.entry.encode(buf)?
        }
        Ok(ext)
    }
}

const REFS_4CC: FourCC = FourCC::new(b"refs");

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum AnySampleGroupEntry {
    DirectReferenceSampleList(u32, Vec<u32>),
    UnknownGroupingType(FourCC, Vec<u8>),
}

impl AnySampleGroupEntry {
    fn decode<B: Buf>(
        grouping_type: FourCC,
        description_length: Option<u32>,
        buf: &mut B,
    ) -> Result<Self> {
        match grouping_type {
            REFS_4CC => {
                let sample_id = u32::decode(buf)?;
                let num_direct_reference_samples = u8::decode(buf)? as usize;
                let mut direct_reference_samples =
                    Vec::with_capacity(std::cmp::min(num_direct_reference_samples, 16));
                for _ in 0..num_direct_reference_samples {
                    direct_reference_samples.push(u32::decode(buf)?);
                }
                Ok(Self::DirectReferenceSampleList(
                    sample_id,
                    direct_reference_samples,
                ))
            }
            _ => {
                let bytes = match description_length {
                    Some(description_length) => {
                        Vec::decode_exact(buf, description_length as usize)?
                    }
                    None => Vec::decode(buf)?,
                };
                Ok(Self::UnknownGroupingType(grouping_type, bytes))
            }
        }
    }

    fn encode<B: BufMut>(&self, buf: &mut B) -> Result<()> {
        match self {
            Self::DirectReferenceSampleList(sample_id, direct_reference_samples) => {
                sample_id.encode(buf)?;
                let num_direct_reference_samples: u8 = direct_reference_samples
                    .len()
                    .try_into()
                    .map_err(|_| Error::TooLarge(REFS_4CC))?;
                num_direct_reference_samples.encode(buf)?;
                for direct_reference_sample in direct_reference_samples {
                    direct_reference_sample.encode(buf)?;
                }
                Ok(())
            }
            Self::UnknownGroupingType(_, bytes) => bytes.encode(buf),
        }
    }
}

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

    // This example was taken from:
    // https://mpeggroup.github.io/FileFormatConformance/files/published/isobmff/a9-aac-samplegroups-edit.mp4
    //
    // I just extracted the bytes for the sgpd atom location.
    const SIMPLE_SGPD: &[u8] = &[
        0x00, 0x00, 0x00, 0x1A, 0x73, 0x67, 0x70, 0x64, 0x01, 0x00, 0x00, 0x00, 0x72, 0x6F, 0x6C,
        0x6C, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x01, 0xFF, 0xFF,
    ];

    #[test]
    fn sgpd_decodes_from_bytes_correctly() {
        let mut buf = Cursor::new(SIMPLE_SGPD);
        let sgpd = Sgpd::decode(&mut buf).expect("sgpd should decode successfully");
        assert_eq!(
            sgpd,
            Sgpd {
                grouping_type: FourCC::from(b"roll"),
                default_length: Some(2),
                default_group_description_index: None,
                static_group_description: false,
                static_mapping: false,
                essential: false,
                entries: vec![SgpdEntry {
                    description_length: Some(2),
                    entry: AnySampleGroupEntry::UnknownGroupingType(
                        FourCC::from(b"roll"),
                        SIMPLE_SGPD[24..].to_vec()
                    )
                }],
            }
        )
    }

    #[test]
    fn sgpd_encodes_from_type_correctly() {
        let sgpd = Sgpd {
            grouping_type: FourCC::from(b"roll"),
            default_length: Some(2),
            default_group_description_index: None,
            static_group_description: false,
            static_mapping: false,
            essential: false,
            entries: vec![SgpdEntry {
                description_length: Some(2),
                entry: AnySampleGroupEntry::UnknownGroupingType(
                    FourCC::from(b"roll"),
                    SIMPLE_SGPD[24..].to_vec(),
                ),
            }],
        };
        let mut buf = Vec::new();
        sgpd.encode(&mut buf).expect("encode should be successful");
        assert_eq!(SIMPLE_SGPD, &buf);
    }

    #[test]
    fn sgpd_unknown_entries_respect_description_length() {
        const MULTIPLE_ENTRIES: &[u8] = &[
            0x00, 0x00, 0x00, 0x1C, 0x73, 0x67, 0x70, 0x64, 0x01, 0x00, 0x00, 0x00, 0x74, 0x65,
            0x73, 0x74, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x02, 0xAA, 0xBB, 0xCC, 0xDD,
        ];

        let sgpd = Sgpd::decode(&mut Cursor::new(MULTIPLE_ENTRIES))
            .expect("sgpd should decode successfully");

        assert_eq!(
            sgpd.entries,
            vec![
                SgpdEntry {
                    description_length: Some(2),
                    entry: AnySampleGroupEntry::UnknownGroupingType(
                        FourCC::from(b"test"),
                        vec![0xAA, 0xBB],
                    ),
                },
                SgpdEntry {
                    description_length: Some(2),
                    entry: AnySampleGroupEntry::UnknownGroupingType(
                        FourCC::from(b"test"),
                        vec![0xCC, 0xDD],
                    ),
                },
            ]
        );
    }

    #[test]
    fn sgpd_rejects_entry_count_past_the_box() {
        // Version 0 of an unknown grouping type, declaring 0xffff0000 entries in a
        // 20-byte box: the first reads nothing, and every later one would be empty.
        const HUGE_COUNT: &[u8] = &[
            0x00, 0x00, 0x00, 0x14, 0x73, 0x67, 0x70, 0x64, 0x00, 0x00, 0x00, 0x00, 0xFF, 0x00,
            0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00,
        ];

        let err = Sgpd::decode(&mut Cursor::new(HUGE_COUNT)).unwrap_err();
        assert!(matches!(err, Error::OverDecode(_)), "{err:?}");
    }

    #[test]
    fn sgpd_version_0_unknown_entries_still_decode() {
        // Two version 0 entries of an unknown type: the first reads the rest of the
        // box, as before, and the count still fits the bytes left.
        const VERSION_0: &[u8] = &[
            0x00, 0x00, 0x00, 0x18, 0x73, 0x67, 0x70, 0x64, 0x00, 0x00, 0x00, 0x00, 0x72, 0x6F,
            0x6C, 0x6C, 0x00, 0x00, 0x00, 0x02, 0xFF, 0xFF, 0xFF, 0xFE,
        ];

        let sgpd = Sgpd::decode(&mut Cursor::new(VERSION_0)).expect("sgpd should decode");
        assert_eq!(sgpd.entries.len(), 2);
        assert_eq!(
            sgpd.entries[0].entry,
            AnySampleGroupEntry::UnknownGroupingType(
                FourCC::from(b"roll"),
                vec![0xFF, 0xFF, 0xFF, 0xFE]
            )
        );
    }

    #[test]
    fn sgpd_essential_requires_version_3_defaults() {
        let mut sgpd = Sgpd {
            grouping_type: FourCC::from(b"test"),
            default_length: None,
            default_group_description_index: None,
            static_group_description: false,
            static_mapping: false,
            essential: true,
            entries: vec![],
        };

        let err = sgpd.encode(&mut Vec::new()).unwrap_err();
        assert!(matches!(err, Error::MissingContent("sgpd default_length")));

        sgpd.default_length = Some(0);
        let err = sgpd.encode(&mut Vec::new()).unwrap_err();
        assert!(matches!(
            err,
            Error::MissingContent("sgpd default_group_description_index")
        ));
    }

    // From the MPEG File Format Conformance suite, heif/C041.heic
    const SGPD_ENCODED_C041: &[u8] = &[
        0x00, 0x00, 0x00, 0x2e, 0x73, 0x67, 0x70, 0x64, 0x01, 0x00, 0x00, 0x00, 0x72, 0x65, 0x66,
        0x73, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
        0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x01,
        0x00,
    ];

    #[test]
    fn sgpd_c041_decode() {
        let mut buf = Cursor::new(SGPD_ENCODED_C041);
        let sgpd = Sgpd::decode(&mut buf).expect("sgpd should decode successfully");
        assert_eq!(
            sgpd,
            Sgpd {
                grouping_type: FourCC::from(b"refs"),
                default_length: Some(0),
                default_group_description_index: None,
                static_group_description: false,
                static_mapping: false,
                essential: false,
                entries: vec![
                    SgpdEntry {
                        description_length: Some(9),
                        entry: AnySampleGroupEntry::DirectReferenceSampleList(0, vec![1])
                    },
                    SgpdEntry {
                        description_length: Some(5),
                        entry: AnySampleGroupEntry::DirectReferenceSampleList(1, vec![])
                    }
                ],
            }
        );

        let mut encoded = Vec::new();
        sgpd.encode(&mut encoded).unwrap();

        assert_eq!(encoded, SGPD_ENCODED_C041);
    }
}