Skip to main content

qualia_audio/io/metadata/
to_provenance.rs

1//! Map parsed [`WavTags`] → bounded provenance key/value pairs for NQuin emission.
2//!
3//! Keys use Dublin Core terms (`dcterms:*`), which the semantic layer can
4//! `q_hash` into predicate slots. The result is a **fixed-size, stack array**
5//! plus a count of how many leading entries are populated — no heap, no growth,
6//! suitable for emitting provenance NQuins alongside decoded audio.
7
8use super::riff_tags::WavTags;
9
10/// Maximum number of provenance pairs [`tags_to_provenance`] can emit — one per
11/// field of [`WavTags`].
12pub const MAX_PROVENANCE_PAIRS: usize = 8;
13
14/// Convert [`WavTags`] into up to [`MAX_PROVENANCE_PAIRS`] `(key, value)` pairs.
15///
16/// Returns the fixed array together with the number of populated leading
17/// entries (`(&out[..n])` are the meaningful ones). Only tags that were present
18/// contribute a pair, so the count reflects real metadata. Values are borrowed
19/// from the same bytes the tags were parsed from.
20pub fn tags_to_provenance<'a>(
21    tags: &WavTags<'a>,
22) -> ([(&'static str, &'a str); MAX_PROVENANCE_PAIRS], usize) {
23    let mut out: [(&'static str, &'a str); MAX_PROVENANCE_PAIRS] = [("", ""); MAX_PROVENANCE_PAIRS];
24    let mut n = 0usize;
25    for (key, value) in [
26        ("dcterms:title", tags.title),
27        ("dcterms:creator", tags.artist),
28        ("dcterms:description", tags.comment),
29        ("dcterms:date", tags.created),
30        ("dcterms:isPartOf", tags.product),
31        ("dcterms:type", tags.genre),
32        ("dcterms:provenance", tags.software),
33        ("dcterms:rights", tags.copyright),
34    ] {
35        if let Some(v) = value {
36            out[n] = (key, v);
37            n += 1;
38        }
39    }
40    (out, n)
41}
42
43#[cfg(test)]
44mod tests {
45    use super::*;
46    use crate::io::metadata::riff_tags::WavTags;
47
48    #[test]
49    fn maps_present_tags_only() {
50        let tags = WavTags {
51            title: Some("Rainfall"),
52            artist: Some("T. Holborn"),
53            created: Some("2026-07-18"),
54            ..WavTags::default()
55        };
56        let (pairs, n) = tags_to_provenance(&tags);
57        assert_eq!(n, 3);
58        assert_eq!(pairs[0], ("dcterms:title", "Rainfall"));
59        assert_eq!(pairs[1], ("dcterms:creator", "T. Holborn"));
60        assert_eq!(pairs[2], ("dcterms:date", "2026-07-18"));
61    }
62
63    #[test]
64    fn empty_tags_emit_nothing() {
65        let (_pairs, n) = tags_to_provenance(&WavTags::default());
66        assert_eq!(n, 0);
67    }
68
69    #[test]
70    fn all_tags_fill_bound() {
71        let tags = WavTags {
72            title: Some("a"),
73            artist: Some("b"),
74            comment: Some("c"),
75            created: Some("d"),
76            product: Some("e"),
77            genre: Some("f"),
78            software: Some("g"),
79            copyright: Some("h"),
80        };
81        let (_pairs, n) = tags_to_provenance(&tags);
82        assert_eq!(n, MAX_PROVENANCE_PAIRS);
83    }
84}