From 64978fa17b6e0882d6bacb6e626b0bc9ead2c81d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= Date: Thu, 8 Apr 2021 14:42:18 +0200 Subject: document mumd::audio --- mumd/src/audio.rs | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) (limited to 'mumd/src/audio.rs') diff --git a/mumd/src/audio.rs b/mumd/src/audio.rs index 2e20583..46f7050 100644 --- a/mumd/src/audio.rs +++ b/mumd/src/audio.rs @@ -1,3 +1,7 @@ +//! All things audio. +//! +//! Audio is handled mostly as signals from [dasp_signal]. Input/output is handled by [cpal]. + pub mod input; pub mod output; pub mod transformers; @@ -27,8 +31,11 @@ use strum::IntoEnumIterator; use strum_macros::EnumIter; use tokio::sync::watch; +/// The sample rate used internally. const SAMPLE_RATE: u32 = 48000; +/// All types of notifications that can be shown. Each notification can be bound to its own audio +/// file. #[derive(Debug, Eq, PartialEq, Clone, Copy, Hash, EnumIter)] pub enum NotificationEvents { ServerConnect, @@ -65,9 +72,11 @@ impl TryFrom<&str> for NotificationEvents { } } +/// Input audio state. pub struct AudioInput { device: DefaultAudioInputDevice, + /// Voice packets received from the network. channel_receiver: Arc> + Unpin>>>, } @@ -114,10 +123,15 @@ impl AudioInput { pub struct AudioOutput { device: DefaultAudioOutputDevice, + /// The volume and mute-status of a user ID. user_volumes: Arc>>, + /// The client stream per user ID. A separate stream is kept for UDP and TCP. + /// + /// Shared with [DefaultAudioOutputDevice]. client_streams: Arc>, + /// Which sound effect should be played on an event. sounds: HashMap>, } @@ -140,6 +154,7 @@ impl AudioOutput { Ok(res) } + /// Loads sound effects, getting unspecified effects from [get_default_sfx]. pub fn load_sound_effects(&mut self, sound_effects: &[SoundEffect]) { let overrides: HashMap<_, _> = sound_effects .iter() @@ -153,6 +168,7 @@ impl AudioOutput { }) .collect(); + // This makes sure that every [NotificationEvent] is present in [self.sounds]. self.sounds = NotificationEvents::iter() .map(|event| { let bytes = overrides @@ -195,6 +211,7 @@ impl AudioOutput { .collect(); } + /// Decodes a voice packet. pub fn decode_packet_payload( &self, stream_type: VoiceStreamType, @@ -207,11 +224,13 @@ impl AudioOutput { .decode_packet((stream_type, session_id), payload); } + /// Sets the volume of the output device. pub fn set_volume(&self, output_volume: f32) { self.device.set_volume(output_volume); } - pub fn set_user_volume(&self, id: u32, volume: f32) { + /// Sets the incoming volume of a user. + pub(crate) fn set_user_volume(&self, id: u32, volume: f32) { match self.user_volumes.lock().unwrap().entry(id) { Entry::Occupied(mut entry) => { entry.get_mut().0 = volume; @@ -222,6 +241,7 @@ impl AudioOutput { } } + /// Mutes another user. pub fn set_mute(&self, id: u32, mute: bool) { match self.user_volumes.lock().unwrap().entry(id) { Entry::Occupied(mut entry) => { @@ -233,12 +253,14 @@ impl AudioOutput { } } + /// Queues a sound effect. pub fn play_effect(&self, effect: NotificationEvents) { let samples = self.sounds.get(&effect).unwrap(); self.client_streams.lock().unwrap().extend(None, samples); } } +/// Reads a sound effect from disk. // moo fn get_sfx(file: &str) -> Cow<'static, [u8]> { let mut buf: Vec = Vec::new(); @@ -251,6 +273,7 @@ fn get_sfx(file: &str) -> Cow<'static, [u8]> { } } +/// Gets the default sound effect. fn get_default_sfx() -> Cow<'static, [u8]> { Cow::from(include_bytes!("fallback_sfx.wav").as_ref()) } -- cgit v1.2.1 From 0f94d30e5ab7945582e1fc7124bbe50c42f37a45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= Date: Tue, 15 Jun 2021 12:51:46 +0200 Subject: incoming -> outgoing packets --- mumd/src/audio.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'mumd/src/audio.rs') diff --git a/mumd/src/audio.rs b/mumd/src/audio.rs index 46f7050..b3c809d 100644 --- a/mumd/src/audio.rs +++ b/mumd/src/audio.rs @@ -76,7 +76,7 @@ impl TryFrom<&str> for NotificationEvents { pub struct AudioInput { device: DefaultAudioInputDevice, - /// Voice packets received from the network. + /// Outgoing voice packets that should be sent over the network. channel_receiver: Arc> + Unpin>>>, } -- cgit v1.2.1 From 9350dd303bbfc1534f61f996bd4206b1e10e5f34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= Date: Tue, 15 Jun 2021 12:52:48 +0200 Subject: more audioinput --- mumd/src/audio.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'mumd/src/audio.rs') diff --git a/mumd/src/audio.rs b/mumd/src/audio.rs index b3c809d..f52389a 100644 --- a/mumd/src/audio.rs +++ b/mumd/src/audio.rs @@ -72,7 +72,8 @@ impl TryFrom<&str> for NotificationEvents { } } -/// Input audio state. +/// Input audio state. Input audio is picket up from an [AudioInputDevice] (e.g. +/// a microphone) and sent over the network. pub struct AudioInput { device: DefaultAudioInputDevice, -- cgit v1.2.1 From bbaf2c576b324cf2f519220930d5c99b0496023e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= Date: Tue, 15 Jun 2021 12:54:19 +0200 Subject: audioouput doc --- mumd/src/audio.rs | 3 +++ 1 file changed, 3 insertions(+) (limited to 'mumd/src/audio.rs') diff --git a/mumd/src/audio.rs b/mumd/src/audio.rs index f52389a..6c20d08 100644 --- a/mumd/src/audio.rs +++ b/mumd/src/audio.rs @@ -122,6 +122,9 @@ impl AudioInput { } } +/// Audio output state. The audio is received from each client over the network, +/// decoded, merged and finally played to an [AudioOutputDevice] (e.g. speaker, +/// headphones, ...). pub struct AudioOutput { device: DefaultAudioOutputDevice, /// The volume and mute-status of a user ID. -- cgit v1.2.1 From 988ac16195e24c71ba17c4103448addb299c58bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= Date: Tue, 15 Jun 2021 12:54:52 +0200 Subject: ~~pub(crate)~~ --- mumd/src/audio.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'mumd/src/audio.rs') diff --git a/mumd/src/audio.rs b/mumd/src/audio.rs index 6c20d08..78e10b9 100644 --- a/mumd/src/audio.rs +++ b/mumd/src/audio.rs @@ -234,7 +234,7 @@ impl AudioOutput { } /// Sets the incoming volume of a user. - pub(crate) fn set_user_volume(&self, id: u32, volume: f32) { + pub fn set_user_volume(&self, id: u32, volume: f32) { match self.user_volumes.lock().unwrap().entry(id) { Entry::Occupied(mut entry) => { entry.get_mut().0 = volume; -- cgit v1.2.1