acpibacklight

acpibacklight
=============

|PyPI version|

A python library and script for changing brightness on Linux via acpi.
Allows for easing animations too!

.. code:: bash

    pip install acpibacklight

You can use the script ``acpi-ease-backlight`` to adjust the backlight
with easing via acpi on your device. See ``acpi-ease-backlight --help``
for options.

CLI Usage
---------

After installing via pip, use the script ``acpi-ease-backlight``. Here
is how you might use it:

.. code:: bash

    $ acpi-ease-backlight -h        # see help
    ...

    $ acpi-ease-backlight show      # show the current backlight value
    4000

    $ acpi-ease-backlight max       # show the your display's max backlight value
    4882

    $ acpi-ease-backlight set 2000  # set the backlight to 2000, over the default
                                    # duration of 0.25 seconds and using the default
                                    # easing function 'easeOutCubic'

    $ acpi-ease-backlight -d 1 -e easeInOutQuad set 3000
                                    # set the backlight to 3000 over duration of
                                    # 1 second, using the easing function 'easeInOutQuad'

    $ acpi-ease-backlight -d 0.5 dec 1000
                                    # decrease the current backlight value by
                                    # 1000 over a duration of 0.5 seconds

Library Usage
-------------

Instantiating
^^^^^^^^^^^^^

Use the class ``acpibacklight.AcpiBacklightControl`` for changing the
backlight level in various ways. ``AcpiBacklightControl`` is designed to
use python *with* statements similarly to file objects and python's
``open`` builtin:

.. code:: python

    from acpibacklight import AcpiBacklightControl

    with AcpiBacklightControl() as ctrl:
        # set the brightness without animating
        ctrl.brightness = 2000

        # get max brightness on this device
        new_brightness = ctrl.max

        # You can also use the animate function on the AcpiBacklightControl.
        # See the docstring for kwargs
        ctrl.animate(new_brightness, duration=0.75)

Alternatively, you can construct, then open, then close the
``AcpiBacklightControl``:

.. code:: python

    ctrl = AcpiBacklightControl()
    ctrl.open()
    ctrl.animate(ctrl.brightness - 1000)
    ctrl.close()

If you have multiple ACPI backlight devices, specify the name when
constructing the ``AcpiBacklightControl``. Otherwise, the default is the
first device directory found.

.. code:: python

    ctrl = AcpiBacklightControl(device_dir='intel_backlight')

Easing Functions
^^^^^^^^^^^^^^^^

You can pass an easing function to be used in ``animate()`` by the
``easing_func`` keyword arg. This package uses
`PyTweening <https://github.com/asweigart/pytweening>`__ for its default
animation and the CLI, so you can easily pass one of those:

.. code:: python

    import pytweening
    ctrl.animate(2345, easing_func=pytweening.easeInOutBounce)

Finally, if you want to create and pass your own easing function, it
should take one paramater (time) between 0 and 1, and return a value
between 0 and 1. For instance, a linear easing function would look like:

.. code:: python

    def linear_easing(t):
      # t is always in the range [0, 1]
      return t

    # ...
    ctrl.animate(1234, easing_func=linear_easing)

.. |PyPI version| image:: https://badge.fury.io/py/acpibacklight.svg
   :target: https://badge.fury.io/py/acpibacklight