<commit_before>=========
osxmmkeys
=========

osxmmkeys is a simple Python library for handling media keys on OS X.
The default behaviour can be prevented and overridden entirely.

Supported keys are:

- ``play_pause``
- ``next_track``
- ``prev_track``
- ``mute``
- ``volume_down``
- ``volume_up``
- ``backlight_down``
- ``backlight_up``
- ``kb_backlight_down``
- ``kb_backlight_up``


Usage:
------

.. code:: python

    import osxmmkeys

    def play_pause():
        print("Play/pause key was pressed")

    tap = osxmmkeys.Tap()
    tap.on('play_pause', play_pause)
    tap.run()<commit_msg>Add installation instructions and start fleshing out the readme<commit_after>=========
osxmmkeys
=========

osxmmkeys is a simple Python library for handling media keys on OS X.
Keys can be observed with no side effects, or have their default behaviours
overridden entirely.

Installation
------------

To install osxmmkeys with pip, use:

.. code:: bash

    $ pip install pyobjc-core
    $ pip install osxmmkeys

The extra install command is due to an issue_ in pyobjc.
It will work without it, but will be quite a bit slower.

.. _issue: https://bitbucket.org/ronaldoussoren/pyobjc/issue/21

Usage
-----

Simple example:

.. code:: python

    import osxmmkeys

    def handler():
        print("Play/pause key was pressed")

    tap = osxmmkeys.Tap()
    tap.on('play_pause', handler)
    tap.run()

Threaded example:

.. code:: python

    import osxmmkeys, time

    def handler():
        print("Play/pause key was pressed")

    tap = osxmmkeys.Tap()
    tap.on('play_pause', handler)
    tap.start()

    try:
        while True:
            time.sleep(1)
    except (KeyboardInterrupt, SystemExit):
        tap.stop()

Supported key names:

- ``play_pause``
- ``next_track``
- ``prev_track``
- ``mute``
- ``volume_down``
- ``volume_up``
- ``backlight_down``
- ``backlight_up``
- ``kb_backlight_down``
- ``kb_backlight_up``
{'fraction_non_alphanumeric': 0.1483402489626556, 'fraction_numerical': 0.0015560165975103733, 'mean_word_length': 3.1843817787418653, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1810582', 'n_tokens_mistral': 644, 'n_tokens_neox': 611, 'n_words': 187}