Ratatui Audio with Rodio: Sound FX for Rust Text‑based UI 🔊 # Ratatui Audio with Rodio: Sound FX for Rust Text-based UI 🔊 #

🧱 Ratatui Audio with Rodio: What I Built #

I didn’t really want background music, just sound effects to play when the player starts the challenge, and then to provide audio feedback if their latest solution attempt was good or perfect. Finally, I wanted to play some audio when each firework on the victory screen ignited. I found some quite small wave files for each of these, and converted them to MP3s.

About Rodio #

Rodio uses a number of lower level crates under the hood, simplifying adding audio via their single higher level API. These, lower-level, crates include:

• cpal for playback;
• symphonia for MP4 and AAC playback;
• hound for WAV playback;
• lewton for Vorbis playback; and
• claxon for FLAC playback.

I just needed MP3s, so disabled default features, and only added symphonia-mp3 back in the project Cargo.toml, to keep the binary size in check:

    
1 [package]
2 name = "countdown-numbers"
3 version = "0.1.0"
4 edition = "2021"
5 license = "BSD-3-Clause"
6 repository = "https://github.com/rodneylab/countdown-numbers"
7 # ratatui v0.26.3 requires 1.74.0 or newer
8 rust-version = "1.74"
9 description = "Trying Ratatui TUI 🧑🏽‍🍳 building a text-based UI number game in the Terminal 🖥️ in Rust with Ratatui immediate mode rendering."
10  
11 [dependencies]
12 num_parser = "1.0.2"
13 rand = "0.8.5"
14 ratatui = "0.28.0"
15 rodio = { version = "0.19.0", default-features = false, features = ["symphonia-mp3"] }

  

🐎 Adding Rodio #

The Rodio docs  give a couple of examples for getting going. Those examples read and decode an ogg file from a local folder within the project. This makes uses of the Rodio decoder struct, either appending it to a Rodio sink, or playing decoder output directly on an output stream. Either way, the audio is decoded and played straight away.

That setup works well for longer files, played once. For the game, I have a few sound effects that might be played dozens of times. It seemed a little extravagant to read from a file and decode each time I needed to play the same sound effect. Luckily, I found a Stack Overflow post with an alternative approach , letting you buffer the decoder output. Since the audio files were no bigger that 10 KB, I was happy to buffer them as the app starts up and keep them in memory.

Rust Code #

I created a SoundEffects struct for holding all the sound effects, as there are only five of them. For an app with more, I would attempt a cleaner solution, but this approach keeps things simple for what I have.

    
1 use std::{fs::File, path::Path};
2 
3 use rodio::{
4     source::{Buffered, Source},
5     Decoder,
6 };
7 
8 pub struct SoundEffects {
9     pub start: Buffered<Decoder<File>>,
10     pub end: Buffered<Decoder<File>>,
11     pub perfect: Buffered<Decoder<File>>,
12     pub valid: Buffered<Decoder<File>>,
13     pub firework: Buffered<Decoder<File>>,
14 }
15 
16 fn buffer_sound_effect<P: AsRef<Path>>(path: P) -> Buffered<Decoder<File>> {
17     let sound_file = File::open(&path)
18         .unwrap_or_else(|_| panic!("Should be able to load `{}`", path.as_ref().display()));
19     let source = Decoder::new(sound_file).unwrap_or_else(|_| {
20         panic!(
21             "Should be able to decode audio file `{}`",
22             path.as_ref().display()
23         )
24     });
25 
26     source.buffered()
27 }
28 
29 impl Default for SoundEffects {
30     fn default() -> Self {
31         SoundEffects {
32             start: buffer_sound_effect("./assets/start.mp3"),
33             end: buffer_sound_effect("./assets/end.mp3"),
34             perfect: buffer_sound_effect("./assets/perfect.mp3"),
35             valid: buffer_sound_effect("./assets/valid.mp3"),
36             firework: buffer_sound_effect("./assets/firework.mp3"),
37         }
38     }
39 }

  

The default initializer for the SoundEffects struct just creates a buffered decoding for each of the effects, which can be called later from the app code.

In app code, I can then clone one of these buffers and add it to a sink to play it. For example in the main game loop:

    
1 fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
2     // ...TRUNCATED   
3  
4     let (_stream, stream_handle) = OutputStream::try_default().unwrap();
5     let sink = Sink::try_new(&stream_handle).unwrap();
6     let sound_effects = SoundEffects::default();
7  
8     loop {
9         if event::poll(timeout)? {
10             if let Event::Key(key) = event::read()? {
11               // ...TRUNCATED
12  
13                 match app.current_screen {
14                   // ...TRUNCATED
15                     CurrentScreen::PickingNumbers => match key.code {
16                         KeyCode::Enter => {
17                             if app.is_number_selection_complete() {
18                                 app.current_screen = CurrentScreen::Playing;
19                                 sink.append(sound_effects.start.clone());
20                             }
21                         }
22                     }
23                 }
24             }
25         }
26         // TRUNCATED...
27     }
28 }

  

We initialize the sink ahead of the main loop, then play the buffered sound from within it (line 19), by calling sink.append(). sink.append() pushes the buffer into a queue and plays it immediately (if nothing is already playing), or waits until the last sound has finished before starting. That setup works here, and if you need to play sounds simultaneously, you can create multiple sinks. This setup also avoids borrow checker issues with consuming the File struct, which might arise when decoding the File within the main loop.

🙌🏽 Ratatui Audio with Rodio: Wrapping Up #

In this Ratatui audio with Rodio post, I briefly ran through how I added audio to the Ratatui Countdown game. In particular, I talked about:

• why I added Rodio;
• why you might buffer Rodio to avoid borrow checker issues in a game loop; and
• how I buffered MP3 sound FX with Rodio.

I hope you found this useful. As promised, you can get the full project code on the Rodney Lab GitHub repo . I would love to hear from you, if you are also new to Rust game development. Do you have alternative resources you found useful? How will you use this code in your own projects?

🙏🏽 Ratatui Audio with Rodio: Feedback #

If you have found this post useful, see links below for further related content on this site. Let me know if there are any ways I can improve on it. I hope you will use the code or starter in your own projects. Be sure to share your work on X, giving me a mention, so I can see what you did. Finally, be sure to let me know ideas for other short videos you would like to see. Read on to find ways to get in touch, further below. If you have found this post useful, even though you can only afford even a tiny contribution, please consider supporting me through Buy me a Coffee.

Rodney

@askRodney

Just dropped a new post on adding audio to a Ratatui Rust Terminal app or game, using Rodio.

We look at Rodio Symphonia MP3 features and how you can buffer decoded MP3 audio.

Hope you find it useful!

#askRodneyhttps://t.co/FZRoEoTHdD

— Rodney (@askRodney) June 19, 2024

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on X (previously Twitter) and also, join the #rodney  Element Matrix room. Also, see further ways to get in touch with Rodney Lab. I post regularly on Game Dev as well as Rust and C++ (among other topics). Also, subscribe to the newsletter to keep up-to-date with our latest projects.