The audiomath.SystemVolume
sub-module
Utilities for manipulating the operating-system master volume and/or mixer.
On Windows, this requires the third-party packages
comtypes
andpsutil
(via our fork of Andre Miras’pycaw
, which is included).On macOS, it uses Applescript.
On Linux, there is a highly-experimental implementation based on
pacmd
andpactl
(so these PulseAudio command-line utilities must be installed).
Because of its dependencies, this submodule is not imported
by default—you must explicitly import audiomath.SystemVolume
.
The recommended way to use this module is via the SystemVolumeSetting
context-manager object:
import audiomath
from audiomath.SystemVolume import SystemVolumeSetting
p = audiomath.Player(audiomath.TestSound())
with SystemVolumeSetting(0.1, mute=False):
p.Play(wait=True)
- audiomath.SystemVolume.GetVolume(dB=False, session='master')
Query volume level and mute settings.
If you want to query volume settings, change them, and later change them back,
SystemVolumeSettings
is a more usable option.The Linux implementation uses Pulse Audio utility
pacmd
. It is likely to break whenever the text format ofpacmd list-sinks
changes in future versions.
- audiomath.SystemVolume.SetVolume(level=None, dB=False, mute=None, session='master')
Sets volume level and/or mute status.
Consider using the context-manager class
SystemVolumeSetting
instead. For a description of the input arguments, seeSystemVolumeSetting
.The Linux implementation uses Pulse Audio utilities
pacmd
andpactl
. It is likely to break whenever the text format ofpacmd list-sinks
changes in future versions.
- class audiomath.SystemVolume.SystemVolumeSetting(level=None, dB=False, mute=None, session='master', verbose=False)
This class is a context-manager. It allows you to change the system volume temporarily, such that it automatically changes back to its previous setting when you are done:
import audiomath from audiomath.SystemVolume import SystemVolumeSetting p = audiomath.Player( audiomath.TestSound() ) with SystemVolumeSetting(0.1, mute=False): p.Play() audiomath.WaitFor(p) # otherwise we'll exit the `with` # clause before anything has been # streamed and won't hear the effect
For your convenience,
MAX_VOLUME
is a ready-instantiatedSystemVolumeSetting
made withlevel=1.0
andmute=False
:from audiomath.SystemVolume import MAX_VOLUME with MAX_VOLUME: p.Play(wait=True)
SystemVolumeSetting
instances can be combined together with the&
operator. This is only really useful on Windows where session-by-session control is possible:MUTE_FIREFOX = SystemVolumeSetting(mute=True, session='Mozilla Firefox') with MAX_VOLUME & MUTE_FIREFOX: p.Play(wait=True)
- Parameters:
level (float, None) – volume setting, from 0.0 to 1.0 (assuming
dB=False
) or from negative infinity to 0.0 (withdB=True
). UseNone
if you want to leave the level untouched and manipulate only themute
setting.dB (bool) – By default,
level
values are interpreted and expressed as relative power values from 0 to 1. However, withdB=True
you can choose to have them interpreted and expressed in decibels, i.e.10*log10(power)
, with 0.0 as the maximum.mute (bool, None) – Whether or not to mute the output. Use
None
to leave the mute setting untouched and manipulate only thelevel
.session (str, int) – (Windows only): control one individual “session” within the Windows mixer. A string will match all sessions with the specified
DisplayName
orProcess.name()
. An integer will match only the audio session with the specifiedProcessId
. A list of sessions instances can be retrieved byGetAllSessions()
.