volumecontrol-core 0.1.2

Common traits, errors and utilities for volumecontrol crates
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

use std::fmt;

use crate::{AudioError, DeviceInfo};

/// Common interface for audio device volume control.
///
/// Implementors represent a single audio output device and expose uniform
/// methods for querying and changing its volume and mute state.
///
/// Every implementor must also implement [`fmt::Display`].  The conventional
/// format is `"name (id)"`, e.g. `"Speakers ({0.0.0.00000000}.{…})"`.
pub trait AudioDevice: Sized + fmt::Display {
    /// Returns the system default audio output device.
    ///
    /// # Errors
    ///
    /// Returns an error if the default device cannot be resolved.
    fn from_default() -> Result<Self, AudioError>;

    /// Returns the audio device identified by `id`.
    ///
    /// # Errors
    ///
    /// Returns [`AudioError::DeviceNotFound`] if no device with the given
    /// identifier exists, or another error if the lookup fails.
    fn from_id(id: &str) -> Result<Self, AudioError>;

    /// Returns the first audio device whose name contains `name`
    /// (case-insensitive substring match).
    ///
    /// The comparison is performed in a case-insensitive manner on all
    /// platforms, so `"airpods"` will match `"AirPods Pro"`.
    ///
    /// # Errors
    ///
    /// Returns [`AudioError::DeviceNotFound`] if no matching device is found,
    /// or another error if the lookup fails.
    fn from_name(name: &str) -> Result<Self, AudioError>;

    /// Lists all available audio devices.
    ///
    /// # Errors
    ///
    /// Returns an error if the device list cannot be retrieved.
    fn list() -> Result<Vec<DeviceInfo>, AudioError>;

    /// Returns the current volume level in the range `0..=100`.
    ///
    /// # Errors
    ///
    /// Returns an error if the volume cannot be read.
    fn get_vol(&self) -> Result<u8, AudioError>;

    /// Sets the volume level.
    ///
    /// `vol` is clamped to `0..=100` before being applied.
    ///
    /// # Errors
    ///
    /// Returns an error if the volume cannot be set.
    fn set_vol(&self, vol: u8) -> Result<(), AudioError>;

    /// Returns `true` if the device is currently muted.
    ///
    /// # Errors
    ///
    /// Returns an error if the mute state cannot be read.
    fn is_mute(&self) -> Result<bool, AudioError>;

    /// Mutes or unmutes the device.
    ///
    /// # Errors
    ///
    /// Returns an error if the mute state cannot be changed.
    fn set_mute(&self, muted: bool) -> Result<(), AudioError>;

    /// Returns the unique identifier for this device.
    ///
    /// The returned value is the same opaque string that [`Self::list`] yields
    /// as [`DeviceInfo::id`] and that [`Self::from_id`] accepts as its argument.
    ///
    /// The value is guaranteed to be non-empty.
    ///
    /// # Platform-specific formats
    ///
    /// | Platform | Format                                                  |
    /// |----------|---------------------------------------------------------|
    /// | Linux    | PulseAudio sink name (e.g. `alsa_output.pci-0000_…`)    |
    /// | Windows  | WASAPI endpoint ID (e.g. `{0.0.0.00000000}.{…}`)       |
    /// | macOS    | CoreAudio device UID (numeric string, e.g. `"73"`)      |
    fn id(&self) -> &str;

    /// Returns the human-readable display name of this device.
    ///
    /// The returned value is the same string that [`Self::list`] yields as
    /// [`DeviceInfo::name`] and that [`Self::from_name`]
    /// uses for substring matching.
    ///
    /// The value is guaranteed to be non-empty.
    ///
    /// # Platform-specific formats
    ///
    /// | Platform | Format                                                  |
    /// |----------|---------------------------------------------------------|
    /// | Linux    | PulseAudio sink description (e.g. `"Built-in Audio"`)   |
    /// | Windows  | WASAPI endpoint friendly name (e.g. `"Speakers"`)       |
    /// | macOS    | CoreAudio device name (e.g. `"MacBook Pro Speakers"`)   |
    fn name(&self) -> &str;
}