rotilities 0.1.2

A helper crate to easily use Rodio in your projects
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

use std::{fs::File, io::BufReader};
use rodio::Decoder;


pub fn get_source(filename: &str) -> Decoder<BufReader<File>> {
    let source = rodio::Decoder::new(
        BufReader::new(
            File::open(format!("./{filename}"))
                .expect("Failed to open file")
        )
    );
    return source.expect("Failed to decode file")
}


///This function creates a sink (audio stream) and returns it (for example to a variable).
///-> Maximum control, all Rodio sink functions work with this
///
/// # Example
///
/// ```
/// let sink = new_sink();
/// ```
pub fn new_sink() -> rodio::Sink {
    let (_stream,stream_handle) = rodio::OutputStream::try_default()
        .expect("Creating OuputStream Failed");
    let sink = rodio::Sink::try_new(&stream_handle)
        .expect("Sink creation failed");
    return sink;
}


//These functions require an existing sink and will manipulate it

/// Add an audio file to the queue of the given sink.
/// Requires an existing sink
///
/// # Example
///
/// ```
/// let sink = new_sink();
/// play_audio(sink, "file.mp3");
/// ```
pub fn play_audio(sink: &rodio::Sink, filename: &str) {
    sink.append(get_source(filename));
}

/// Stops audio playback and clears the queue of a sink.
/// Requires an existing sink
///
/// # Example
///
/// ```
/// //this example plays the sound "file.mp3" for 5 seconds, then stops it.
///
/// let sink = new_sink();
///
/// play_audio(&sink, "file.mp3");
/// std::thread::sleep(std::time::Duration::from_secs(5));
///
/// stop_audio(&sink);
/// ```
pub fn stop_audio(sink: &rodio::Sink) {
    sink.stop();
}

/// Pauses audio playback of a sink without affecting the sink's queue.
/// Requires an existing sink
///
/// # Example
///
/// ```
/// //this example plays the sound "file.mp3" for 5 seconds, then pauses it
///
/// let sink = new_sink();
///
/// play_audio(&sink, "file.mp3");
/// std::thread::sleep(std::time::Duration::from_secs(5));
///
/// pause_audio(&sink);
/// ```
pub fn pause_audio(sink: &rodio::Sink) {
    sink.pause();
}

/// Resumes audio playback of a sink.
/// Requires and existing sink
///
/// # Example
///
/// ```
/// //this example plays the sound "file.mp3" for 5 seconds, pauses it for 2 seconds, then resumes it
///
/// let sink = new_sink();
///
/// play_audio(&sink, "file.mp3");
/// std::thread::sleep(std::time::Duration::from_secs(5));
///
/// pause_audio(&sink);
/// std::thread::sleep(std::time::Duration::from_secs(2));
///
/// resume_audio(&sink);
/// ```
pub fn resume_audio(sink: &rodio::Sink) {
    sink.play();
}

/// Set the volume level of a sink.
/// Requires an existing sink
///
/// # Example
///
/// ```
/// //this example plays the sound "file.mp3" and halves the volume after 5 seconds.
///
/// let sink = new_sink();
///
/// play_audio(&sink, "file.mp3");
/// std::thread::sleep(std::time::Duration::from_secs(5));
///
/// set_audio_volume(&sink, 0.5);
/// ```
pub fn set_audio_volume(sink: &rodio::Sink, volume: f32) {
    sink.set_volume(volume);
}


/// This function will create its own Sink and directly play audio using it.
/// -> Less Control but useful for playing short or multiple overlapping sound
pub fn play_audio_once(filename: &str) {
    let sink = new_sink();
    play_audio(&sink, filename);
}