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 and psutil (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 and pactl (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 of pacmd 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, see SystemVolumeSetting.

The Linux implementation uses Pulse Audio utilities pacmd and pactl. It is likely to break whenever the text format of pacmd 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-instantiated SystemVolumeSetting made with level=1.0 and mute=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 (with dB=True). Use None if you want to leave the level untouched and manipulate only the mute setting.
dB (bool) – By default, level values are interpreted and expressed as relative power values from 0 to 1. However, with dB=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 the level.
session (str, int) – (Windows only): control one individual “session” within the Windows mixer. A string will match all sessions with the specified DisplayName or Process.name(). An integer will match only the audio session with the specified ProcessId. A list of sessions instances can be retrieved by GetAllSessions().

The audiomath.SystemVolume sub-module

The `audiomath.SystemVolume` sub-module