core (meta): Per-track metadata.

Author: pdeljanov

symphonia-bundle-flac/src/demuxer.rs

@@ -75,7 +75,7 @@ impl<'s> FlacReader<'s> {
 
     /// Reads all the metadata blocks, returning a fully populated `FlacReader`.
     fn init_with_metadata(mss: MediaSourceStream<'s>, opts: FormatOptions) -> Result<Self> {
-        let mut metadata_builder = MetadataBuilder::new();
+        let mut metadata_builder = MetadataBuilder::new(FLAC_METADATA_INFO);
 
         let mut reader = mss;
         let mut track = None;
@@ -174,7 +174,7 @@ impl<'s> FlacReader<'s> {
 
         // Commit any read metadata to the metadata log.
         let mut metadata = opts.external_data.metadata.unwrap_or_default();
-        metadata.push(metadata_builder.metadata());
+        metadata.push(metadata_builder.build());
 
         // Synchronize the packet parser to the first audio frame.
         let _ = parser.resync(&mut reader)?;

symphonia-core/src/common.rs

@@ -65,3 +65,33 @@ pub enum Tier {
     /// Use as a fallback if nothing else is available.
     Fallback,
 }
+
+/// `Limit` defines an upper-bound of how much of a resource should be allocated when the amount to
+/// be allocated is specified by the media stream, which is untrusted. A limit will place an
+/// upper-bound on this allocation at the risk of breaking potentially valid streams. Limits are
+/// used to prevent denial-of-service attacks.
+///
+/// All limits can be defaulted to a reasonable value specific to the situation. These defaults will
+/// generally not break any normal streams.
+#[derive(Copy, Clone, Debug, Default)]
+pub enum Limit {
+    /// Do not impose any limit.
+    None,
+    /// Use the a reasonable default specified by the `FormatReader` or `Decoder` implementation.
+    #[default]
+    Default,
+    /// Specify the upper limit of the resource. Units are case specific.
+    Maximum(usize),
+}
+
+impl Limit {
+    /// Gets the numeric limit of the limit, or default value. If there is no limit, None is
+    /// returned.
+    pub fn limit_or_default(&self, default: usize) -> Option<usize> {
+        match self {
+            Limit::None => None,
+            Limit::Default => Some(default),
+            Limit::Maximum(max) => Some(*max),
+        }
+    }
+}

symphonia-core/src/meta.rs

@@ -56,12 +56,12 @@ use std::fmt;
 use std::num::NonZeroU8;
 use std::sync::Arc;
 
-use crate::common::FourCc;
+use crate::common::{FourCc, Limit};
 use crate::errors::Result;
 use crate::io::MediaSourceStream;
 use crate::units::Time;
 
-/// A `MetadataType` is a unique identifier used to identify a metadata format.
+/// A `MetadataId` is a unique identifier used to identify a specific metadata format.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct MetadataId(u32);
 
@@ -89,7 +89,7 @@ impl fmt::Display for MetadataId {
 pub const METADATA_ID_NULL: MetadataId = MetadataId(0x0);
 
 /// Basic information about a metadata format.
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, Debug)]
 pub struct MetadataInfo {
     /// The `MetadataType` identifier.
     pub metadata: MetadataId,
@@ -99,37 +99,7 @@ pub struct MetadataInfo {
     pub long_name: &'static str,
 }
 
-/// `Limit` defines an upper-bound on how much of a resource should be allocated when the amount to
-/// be allocated is specified by the media stream, which is untrusted. A limit will place an
-/// upper-bound on this allocation at the risk of breaking potentially valid streams. Limits are
-/// used to prevent denial-of-service attacks.
-///
-/// All limits can be defaulted to a reasonable value specific to the situation. These defaults will
-/// generally not break any normal streams.
-#[derive(Copy, Clone, Debug, Default)]
-pub enum Limit {
-    /// Do not impose any limit.
-    None,
-    /// Use the a reasonable default specified by the `FormatReader` or `Decoder` implementation.
-    #[default]
-    Default,
-    /// Specify the upper limit of the resource. Units are case specific.
-    Maximum(usize),
-}
-
-impl Limit {
-    /// Gets the numeric limit of the limit, or default value. If there is no limit, None is
-    /// returned.
-    pub fn limit_or_default(&self, default: usize) -> Option<usize> {
-        match self {
-            Limit::None => None,
-            Limit::Default => Some(default),
-            Limit::Maximum(max) => Some(*max),
-        }
-    }
-}
-
-/// `MetadataOptions` is a common set of options that all metadata readers use.
+/// A common set of options that all metadata readers use.
 #[derive(Copy, Clone, Debug, Default)]
 pub struct MetadataOptions {
     /// The maximum size limit in bytes that a tag may occupy in memory once decoded. Tags exceeding
@@ -705,60 +675,108 @@ pub enum ChapterGroupItem {
     Chapter(Chapter),
 }
 
-/// A metadata revision is a container for a single discrete revision of media metadata.
-///
-/// A metadata revision contains what a user typically associates with metadata: tags, pictures,
-/// etc.
+/// A container of metadata tags and pictures.
 #[derive(Clone, Debug, Default)]
-pub struct MetadataRevision {
+pub struct MetadataContainer {
     /// Key-value pairs of metadata.
-    tags: Vec<Tag>,
+    pub tags: Vec<Tag>,
     /// Attached pictures.
-    visuals: Vec<Visual>,
+    pub visuals: Vec<Visual>,
+}
+
+/// Container for metadata associated with a specific track. A [`MetadataContainer`] wrapper
+/// associating it with a track ID.
+#[derive(Clone, Debug, Default)]
+pub struct PerTrackMetadata {
+    /// The ID of the track the metadata is associated with.
+    pub track_id: u64,
+    /// Track-specific metadata.
+    pub metadata: MetadataContainer,
 }
 
-impl MetadataRevision {
-    /// Gets an immutable slice to the `Tag`s in this revision.
+/// A metadata revision is a container for a single discrete version of media metadata.
+///
+/// A metadata revision contains what a user typically associates with metadata: tags, pictures,
+/// etc., for the media as a whole and, optionally, for each contained track.
+#[derive(Clone, Debug)]
+pub struct MetadataRevision {
+    /// Information about the source of this revision of metadata.
+    pub info: MetadataInfo,
+    /// Media-level, global, metadata.
     ///
-    /// If a tag read from the source contained multiple values, then there will be one `Tag` item
-    /// per value, with each item having the same key and standard key.
-    pub fn tags(&self) -> &[Tag] {
-        &self.tags
+    /// The vast majority of metadata is media-level metadata.
+    pub media: MetadataContainer,
+    /// Per-track metadata.
+    pub per_track: Vec<PerTrackMetadata>,
+}
+
+/// A builder for [`MetadataRevision`].
+#[derive(Clone, Debug)]
+pub struct MetadataBuilder {
+    revision: MetadataRevision,
+}
+
+impl MetadataBuilder {
+    /// Instantiate a new `MetadataBuilder`.
+    pub fn new(info: MetadataInfo) -> Self {
+        let revision =
+            MetadataRevision { info, media: Default::default(), per_track: Default::default() };
+        MetadataBuilder { revision }
     }
 
-    /// Gets an immutable slice to the `Visual`s in this revision.
-    pub fn visuals(&self) -> &[Visual] {
-        &self.visuals
+    /// Add a media-level `Tag` to the metadata.
+    pub fn add_tag(&mut self, tag: Tag) -> &mut Self {
+        self.revision.media.tags.push(tag);
+        self
+    }
+
+    /// Add a media-level `Visual` to the metadata.
+    pub fn add_visual(&mut self, visual: Visual) -> &mut Self {
+        self.revision.media.visuals.push(visual);
+        self
+    }
+
+    /// Add track-specific metadata.
+    pub fn add_track(&mut self, per_track: PerTrackMetadata) -> &mut Self {
+        self.revision.per_track.push(per_track);
+        self
+    }
+
+    /// Build and return the metadata revision.
+    pub fn build(self) -> MetadataRevision {
+        self.revision
     }
 }
 
-/// `MetadataBuilder` is the builder for [`Metadata`] revisions.
-#[derive(Clone, Debug, Default)]
-pub struct MetadataBuilder {
-    metadata: MetadataRevision,
+/// A builder for [`PerTrackMetadata`].
+#[derive(Clone, Debug)]
+pub struct PerTrackMetadataBuilder {
+    per_track: PerTrackMetadata,
 }
 
-impl MetadataBuilder {
+impl PerTrackMetadataBuilder {
     /// Instantiate a new `MetadataBuilder`.
-    pub fn new() -> Self {
-        MetadataBuilder { metadata: Default::default() }
+    pub fn new(track_id: u64) -> Self {
+        PerTrackMetadataBuilder {
+            per_track: PerTrackMetadata { track_id, metadata: Default::default() },
+        }
     }
 
-    /// Add a `Tag` to the metadata.
+    /// Add a `Tag` to the per-track metadata.
     pub fn add_tag(&mut self, tag: Tag) -> &mut Self {
-        self.metadata.tags.push(tag);
+        self.per_track.metadata.tags.push(tag);
         self
     }
 
-    /// Add a `Visual` to the metadata.
+    /// Add a `Visual` to the per-track metadata.
     pub fn add_visual(&mut self, visual: Visual) -> &mut Self {
-        self.metadata.visuals.push(visual);
+        self.per_track.metadata.visuals.push(visual);
         self
     }
 
-    /// Yield the constructed `Metadata` revision.
-    pub fn metadata(self) -> MetadataRevision {
-        self.metadata
+    /// Build and return the track-specific metadata.
+    pub fn build(self) -> PerTrackMetadata {
+        self.per_track
     }
 }
 
@@ -804,7 +822,7 @@ impl Metadata<'_> {
     }
 }
 
-/// `MetadataLog` is a container for time-ordered [`Metadata`] revisions.
+/// A queue for time-ordered [`MetadataRevision`]s.
 #[derive(Clone, Debug, Default)]
 pub struct MetadataLog {
     revisions: VecDeque<MetadataRevision>,
@@ -898,11 +916,13 @@ pub mod well_known {
     // Format-native tags
 
     /// RIFF tags
-    pub const METADATA_ID_RIFF: MetadataId = MetadataId(0x400);
+    pub const METADATA_ID_WAVE: MetadataId = MetadataId(0x400);
+    /// RIFF tags
+    pub const METADATA_ID_AIFF: MetadataId = MetadataId(0x401);
     /// EXIF
-    pub const METADATA_ID_EXIF: MetadataId = MetadataId(0x401);
+    pub const METADATA_ID_EXIF: MetadataId = MetadataId(0x402);
     /// Matroska tags
-    pub const METADATA_ID_MATROSKA: MetadataId = MetadataId(0x402);
+    pub const METADATA_ID_MATROSKA: MetadataId = MetadataId(0x403);
     /// ISOMP4 tags
-    pub const METADATA_ID_ISOMP4: MetadataId = MetadataId(0x403);
+    pub const METADATA_ID_ISOMP4: MetadataId = MetadataId(0x404);
 }

symphonia-format-isomp4/src/atoms/ilst.rs

@@ -9,8 +9,10 @@ use std::sync::Arc;
 
 use symphonia_core::errors::{decode_error, Error, Result};
 use symphonia_core::io::{BufReader, ReadBytes};
+use symphonia_core::meta::well_known::METADATA_ID_ISOMP4;
 use symphonia_core::meta::{
-    ContentAdvisory, MetadataBuilder, MetadataRevision, RawTag, StandardTag, StandardVisualKey, Tag,
+    ContentAdvisory, MetadataBuilder, MetadataInfo, MetadataRevision, RawTag, StandardTag,
+    StandardVisualKey, Tag,
 };
 use symphonia_core::meta::{RawValue, Visual};
 use symphonia_core::util::{bits, text};
@@ -21,6 +23,12 @@ use crate::atoms::{Atom, AtomHeader, AtomIterator, AtomType};
 
 use log::{debug, warn};
 
+const ISOMP4_METADATA_INFO: MetadataInfo = MetadataInfo {
+    metadata: METADATA_ID_ISOMP4,
+    short_name: "isomp4",
+    long_name: "ISO Base Media File Format",
+};
+
 /// Data type enumeration for metadata value atoms as defined in the QuickTime File Format standard.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub enum DataType {
@@ -720,7 +728,7 @@ impl Atom for IlstAtom {
     fn read<B: ReadBytes>(reader: &mut B, header: AtomHeader) -> Result<Self> {
         let mut iter = AtomIterator::new(reader, header);
 
-        let mut mb = MetadataBuilder::new();
+        let mut mb = MetadataBuilder::new(ISOMP4_METADATA_INFO);
 
         while let Some(header) = iter.next()? {
             // Ignore standard atoms, check if other is a metadata atom.
@@ -925,7 +933,7 @@ impl Atom for IlstAtom {
             }
         }
 
-        Ok(IlstAtom { metadata: mb.metadata() })
+        Ok(IlstAtom { metadata: mb.build() })
     }
 }