medea_control_api_proto/control/endpoint/
web_rtc_publish.rs

1//! [`WebRtcPublish`] [`Endpoint`] definitions.
2//!
3//! [`Endpoint`]: crate::Endpoint
4
5use derive_more::with_trait::{AsRef, Display, From, Into};
6use ref_cast::RefCast;
7#[cfg(feature = "serde")]
8use serde::{Deserialize, Serialize};
9
10use crate::control::endpoint;
11
12/// Media [`Element`] receiving media data from a client via [WebRTC] (allows to
13/// publish media data).
14///
15/// [`Element`]: crate::Element
16/// [WebRTC]: https://w3.org/TR/webrtc
17#[derive(Clone, Debug, Eq, PartialEq)]
18pub struct WebRtcPublish {
19    /// ID of this [`WebRtcPublish`] media [`Element`].
20    ///
21    /// [`Element`]: crate::Element
22    pub id: Id,
23
24    /// [`Spec`] of this [`WebRtcPublish`] media [`Element`].
25    ///
26    /// [`Element`]: crate::Element
27    pub spec: Spec,
28}
29
30/// Spec of a [`WebRtcPublish`] media [`Element`].
31///
32/// [`Element`]: crate::Element
33#[derive(Clone, Copy, Debug, Eq, PartialEq)]
34#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
35pub struct Spec {
36    /// Peer-to-peer mode of this [`WebRtcPublish`] [`Element`].
37    ///
38    /// [`Element`]: crate::Element
39    pub p2p: P2pMode,
40
41    /// Indicator whether to relay all media data through a [TURN] server
42    /// forcibly.
43    ///
44    /// [TURN]: https://webrtc.org/getting-started/turn-server
45    #[cfg_attr(feature = "serde", serde(default))]
46    pub force_relay: bool,
47
48    /// Settings for the audio media type of this [`WebRtcPublish`]
49    /// [`Element`].
50    ///
51    /// [`Element`]: crate::Element
52    #[cfg_attr(feature = "serde", serde(default))]
53    pub audio_settings: AudioSettings,
54
55    /// Settings for the video media type of this [`WebRtcPublish`]
56    /// [`Element`].
57    ///
58    /// [`Element`]: crate::Element
59    #[cfg_attr(feature = "serde", serde(default))]
60    pub video_settings: VideoSettings,
61}
62
63/// ID of a [`WebRtcPublish`] media [`Element`]
64///
65/// [`Element`]: crate::Element
66#[derive(
67    AsRef,
68    Clone,
69    Debug,
70    Display,
71    Eq,
72    From,
73    Hash,
74    Into,
75    Ord,
76    PartialEq,
77    PartialOrd,
78    RefCast,
79)]
80#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
81#[cfg_attr(feature = "serde", serde(transparent))]
82#[from(Box<str>, &str, String)]
83#[into(Box<str>, String)]
84#[repr(transparent)]
85pub struct Id(Box<str>);
86
87impl AsRef<endpoint::Id> for Id {
88    fn as_ref(&self) -> &endpoint::Id {
89        endpoint::Id::ref_cast(&self.0)
90    }
91}
92
93/// Possible peer-to-peer modes of [WebRTC] interaction in a [`WebRtcPublish`]
94/// media [`Element`].
95///
96/// [`Element`]: crate::Element
97/// [WebRTC]: https://w3.org/TR/webrtc
98#[derive(Clone, Copy, Debug, Eq, PartialEq)]
99#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
100pub enum P2pMode {
101    /// Never use peer-to-peer connections and always send media data through a
102    /// media server.
103    Never = 0,
104
105    /// Use peer-to-peer connections directly if it's possible, otherwise send
106    /// media data through a media server.
107    IfPossible = 1,
108
109    /// Send media data via peer-to-peer connections only, and never through a
110    /// media server.
111    Always = 2,
112}
113
114/// Audio media type settings of a [`WebRtcPublish`] media [`Element`].
115///
116/// [`Element`]: crate::Element
117#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
118#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
119pub struct AudioSettings {
120    /// [`Policy`] to publish the audio media type with.
121    #[cfg_attr(feature = "serde", serde(default))]
122    pub publish_policy: Policy,
123}
124
125/// Video media type settings of a [`WebRtcPublish`] media [`Element`].
126///
127/// [`Element`]: crate::Element
128#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
129#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
130pub struct VideoSettings {
131    /// [`Policy`] to publish the video media type with.
132    #[cfg_attr(feature = "serde", serde(default))]
133    pub publish_policy: Policy,
134}
135
136/// Policy of how a video or an audio media type can be published in a
137/// [`WebRtcPublish`] media [`Element`].
138///
139/// [`Element`]: crate::Element
140#[derive(Clone, Copy, Debug, Eq, PartialEq, Default)]
141#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
142pub enum Policy {
143    /// Media type __may__ be published.
144    ///
145    /// Media server will try to initialize publishing, but won't produce any
146    /// errors if user application fails to (or chooses not to) acquire the
147    /// required media track. Media server will approve user requests to stop
148    /// and to restart publishing the specified media type.
149    #[default]
150    Optional = 0,
151
152    /// Media type __must__ be published.
153    ///
154    /// Media server will try to initialize publishing, and if the required
155    /// media track cannot be acquired, then an error will be thrown. Media
156    /// server will deny all requests to stop publishing.
157    Required = 1,
158
159    /// Media type __must not__ be published.
160    ///
161    /// Media server will not try to initialize publishing.
162    Disabled = 2,
163}
medea_control_api_proto/control/endpoint/web_rtc_publish.rs

medea_control_api_proto/control/endpoint/
web_rtc_publish.rs
