Metadata-Version: 2.4
Name: flx4py
Version: 0.1.0
Summary: Python library for the Pioneer DDJ-FLX4 DJ controller.
License-Expression: MIT
License-File: LICENSE
Keywords: midi,dj,controller,pioneer,ddj-flx4,ddj,flx4
Author: Arne K. (TRC-Loop)
Author-email: me@arne.sh
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: dev
Provides-Extra: docs
Requires-Dist: mido (>=1.3.3,<2.0.0)
Requires-Dist: mkdocs (>=1.6.0,<2.0.0) ; extra == "dev"
Requires-Dist: mkdocs (>=1.6.0,<2.0.0) ; extra == "docs"
Requires-Dist: mkdocs-material (>=9.5.0) ; extra == "dev"
Requires-Dist: mkdocs-material (>=9.5.0) ; extra == "docs"
Requires-Dist: mkdocstrings[python] (>=0.24.0) ; extra == "dev"
Requires-Dist: mkdocstrings[python] (>=0.24.0) ; extra == "docs"
Requires-Dist: python-rtmidi (>=1.5.8,<2.0.0)
Project-URL: Documentation, https://TRC-Loop.github.io/flx4py/
Project-URL: Homepage, https://github.com/TRC-Loop/flx4py
Project-URL: Issues, https://github.com/TRC-Loop/flx4py/issues
Project-URL: Repository, https://github.com/TRC-Loop/flx4py
Description-Content-Type: text/markdown

# flx4py

Python library for the Pioneer DDJ-FLX4 DJ controller.

Full programmatic access to every button, knob, fader, jog wheel, and LED on the device — with a clean, callback-based API.

```python
import flx4py

controller = flx4py.DDJFlx4()

@controller.on_pad(deck=1, pressed=True)
def pad_pressed(event: flx4py.PadEvent):
    controller.leds.set_pad(event.deck, event.pad, True)

@controller.on_knob("CROSSFADER")
def crossfader(event: flx4py.KnobEvent):
    controller.leds.set_level_meter(1, event.value)
    controller.leds.set_level_meter(2, 1.0 - event.value)

with controller:
    import time
    while True:
        time.sleep(1)
```

## Install

```bash
pip install flx4py
```

Requires Python 3.10+ and a DDJ-FLX4 connected over USB.

## Features

- **Callbacks** for pads, buttons, knobs, faders, jog wheels, and the browse encoder
- **LED control** for pads (all modes), transport buttons, tab keys, FX buttons, and VU meters
- **Built-in animations** — wave, knight rider, breathing, sparkle, ping pong, rainbow chase
- **Current value queries** — ask for the last known position of any knob or fader
- 14-bit resolution for faders and knobs
- Context manager for clean resource management

## Documentation

Full docs at **[trc-loop.github.io/flx4py](https://trc-loop.github.io/flx4py/)**

## Quick reference

```python
# Pads
@controller.on_pad(deck=1, pressed=True)
def handler(event: flx4py.PadEvent): ...

# Buttons
@controller.on_button("PLAY_PAUSE", deck=1, pressed=True)
def handler(event: flx4py.ButtonEvent): ...

# Knobs / faders
@controller.on_knob("CH_FADER", deck=1)
def handler(event: flx4py.KnobEvent): ...  # event.value = 0.0–1.0

# Jog wheels
@controller.on_jog(deck=1, surface="top")
def handler(event: flx4py.JogEvent): ...  # event.direction = +1 or -1

# Browse encoder
@controller.on_browse()
def handler(event: flx4py.BrowseEvent): ...  # event.steps = ±n

# LEDs
controller.leds.set_pad(deck=1, pad=0, on=True)
controller.leds.set_button("PLAY_PAUSE", on=True, deck=1)
controller.leds.set_level_meter(deck=1, level=0.75)
controller.leds.all_off()

# Query current values
fader = controller.get_value("CH_FADER", deck=1)    # 0.0–1.0
tempo = controller.get_value("TEMPO", deck=1)        # -1.0–1.0
cross = controller.get_value("CROSSFADER")           # 0.0–1.0
```

## License

MIT

