mediaframe 0.4.0

A common media-stream descriptor vocabulary (pixel-format, colour, and frame metadata for video — audio/subtitle to follow) for media processing pipelines.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

//! Audio fingerprint — algorithm-tagged raw bytes.

use bytes::Bytes;
use smol_str::SmolStr;

/// Audio fingerprint value object — a free-text algorithm label
/// (`"chromaprint"`, `"acoustid"`, `"audiocrc32"`, …) plus the raw
/// fingerprint bytes the named algorithm produces.
///
/// The byte layout is opaque to this crate; the `algorithm` label is
/// the routing key that lets a downstream consumer interpret the
/// bytes correctly. The payload is held as [`bytes::Bytes`] (O(1)
/// clone). Empty `algorithm` is rejected because an unlabelled
/// fingerprint cannot be routed; empty `value` is **allowed** (some
/// algorithms emit an empty fingerprint for silence / sub-second
/// clips).
#[cfg_attr(
  feature = "quickcheck",
  derive(::quickcheck_richderive::Arbitrary),
  quickcheck(arbitrary = "crate::quickcheck_helpers::composite::fingerprint")
)]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Fingerprint {
  algorithm: SmolStr,
  value: Bytes,
}

// Optional `serde` impls grouped in one gated `const` block: a single
// `#[cfg]` covers both directions, and the validate-on-deserialize shadow
// stays private to the block (no module-namespace pollution).
#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
const _: () = {
  use serde::{Deserialize, Deserializer, Serialize, Serializer, ser::SerializeStruct};

  impl Serialize for Fingerprint {
    fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error> {
      let mut st = ser.serialize_struct("Fingerprint", 2)?;
      st.serialize_field("algorithm", &self.algorithm)?;
      st.serialize_field("value", &self.value)?;
      st.end()
    }
  }

  // Routes deserialize through `try_new` so the non-empty-`algorithm`
  // invariant holds instead of being bypassed by a field derive.
  #[derive(Deserialize)]
  struct Shadow {
    algorithm: SmolStr,
    value: Bytes,
  }

  impl<'de> Deserialize<'de> for Fingerprint {
    fn deserialize<D: Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
      let s = Shadow::deserialize(de)?;
      Fingerprint::try_new(s.algorithm, s.value).map_err(serde::de::Error::custom)
    }
  }
};

impl Default for Fingerprint {
  /// Synthetic `Default` — `algorithm: "default"`, `value: []`. The
  /// public constructor [`Self::try_new`] still rejects empty
  /// algorithm; the default value here exists purely as a decoder
  /// seed for the `buffa` wire layer (which requires
  /// `DefaultInstance: Default`). Don't use this for real
  /// fingerprints — go through [`Self::try_new`].
  fn default() -> Self {
    Self {
      algorithm: SmolStr::new_inline("default"),
      value: Bytes::new(),
    }
  }
}

/// Error returned by [`Fingerprint::try_new`] when the inputs
/// are structurally invalid (empty `algorithm`).
#[derive(Debug, Clone, PartialEq, Eq, Hash, thiserror::Error)]
#[non_exhaustive]
pub enum FingerprintError {
  /// The `algorithm` label was empty — a fingerprint without an
  /// algorithm tag cannot be routed.
  #[error("audio fingerprint algorithm label is empty")]
  EmptyAlgorithm,
}

impl Fingerprint {
  /// Constructs an `Fingerprint` from an algorithm label and
  /// raw bytes. Rejects an empty `algorithm` with
  /// [`FingerprintError::EmptyAlgorithm`]. Empty `value` is
  /// allowed (some algorithms emit no bytes for silence / very
  /// short clips).
  pub fn try_new(
    algorithm: impl Into<SmolStr>,
    value: impl Into<Bytes>,
  ) -> Result<Self, FingerprintError> {
    let algorithm = algorithm.into();
    if algorithm.is_empty() {
      return Err(FingerprintError::EmptyAlgorithm);
    }
    Ok(Self {
      algorithm,
      value: value.into(),
    })
  }

  /// Returns the algorithm label (e.g. `"chromaprint"`).
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn algorithm(&self) -> &str {
    self.algorithm.as_str()
  }

  /// Returns the raw fingerprint bytes.
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn value(&self) -> &[u8] {
    self.value.as_ref()
  }

  /// Returns the fingerprint payload as a cheaply-cloneable
  /// [`bytes::Bytes`] handle (O(1) refcount bump, no copy).
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn value_bytes(&self) -> Bytes {
    self.value.clone()
  }
}

#[cfg(test)]
mod tests;