ruma_events/room/message/
audio.rs

Help
1use std::time::Duration;
2
3use js_int::UInt;
4use ruma_common::OwnedMxcUri;
5use serde::{Deserialize, Serialize};
6
7use super::FormattedBody;
8use crate::room::{
9    message::media_caption::{caption, formatted_caption},
10    EncryptedFile, MediaSource,
11};
12
13/// The payload for an audio message.
14#[derive(Clone, Debug, Deserialize, Serialize)]
15#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
16pub struct AudioMessageEventContent {
17    /// The textual representation of this message.
18    ///
19    /// If the `filename` field is not set or has the same value, this is the filename of the
20    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
21    pub body: String,
22
23    /// Formatted form of the message `body`.
24    ///
25    /// This should only be set if the body represents a caption.
26    #[serde(flatten)]
27    pub formatted: Option<FormattedBody>,
28
29    /// The original filename of the uploaded file as deserialized from the event.
30    ///
31    /// It is recommended to use the `filename` method to get the filename which automatically
32    /// falls back to the `body` field when the `filename` field is not set.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub filename: Option<String>,
35
36    /// The source of the audio clip.
37    #[serde(flatten)]
38    pub source: MediaSource,
39
40    /// Metadata for the audio clip referred to in `source`.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub info: Option<Box<AudioInfo>>,
43
44    /// Extensible event fallback data for audio messages, from the
45    /// [first version of MSC3245][msc].
46    ///
47    /// [msc]: https://github.com/matrix-org/matrix-spec-proposals/blob/83f6c5b469c1d78f714e335dcaa25354b255ffa5/proposals/3245-voice-messages.md
48    #[cfg(feature = "unstable-msc3245-v1-compat")]
49    #[serde(rename = "org.matrix.msc1767.audio", skip_serializing_if = "Option::is_none")]
50    pub audio: Option<UnstableAudioDetailsContentBlock>,
51
52    /// Extensible event fallback data for voice messages, from the
53    /// [first version of MSC3245][msc].
54    ///
55    /// [msc]: https://github.com/matrix-org/matrix-spec-proposals/blob/83f6c5b469c1d78f714e335dcaa25354b255ffa5/proposals/3245-voice-messages.md
56    #[cfg(feature = "unstable-msc3245-v1-compat")]
57    #[serde(rename = "org.matrix.msc3245.voice", skip_serializing_if = "Option::is_none")]
58    pub voice: Option<UnstableVoiceContentBlock>,
59}
60
61impl AudioMessageEventContent {
62    /// Creates a new `AudioMessageEventContent` with the given body and source.
63    pub fn new(body: String, source: MediaSource) -> Self {
64        Self {
65            body,
66            formatted: None,
67            filename: None,
68            source,
69            info: None,
70            #[cfg(feature = "unstable-msc3245-v1-compat")]
71            audio: None,
72            #[cfg(feature = "unstable-msc3245-v1-compat")]
73            voice: None,
74        }
75    }
76
77    /// Creates a new non-encrypted `AudioMessageEventContent` with the given body and url.
78    pub fn plain(body: String, url: OwnedMxcUri) -> Self {
79        Self::new(body, MediaSource::Plain(url))
80    }
81
82    /// Creates a new encrypted `AudioMessageEventContent` with the given body and encrypted
83    /// file.
84    pub fn encrypted(body: String, file: EncryptedFile) -> Self {
85        Self::new(body, MediaSource::Encrypted(Box::new(file)))
86    }
87
88    /// Creates a new `AudioMessageEventContent` from `self` with the `info` field set to the given
89    /// value.
90    ///
91    /// Since the field is public, you can also assign to it directly. This method merely acts
92    /// as a shorthand for that, because it is very common to set this field.
93    pub fn info(self, info: impl Into<Option<Box<AudioInfo>>>) -> Self {
94        Self { info: info.into(), ..self }
95    }
96
97    /// Computes the filename for the audio file as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
98    ///
99    /// This differs from the `filename` field as this method falls back to the `body` field when
100    /// the `filename` field is not set.
101    pub fn filename(&self) -> &str {
102        self.filename.as_deref().unwrap_or(&self.body)
103    }
104
105    /// Returns the caption for the audio as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
106    ///
107    /// In short, this is the `body` field if the `filename` field exists and has a different value,
108    /// otherwise the media file does not have a caption.
109    pub fn caption(&self) -> Option<&str> {
110        caption(&self.body, self.filename.as_deref())
111    }
112
113    /// Returns the formatted caption for the audio as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
114    ///
115    /// This is the same as `caption`, but returns the formatted body instead of the plain body.
116    pub fn formatted_caption(&self) -> Option<&FormattedBody> {
117        formatted_caption(&self.body, self.formatted.as_ref(), self.filename.as_deref())
118    }
119}
120
121/// Metadata about an audio clip.
122#[derive(Clone, Debug, Default, Deserialize, Serialize)]
123#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
124pub struct AudioInfo {
125    /// The duration of the audio in milliseconds.
126    #[serde(
127        with = "ruma_common::serde::duration::opt_ms",
128        default,
129        skip_serializing_if = "Option::is_none"
130    )]
131    pub duration: Option<Duration>,
132
133    /// The mimetype of the audio, e.g. "audio/aac".
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub mimetype: Option<String>,
136
137    /// The size of the audio clip in bytes.
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub size: Option<UInt>,
140}
141
142impl AudioInfo {
143    /// Creates an empty `AudioInfo`.
144    pub fn new() -> Self {
145        Self::default()
146    }
147}
148
149/// Extensible event fallback data for audio messages, from the
150/// [first version of MSC3245][msc].
151///
152/// [msc]: https://github.com/matrix-org/matrix-spec-proposals/blob/83f6c5b469c1d78f714e335dcaa25354b255ffa5/proposals/3245-voice-messages.md
153#[cfg(feature = "unstable-msc3245-v1-compat")]
154#[derive(Clone, Debug, Deserialize, Serialize)]
155#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
156pub struct UnstableAudioDetailsContentBlock {
157    /// The duration of the audio in milliseconds.
158    ///
159    /// Note that the MSC says this should be in seconds but for compatibility with the Element
160    /// clients, this uses milliseconds.
161    #[serde(with = "ruma_common::serde::duration::ms")]
162    pub duration: Duration,
163
164    /// The waveform representation of the audio content, if any.
165    ///
166    /// This is optional and defaults to an empty array.
167    #[serde(default, skip_serializing_if = "Vec::is_empty")]
168    pub waveform: Vec<UnstableAmplitude>,
169}
170
171#[cfg(feature = "unstable-msc3245-v1-compat")]
172impl UnstableAudioDetailsContentBlock {
173    /// Creates a new `UnstableAudioDetailsContentBlock ` with the given duration and waveform.
174    pub fn new(duration: Duration, waveform: Vec<UnstableAmplitude>) -> Self {
175        Self { duration, waveform }
176    }
177}
178
179/// Extensible event fallback data for voice messages, from the
180/// [first version of MSC3245][msc].
181///
182/// [msc]: https://github.com/matrix-org/matrix-spec-proposals/blob/83f6c5b469c1d78f714e335dcaa25354b255ffa5/proposals/3245-voice-messages.md
183#[cfg(feature = "unstable-msc3245-v1-compat")]
184#[derive(Clone, Debug, Default, Deserialize, Serialize)]
185#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
186pub struct UnstableVoiceContentBlock {}
187
188#[cfg(feature = "unstable-msc3245-v1-compat")]
189impl UnstableVoiceContentBlock {
190    /// Creates a new `UnstableVoiceContentBlock`.
191    pub fn new() -> Self {
192        Self::default()
193    }
194}
195
196/// The unstable version of the amplitude of a waveform sample.
197///
198/// Must be an integer between 0 and 1024.
199#[cfg(feature = "unstable-msc3245-v1-compat")]
200#[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq, PartialOrd, Ord, Serialize)]
201pub struct UnstableAmplitude(UInt);
202
203#[cfg(feature = "unstable-msc3245-v1-compat")]
204impl UnstableAmplitude {
205    /// The smallest value that can be represented by this type, 0.
206    pub const MIN: u16 = 0;
207
208    /// The largest value that can be represented by this type, 1024.
209    pub const MAX: u16 = 1024;
210
211    /// Creates a new `UnstableAmplitude` with the given value.
212    ///
213    /// It will saturate if it is bigger than [`UnstableAmplitude::MAX`].
214    pub fn new(value: u16) -> Self {
215        Self(value.min(Self::MAX).into())
216    }
217
218    /// The value of this `UnstableAmplitude`.
219    pub fn get(&self) -> UInt {
220        self.0
221    }
222}
223
224#[cfg(feature = "unstable-msc3245-v1-compat")]
225impl From<u16> for UnstableAmplitude {
226    fn from(value: u16) -> Self {
227        Self::new(value)
228    }
229}
230
231#[cfg(feature = "unstable-msc3245-v1-compat")]
232impl<'de> Deserialize<'de> for UnstableAmplitude {
233    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
234    where
235        D: serde::Deserializer<'de>,
236    {
237        let uint = UInt::deserialize(deserializer)?;
238        Ok(Self(uint.min(Self::MAX.into())))
239    }
240}
ruma_events/room/message/audio.rs

ruma_events/room/message/
audio.rs
