API

Monitor

class monitorcontrol.monitorcontrol.AudioMuteMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Monitor audio mute modes.

off = 2: Off.

on = 1: On.

class monitorcontrol.monitorcontrol.ColorPreset(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): Monitor color presets.

class monitorcontrol.monitorcontrol.InputSource(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): Monitor input sources.

class monitorcontrol.monitorcontrol.Monitor(vcp: VCP)

A physical monitor attached to a Virtual Control Panel (VCP).

Typically, you do not use this class directly and instead use get_monitors() to get a list of initialized monitors.

All class methods must be called from within a context manager unless otherwise stated.

Parameters:: vcp – Virtual control panel for the monitor.

get_audio_mute_mode() → AudioMuteMode

Get the monitor audio mute mode.

Returns:: Value from the AudioMuteMode enumeration.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_audio_mute_mode())

Raises:

VCPError – Failed to get the audio mute mode.
ValueError – Set audio mute state outside of valid range.
KeyError – Set audio mute mode string is invalid.

get_color_preset() → int

Gets the monitors color preset.

Returns:: Current color preset. Valid values are enumerated in ColorPreset.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_color_preset())

Raises:: VCPError – Failed to get color preset from the VCP.

get_contrast() → int

Gets the monitors contrast.

Returns:: Current contrast value.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_contrast())

Raises:: VCPError – Failed to get contrast from the VCP.

get_input_source() → int

Gets the monitors input source

Returns:: Current input source.

Example

Basic Usage:

from monitorcontrol import get_monitors, InputSource

for monitor in get_monitors():
    with monitor:
        input_source_raw: int = monitor.get_input_source()
        print(InputSource(input_source_raw).name)

Raises:: VCPError – Failed to get input source from the VCP.

get_luminance() → int

Gets the monitors back-light luminance.

Returns:: Current luminance value.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_luminance())

Raises:: VCPError – Failed to get luminance from the VCP.

get_power_mode() → PowerMode

Get the monitor power mode.

Returns:: Value from the PowerMode enumeration.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_power_mode())

Raises:: VCPError – Failed to get the power mode.

get_vcp_capabilities() → dict

Gets the capabilities of the monitor

Returns:

Dictionary of capabilities in the following example format:

{
    "prot": "monitor",
    "type": "LCD",
    "cmds": {
            1: [],
            2: [],
            96: [15, 17, 18],
    },
    "inputs": [
        InputSource.DP1,
        InputSource.HDMI1,
        InputSource.HDMI2
        # this may return integers for out-of-spec values,
        # such as USB Type-C monitors
    ],
}

get_volume() → int

Gets the monitors sound volume level.

Returns:: Current sound volume value.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.get_volume())

Raises:: VCPError – Failed to get sound volume from the VCP.

set_audio_mute_mode(value: int | str | AudioMuteMode)

Set the monitor audio mute mode.

Parameters:: value – An integer audio mute mode, or a string representing the audio mute mode, or a value from AudioMuteMode.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        monitor.set_audio_mute_mode("standby")

Raises:

VCPError – Failed to get or set the audio mute mode
ValueError – audio mute state outside of valid range.
AttributeError – audio mute mode string is invalid.

set_color_preset(value: int | str | ColorPreset)

Sets the monitors color preset.

Parameters:: value – An integer color preset, or a string representing the color preset, or a value from ColorPreset.

Example

Basic Usage:

from monitorcontrol import get_monitors, ColorPreset

for monitor in get_monitors():
    with monitor:
        monitor.set_color_preset(ColorPreset.COLOR_TEMP_5000K)

Raises:

VCPError – Failed to set color preset in the VCP.
ValueError – Color preset outside valid range.
AttributeError – Color preset string is invalid.
TypeError – Unsupported value

set_contrast(value: int)

Sets the monitors back-light contrast.

Parameters:: value – New contrast value (typically 0-100).

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.set_contrast(50))

Raises:

ValueError – Contrast outside of valid range.
VCPError – Failed to set contrast in the VCP.

set_input_source(value: int | str | InputSource)

Sets the monitors input source.

Parameters:: value – New input source

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        print(monitor.set_input_source("DP1"))

Raises:

VCPError – Failed to get the input source.
KeyError – Set input source string is invalid.

set_luminance(value: int)

Sets the monitors back-light luminance.

Parameters:: value – New luminance value (typically 0-100).

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        monitor.set_luminance(50)

Raises:

ValueError – Luminance outside of valid range.
VCPError – Failed to set luminance in the VCP.

set_power_mode(value: int | str | PowerMode)

Set the monitor power mode.

Parameters:: value – An integer power mode, or a string representing the power mode, or a value from PowerMode.

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        monitor.set_power_mode("standby")

Raises:

VCPError – Failed to get or set the power mode
ValueError – Power state outside of valid range.
AttributeError – Power mode string is invalid.

set_volume(value: int)

Sets the monitors set_volume level.

Parameters:: value – New set_volume value (typically 0-100).

Example

Basic Usage:

from monitorcontrol import get_monitors

for monitor in get_monitors():
    with monitor:
        monitor.set_volume(50)

Raises:

ValueError – Luminance outside of valid range.
VCPError – Failed to set sound volume in the VCP.

class monitorcontrol.monitorcontrol.PowerMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Monitor power modes.

off_hard = 5: Hardware power off.

off_soft = 4: Software power off.

on = 1: On.

standby = 2: Standby.

suspend = 3: Suspend.

monitorcontrol.monitorcontrol.get_input_name(input_code: int) → str

Returns the input name for a given input code.

Parameters:: input_code – an integer representing a known (standard) input identifier
Returns:: A string containing the input name, or “UNKNOWN” plus the unknown code as hex

monitorcontrol.monitorcontrol.get_monitors() → List[Monitor]

Creates a list of all monitors.

Returns:: List of monitors in a closed state.
Raises:: VCPError – Failed to list VCPs.

Example

Setting the power mode of all monitors to standby:

for monitor in get_monitors():
    with monitor:
        monitor.set_power_mode("standby")

Setting all monitors to the maximum brightness using the context manager:

for monitor in get_monitors():
    with monitor:
        monitor.set_luminance(100)

monitorcontrol.monitorcontrol.get_vcps() → List[VCP]

Discovers virtual control panels.

This function should not be used directly in most cases, use get_monitors() get monitors with VCPs.

Returns:

List of VCPs in a closed state.

Raises:

NotImplementedError – not implemented for your operating system
VCPError – failed to list VCPs

Virtual Control Panel

exception monitorcontrol.vcp.VCPError: Base class for all VCP related errors.

exception monitorcontrol.vcp.VCPIOError: Raised on VCP IO errors.

exception monitorcontrol.vcp.VCPPermissionError: Raised on VCP permission errors.

class monitorcontrol.vcp.vcp_abc.VCP

Checksum Behaviour

By default if a monitor responds with a bad checksum this will be ignored on Windows, this is not controlable by the user.

To maintain consistentency across platforms checksums are disabled on Linux by default as well (see issue #5).

The behaviour of incorrect checksums on Linux can be set with the static class variable monitorcontrol.vcp.vcp_linux.LinuxVCP.CHECKSUM_ERRORS.

"ignore" (default) ignore checksum errors.
"strict" raise a VCPIOError.
"warning" log a warning.