Skip to content

Commit b2cd7db

Browse files
committed
Update readme
1 parent 83ef7fe commit b2cd7db

File tree

1 file changed

+20
-14
lines changed

1 file changed

+20
-14
lines changed

README.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,16 @@ pip3 install .
1313
```
1414

1515
#### Note:
16-
For running on Linux you will need to install one of these programs: xrandr, ddcutil, [light](https://github.com/haikarainen/light) or xbacklight.
16+
For running on Linux you may need to install one of these programs: xrandr, ddcutil, [light](https://github.com/haikarainen/light) or xbacklight. If you do not wish to install any 3rd party programs you will have to run this module as root.
1717
Here is a quick outline of each program:
1818

19-
Program | Is it Fast | Works with laptop displays | Works with external monitors | Multi-display support | Requires RandR support
20-
------------|------------|----------------------------|------------------------------|---------------------------------------|-----------------------
21-
ddcutil | No | No | Yes | Yes | No
22-
xrandr | Yes | Yes | Yes | Yes | Yes
23-
xbacklight | Yes | Yes | No | Yes but not individually controllable | Yes
24-
light | Yes | Yes | No | Yes | No
19+
Program | Works on laptop displays | Works on external monitors | Multi-display support | Requires RandR support | Requires Root
20+
------------|--------------------------|----------------------------|---------------------------------------|------------------------|--------------
21+
ddcutil | No | Yes (slow) | Yes | No | Yes
22+
xrandr | Yes | Yes | Yes | Yes | No
23+
xbacklight | Yes | No | Yes but not individually controllable | Yes | No
24+
light | Yes | No | Yes | No | No
25+
[No program]| Yes | No | Yes | No | Yes
2526

2627
Something to be aware of is that xrandr does not change the backlight of the display, it just changes the brightness by applying a filter to the pixels to make them look dimmer/brighter.
2728

@@ -75,7 +76,7 @@ Raises `ScreenBrightnessError` upon failure
7576
**Arguments:**
7677

7778
* `display` - the specific display you wish to adjust. This can be an integer or a string (EDID, serial, name or model)
78-
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'` or `'xbacklight'`
79+
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'`, `'sysfiles'` or `'xbacklight'`
7980
* `verbose_error` - a boolean value to control how much detail any error messages should contain
8081

8182
**Usage:**
@@ -102,7 +103,7 @@ Raises `ScreenBrightnessError` upon failure
102103

103104
* `value` - the level to set the brightness to. Can either be an integer or a string.
104105
* `display` - the specific display you wish to adjust. This can be an integer or a string (EDID, serial, name or model)
105-
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'` or `'xbacklight'`
106+
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'`, `'sysfiles'` or `'xbacklight'`
106107
* `force` (Linux only) - if set to `False` then the brightness is never set to less than 1 because on Linux this often turns the screen off. If set to `True` then it will bypass this check
107108
* `verbose_error` - a boolean value to control how much detail any error messages should contain
108109
* `no_return` - boolean value, whether this function should return `None` or not. By default, the return value is the new brightness value but this behaviour is deprecated. In the future this function will return `None` by default.
@@ -169,7 +170,7 @@ Returns a list of the names of all detected monitors
169170

170171
**Arguments:**
171172

172-
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'` or `'xbacklight'`
173+
* `method` - the OS specific method to use. On Windows this can be `'wmi'` or `'vcp'` and on Linux this can be `'light'`, `'xrandr'`, `'ddcutil'`, `'sysfiles'` or `'xbacklight'`
173174

174175
**Usage:**
175176
```python
@@ -190,21 +191,26 @@ This software is licensed under the [MIT license](https://mit-license.org/)
190191
**Why this happens:**
191192
The way brightness is adjusted on Linux is the program tries to run shell commands to adjust the brightness.
192193
The programs it attempts to call are "light", "xrandr", "ddcutil" and "xbacklight".
193-
If none of these programs can be called a `ScreenBrightnessError` is raised
194+
If none of these programs are installed then it attempts to read/write to files located in the `/sys/class/backlight`
195+
directory, which will require root permissions.
196+
197+
If none of methods succeed, a `ScreenBrightnessError` is raised.
194198

195199
**How to fix it:**
196200
Install `xrandr`, `ddcutil`, `light`, or `xbacklight` using your system package manager. See the installation section at the top of this document for instructions on how to do so.
201+
Or run the module as root if you do not wish to install 3rd party software.
197202

198203

199204
### I call `set_brightness()` and nothing happens (Linux)
200205
**Why this happens:**
201206
Light requires root access to run, which is usually provided when you manually install it using you package manager.
202207
If you installed xrandr or xbacklight, it only supports graphics drivers that support RandR.
203-
If you installed ddcutil, this requires root access to run for every query.
208+
If you installed ddcutil or have none of the recommended 3rd party softwares installed,
209+
you require root access to run for every query.
204210

205211
**How to fix it:**
206212
If you installed `xrandr` or `xbacklight`: make sure your graphics drivers support RandR.
207-
If you installed `ddcutil`: make sure to run the script with root permissions.
213+
If you installed `ddcutil` or none of the recommended 3rd party softwares: make sure to run the script with root permissions.
208214
If you installed `light`: follow [these steps](https://github.com/haikarainen/light#installation) making sure to run the install as sudo or re-compile from source (requires `autoconf` to be installed):
209215
```
210216
git clone https://github.com/haikarainen/light && cd light
@@ -214,7 +220,7 @@ sh autogen.sh && ./configure && make && sudo make install
214220

215221
### Using the `display` kwarg does nothing/creates exceptions (Linux)
216222
**Why this happens:**
217-
The `display` kwarg is only supported by the `Light`, `XRandr` and `DDCUtil` classes, not by `XBacklight`. So if you only have `xbacklight` installed on your system this kwarg will not work
223+
The `display` kwarg is only supported by the `Light`, `XRandr`, `DDCUtil` and `SysFiles` classes, not by `XBacklight`. So if you only have `xbacklight` installed on your system this kwarg will not work
218224

219225
**How to fix it:**
220226
Install `xrandr` or `ddcutil` or `light` using your system package manager. See the installation section at the top of this document for instructions on how to do so.

0 commit comments

Comments
 (0)