hang 0.21.19

Media over QUIC
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
129
130
131
132
133
134
135
136
137
138
139

use std::collections::{BTreeMap, btree_map};

use serde::{Deserialize, Serialize};

use crate::catalog::millis::MillisCeil;
use crate::catalog::{Compression, Mode};

/// The binary tracks a broadcast publishes, keyed by track name.
///
/// Each frame is an opaque blob: a thumbnail, a serialized state snapshot, a sequence of samples in
/// some application format. Each entry says how to read the track ([`mode`](BinaryConfig::mode) and
/// [`compression`](BinaryConfig::compression)) without a consumer having to know the application.
/// Use [`Json`](crate::catalog::Json) instead when the payloads are JSON, so a generic consumer can
/// read them.
///
/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major
/// version. External callers start from [`Binary::default`] and fill in what they need
/// ([`insert`](Self::insert)); struct-literal construction is not available outside this crate.
#[serde_with::skip_serializing_none]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Binary {
	/// A map of track name to configuration.
	///
	/// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are
	/// sorted for *some* deterministic behavior.
	pub tracks: BTreeMap<String, BinaryConfig>,
}

impl crate::catalog::Section for Binary {
	const MAP: &'static str = "tracks";
}

impl Binary {
	/// Insert a track config, returning an error if the name already exists.
	pub fn insert(&mut self, name: &str, config: BinaryConfig) -> crate::Result<()> {
		let btree_map::Entry::Vacant(entry) = self.tracks.entry(name.to_string()) else {
			return Err(crate::Error::Duplicate(name.to_string()));
		};
		entry.insert(config);
		Ok(())
	}

	/// Remove the track from the catalog and return its configuration if found.
	pub fn remove(&mut self, name: &str) -> Option<BinaryConfig> {
		self.tracks.remove(name)
	}

	/// Whether there are no binary tracks, in which case the section is left off the wire.
	pub fn is_empty(&self) -> bool {
		self.tracks.is_empty()
	}
}

/// How to read one binary track.
///
/// Each frame is an opaque payload; [`mode`](Self::mode) says how the track's groups compose those
/// frames into what a consumer sees.
///
/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major
/// version. External callers build one with [`BinaryConfig::new`] and assign the optional fields
/// they need; struct-literal construction is not available outside this crate.
#[serde_with::serde_as]
#[serde_with::skip_serializing_none]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct BinaryConfig {
	/// Optional reference to another broadcast that publishes this track, expressed relative to the
	/// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same
	/// broadcast as the catalog.
	#[serde(default)]
	pub broadcast: Option<moq_net::path::RelativeOwned>,

	/// Whether the track is a latest-value blob or an append log. Always stated: see [`Mode`].
	#[serde_as(as = "serde_with::DisplayFromStr")]
	pub mode: Mode,

	/// The compression applied to each frame, or `None` when they are written through untouched.
	#[serde(default)]
	#[serde_as(as = "Option<serde_with::DisplayFromStr>")]
	pub compression: Option<Compression>,

	/// An optional media type for each payload (e.g. `image/jpeg`). Purely descriptive: a consumer
	/// that doesn't recognize it can still read the track.
	#[serde(default)]
	pub mime: Option<String>,

	/// The maximum bitrate of the track in bits per second, if known.
	#[serde(default)]
	pub bitrate: Option<u64>,

	/// The maximum delay between a payload being ready and the publisher flushing it, with the same
	/// meaning and whole-millisecond encoding as [`VideoConfig::jitter`](crate::catalog::VideoConfig::jitter).
	#[serde_as(as = "MillisCeil")]
	#[serde(default)]
	pub jitter: Option<std::time::Duration>,

	/// How far this track's payloads reach the transport behind the broadcast's earliest
	/// rendition, with the same meaning and encoding as
	/// [`VideoConfig::delay`](crate::catalog::VideoConfig::delay). Only measured for payloads that
	/// carry a capture time.
	#[serde_as(as = "MillisCeil")]
	#[serde(default)]
	pub delay: Option<std::time::Duration>,

	/// Fields this build doesn't recognize, kept so the entry round-trips.
	///
	/// A future [`Mode`] or [`Compression`] almost certainly comes with fields describing it, and
	/// preserving the discriminant without them would leave a relay republishing an entry nothing
	/// can act on. Same reason [`Container`](crate::catalog::Container) keeps an unknown container
	/// verbatim.
	#[serde(flatten)]
	pub extra: serde_json::Map<String, serde_json::Value>,
}

impl BinaryConfig {
	/// A config for a track read in `mode`, uncompressed and with no optional fields set.
	pub fn new(mode: Mode) -> Self {
		Self {
			broadcast: None,
			mode,
			compression: None,
			mime: None,
			bitrate: None,
			jitter: None,
			delay: None,
			extra: Default::default(),
		}
	}
}

/// The config itself, so a data producer takes it wherever it takes an entry embedding one.
impl AsMut<BinaryConfig> for BinaryConfig {
	fn as_mut(&mut self) -> &mut Self {
		self
	}
}