API¶

Monitor¶

class monitorcontrol.monitorcontrol.InputSource(value)¶: Monitor input sources.

exception monitorcontrol.monitorcontrol.InputSourceValueError(message: str, value: int)¶

Raised upon an invalid (out of spec) input source value.

https://github.com/newAM/monitorcontrol/issues/93

value¶

The value of the input source that was invalid.

Type: int

class monitorcontrol.monitorcontrol.Monitor(vcp: monitorcontrol.vcp.vcp_abc.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_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() → monitorcontrol.monitorcontrol.InputSource ¶

Gets the monitors input source

Returns: Current input source.

Example

Basic Usage:

from monitorcontrol import get_monitors

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

Handling out-of-spec inputs (observed for USB type-C inputs):

from monitorcontrol import get_monitors, InputSourceValueError

for monitor in get_monitors():
    with monitor:
        try:
            print(monitor.get_input_source())
        except InputSourceValueError as e:
            print(e.value)

Raises

VCPError – Failed to get input source from the VCP.
InputSourceValueError – Input source value is not within the MCCS defined inputs.

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() → monitorcontrol.monitorcontrol.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.
ValueError – Set power state outside of valid range.
KeyError – Set power mode string is invalid.

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
    ],
}

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: Union[int, str, monitorcontrol.monitorcontrol.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: Union[int, str, monitorcontrol.monitorcontrol.PowerMode])¶

Set the monitor power mode.

Parameters: value – An integer power mode, or a string represeting 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.

class monitorcontrol.monitorcontrol.PowerMode(value)¶

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_monitors() → List[monitorcontrol.monitorcontrol.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[Type[monitorcontrol.vcp.vcp_abc.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.