ISSoundAdditions is a Swift Package for macOS that allows to control the volume of the default output device, as well as muting and unmuting. The entire implementation relies on various CoreAudio calls, but they are exposed in a clean and simple Swift flavor.
ISSoundAdditions is available via Swift Package Manager.
.package(url: "https://github.com/InerziaSoft/ISSoundAdditions", from: "<see GitHub releases>")
To find out the latest version, look at the Releases tab of this repository.
All the functions of the library are exposed through the Sound
class. This class cannot be instantiated, but it provides a structure to access the output
, which represents the default device using for sound output. This structure also allows for future improvements, such as adding support for input
devices.
There are two ways to interact with the library: simple mode (via properties) or manual mode (via method calls).
If your application doesn't care about errors management and you're just looking for a simple way to change the system volume, mute or unmute, you can interact with the properties offered by the shared instance of SoundOutputManager
.
// Retrieve the default output device
let deviceID = Sound.output.defaultOutputDevice
// Get the current volume
let currentVolume = Sound.output.volume
// Set the volume (values between 0 and 1)
Sound.output.volume = 0.7
// Get the mute property value
let isMuted = Sound.output.isMuted
// Mute or unmute
Sound.output.isMuted = true
Sound.output.isMuted = false
When interacting with these properties, all errors will be ignored. When running in Debug mode, you will still be able to see some of the errors, as CoreAudio logs them to the console.
This library also provides some additional methods that interact with the properties shown above.
// Increase the volume by a given amount
Sound.output.increaseVolume(by: 0.2)
// Decrease the volume by a given amount
Sound.output.decreaseVolume(by: 0.2)
// Set the volume and, optionally,
// automatically mutes or unmutes if the resulting volume
// is below or above the given threshold (which defaults to 0.005).
// The `autoMuteUnmute` parameter can also be used on the other
// two methods above.
Sound.output.setVolume(0, autoMuteUnmute: true)
A lot of things can go wrong when trying to manipulate the system volume, muting, unmuting and even when getting the current default output device. If you're interested in intercepting these errors, you can call the methods provided by the shared instance of SoundOutputManager
.
// Retrieve the default output device
// Returns `nil` if no device is set or throws if an error occurs.
let deviceID = try Sound.output.retrieveDefaultOutputDevice()
// Get the current volume
// Throws if an error occurs and will also throw if
// the current output device doesn't have a volume (eg. virtual devices)
let currentVolume = try Sound.output.readVolume
// Set the volume (values between 0 and 1)
// Throws if an error occurs, including when the current output device
// doesn't have a volume or doesn't allow changing it.
try Sound.output.setVolume(0.7)
// Get the mute property value
// Throws if an error occurs and will also throw if
// the current output device doesn't have the mute property.
let isMuted = try Sound.output.readMute()
// Mute or unmute
// Throws if an error occurs, including when the current output device
// doesn't have the mute property or doesn't allow changing it.
try Sound.output.mute(true)
try Sound.output.mute(false)
All classes and methods are fully documented.
You can find the autogenerated documentation here.
ISSoundAdditions is compatible with macOS 10.12 or higher.
If you're targeting older versions of macOS, you can download and use version 1. Version 1 requires macOS 10.6 or later.
All contributions to expand the library are welcome. Fork the repo, make the changes you want, and open a Pull Request.
If you make changes to the codebase, we are not enforcing a coding style, but we may ask you to make changes based on how the rest of the library is made.
The library can be considered stable and can be used in Production apps.
Starting with version 2, in case breaking changes are introduced, we will follow Semantic Versioning strictly.
ISSoundAdditions was created by Massimo Moiso (InerziaSoft), based on an idea of António Nunes. The library has been ported to Swift by Alessio Moiso (InerziaSoft).
ISSoundAdditions is distributed under the MIT license. See LICENSE for details.