xair-api


Namexair-api JSON
Version 2.3.1 PyPI version JSON
download
home_pagehttps://github.com/onyx-and-iris/xair-api-python
SummaryRemote control Behringer X-Air | Midas MR mixers through OSC
upload_time2024-02-15 18:36:17
maintainer
docs_urlNone
authoronyx-and-iris
requires_python>=3.10,<4.0
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            [![PyPI version](https://badge.fury.io/py/xair-api.svg)](https://badge.fury.io/py/xair-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/xair-api-python/blob/dev/LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
![Tests Status](./tests/xair/MR18.svg?dummy=8484744)

# Xair API

This package offers a python interface for the [Behringer XAir](https://www.behringer.com/series.html?category=R-BEHRINGER-XAIRSERIES), [Midas MR](https://www.midasconsoles.com/catalog.html?catalog=Category&category=C-MIDAS-MIXERS-DIGITALSTAGEBOXMIXERS) series of digital rack mixers. I only have access to an MR18 for testing so if there is an error in the kind maps feel free to raise an issue or PR.

For an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)

## Prerequisites

- Python 3.10 or greater

## Installation

```
pip install xair-api
```

## Usage

### Connection

A toml file named config.toml, placed into the current working directory of your code may be used to configure the mixers ip. A valid `config.toml` may resemble:

```toml
[connection]
ip = "<ip address>"
```

Alternatively you may pass it as a keyword argument.

### Example

```python
import xair_api


def main():
    kind_id = "XR18"
    ip = "<ip address>"

    with xair_api.connect(kind_id, ip=ip) as mixer:
        mixer.strip[8].config.name = "sm7b"
        mixer.strip[8].mix.on = True
        print(
            f"strip 09 ({mixer.strip[8].config.name}) on has been set to {mixer.strip[8].mix.on}"
        )


if __name__ == "__main__":
    main()
```

#### `xair_api.connect(kind_id, ip=ip, delay=delay)`

Currently the following devices are supported:

- `MR18`
- `XR18`
- `XR16`
- `XR12`

The `X32` is partially supported. However, this document covers specifically the `XAir` series.

The following keyword arguments may be passed:

- `ip`: ip address of the mixer
- `port`: mixer port, defaults to 10023 for x32 and 10024 for xair
- `delay`: a delay between each command (applies to the getters). Defaults to 20ms.
  - a note about delay, stability may rely on network connection. For wired connections the delay can be safely reduced.

## API

### XAirRemote class (higher level)

`mixer.lr`

A class representing Main LR channel

`mixer.strip`

A Strip tuple containing a class for each input strip channel

`mixer.bus`

A Bus tuple containing a class for each output bus channel

`mixer.dca`

A DCA tuple containing a class for each DCA group

`mixer.fx`

An FX tuple containing a class for each FX channel

`mixer.fxsend`

An FXSend tuple containing a class for each FX Send channel

`mixer.fxreturn`

An FXReturn tuple containing a class for each FX Return channel

`mixer.auxreturn`

A class representing auxreturn channel

`mixer.config`

A class representing the main config settings

### `LR`

Contains the subclasses:
(`Config`, `Dyn`, `Insert`, `EQ`, `Mix`)

### `Strip`

Contains the subclasses:
(`Config`, `Preamp`, `Gate`, `Dyn`, `Insert`, `GEQ`, `EQ`, `Mix`, `Group`, `Automix`, `Send`)

### `Bus`

Contains the subclasses:
(`Config`, `Dyn`, `Insert`, `EQ`, `Mix`, `Group`)

### `FXSend`

Contains the subclasses:
(`Config`, `Mix`, `Group`)

### `FXRtn`

Contains the subclasses:
(`Config`, `Preamp`, `EQ`, `Mix`, `Group`, `Send`)

### `AuxRtn`

Contains the subclasses:
(`Config`, `Preamp`, `EQ`, `Mix`, `Group`, `Send`)

### `Subclasses`

For each subclass the corresponding properties are available.

`Config`

- `name`: string
- `color`: int, from 0, 16
- `inputsource`: int
- `usbreturn`: int

`Preamp`

- `on`: bool
- `usbtrim`: float, from -18.0 to 18.0
- `usbinput`: bool
- `invert`: bool
- `highpasson`: bool
- `highpassfilter`: int, from 20 to 400

`Gate`

- `on`: bool
- `mode`: str, one of ('gate', 'exp2', 'exp3', 'exp4', 'duck')
- `threshold`: float, from -80.0 to 0.0
- `range`: int, from 3 to 60
- `attack`: int, from 0 to 120
- `hold`: float, from 0.02 to 2000
- `release`: int, from 5 to 4000
- `keysource`, from 0 to 22
- `filteron`: bool
- `filtertype`: int, from 0 to 8
- `filterfreq`: float, from 20 to 20000

`Dyn`

- `on`: bool
- `mode`: str, one of ('comp', 'exp')
- `det`: str, one of ('peak', 'rms')
- `env`: str, one of ('lin', 'log')
- `threshold`: float, from -60.0 to 0.0
- `ratio`: int, from 0 to 11
- `knee`: int, from 0 to 5
- `mgain`: float, from 0.0 to 24.0
- `attack`: int, from 0 to 120
- `hold`: float, from 0.02 to 2000
- `release`: int, from 5 to 4000
- `mix`: int, from 0 to 100
- `keysource`: int, from 0 to 22
- `auto`: bool
- `filteron`: bool
- `filtertype`: int, from 0 to 8
- `filterfreq`: float, from 20 to 20000

`Insert`

- `on`: bool
- `sel`: int

`GEQ`
The following method names preceded by `slider_`

- `20`, `25`, `31_5`, `40`, `50`, `63`, `80`, `100`, `125`, `160`,
- `200`, `250`, `315`, `400`, `500`, `630`, `800`, `1k`, `1k25`, `1k6`, `2k`,
- `2k5`, `3k15`, `4k`, `5k`, `6k3`, `8k`, `10k`, `12k5`, `16k`, `20k`: float, from -15.0 to 15.0

for example: `slider_20`, `slider_6k3` etc..

`EQ`

- `on`: bool
- `mode`: str, one of ('peq', 'geq', 'teq')

For the subclasses: `low`, `low2`, `lomid`, `himid`, `high2`, `high` the following properties are available:

- `type`: int, from 0 to 5
- `frequency`: float, from 20.0 to 20000.0
- `gain`: float, -15.0 to 15.0
- `quality`: float, from 0.3 to 10.0

for example: `eq.low2.type`

`Mix`

- `on`: bool
- `fader`: float, -inf, to 10.0
- `lr`: bool

`Group`

- `dca`: int, from 0 to 15
- `mute`: int, from 0 to 15

`Automix`

- `group`: int, from 0 to 2
- `weight`: float, from -12.0 to 12.0

### `DCA`

- `on`: bool
- `name`: str
- `color`: int, from 0 to 15

### `Config`

The following method names preceded by `chlink`

- `1_2`, `3_4`, `5_6`, `7_8`, `9_10`, `11_12`, `13_14`, `15_16`

The following method names preceded by `buslink`

- `1_2`, `3_4`, `5_6`

for example: `chlink1_2`, `buslink5_6` etc..

- `link_eq`: bool
- `link_dyn`: bool
- `link_fader_mute`: bool
- `amixenable`: bool
- `amixlock`: bool

For the subclass `monitor` the following properties are available

- `level`: float, -inf to 10.0
- `source`: int, from 0 to 14
- `sourcetrim`: float, from -18.0 to 18.0
- `chmode`: bool
- `busmode`: bool
- `dim`: bool
- `dimgain`: float, from -40.0 to 0.0
- `mono`: bool
- `mute`: bool
- `dimfpl`: bool

for example: `config.monitor.chmode`

#### `mute_group`

tuple containing a class for each mute group

- `on`: bool, from 0 to 3

for example: `config.mute_group[0].on = True`

### `Send`

- `level`: float, -inf to 10.0

for example: `mixer.strip[10].send[3].level = -16.5`

### XAirRemote class (lower level)

Send an OSC command directly to the mixer

- `send(osc command, value)`

for example:

```python
mixer.send("/ch/01/mix/on", 1)
mixer.send("/bus/2/config/name", "somename")
```

Query the value of a command:

- `query(osc command)`

for example:

```python
print(mixer.query("/ch/01/mix/on"))
```

### `Tests`

Unplug any expensive equipment before running tests.
Save your current settings to a snapshot first.

First make sure you installed the [development dependencies](https://github.com/onyx-and-iris/xair-api-python#installation)

To run all tests:

`pytest -v`.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

## Documentation

[XAir OSC Commands](https://behringer.world/wiki/doku.php?id=x-air_osc)

[X32 OSC Commands](https://wiki.munichmakerlab.de/images/1/17/UNOFFICIAL_X32_OSC_REMOTE_PROTOCOL_%281%29.pdf)

## Special Thanks

[Peter Dikant](https://github.com/peterdikant) for writing the base class

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/onyx-and-iris/xair-api-python",
    "name": "xair-api",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.10,<4.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "onyx-and-iris",
    "author_email": "code@onyxandiris.online",
    "download_url": "https://files.pythonhosted.org/packages/7c/ff/28f567a4d37b9c06a69bf28676ebed4c06e53265ad287806743fd54aec21/xair_api-2.3.1.tar.gz",
    "platform": null,
    "description": "[![PyPI version](https://badge.fury.io/py/xair-api.svg)](https://badge.fury.io/py/xair-api)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/xair-api-python/blob/dev/LICENSE)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)\n![Tests Status](./tests/xair/MR18.svg?dummy=8484744)\n\n# Xair API\n\nThis package offers a python interface for the [Behringer XAir](https://www.behringer.com/series.html?category=R-BEHRINGER-XAIRSERIES), [Midas MR](https://www.midasconsoles.com/catalog.html?catalog=Category&category=C-MIDAS-MIXERS-DIGITALSTAGEBOXMIXERS) series of digital rack mixers. I only have access to an MR18 for testing so if there is an error in the kind maps feel free to raise an issue or PR.\n\nFor an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)\n\n## Prerequisites\n\n- Python 3.10 or greater\n\n## Installation\n\n```\npip install xair-api\n```\n\n## Usage\n\n### Connection\n\nA toml file named config.toml, placed into the current working directory of your code may be used to configure the mixers ip. A valid `config.toml` may resemble:\n\n```toml\n[connection]\nip = \"<ip address>\"\n```\n\nAlternatively you may pass it as a keyword argument.\n\n### Example\n\n```python\nimport xair_api\n\n\ndef main():\n    kind_id = \"XR18\"\n    ip = \"<ip address>\"\n\n    with xair_api.connect(kind_id, ip=ip) as mixer:\n        mixer.strip[8].config.name = \"sm7b\"\n        mixer.strip[8].mix.on = True\n        print(\n            f\"strip 09 ({mixer.strip[8].config.name}) on has been set to {mixer.strip[8].mix.on}\"\n        )\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\n#### `xair_api.connect(kind_id, ip=ip, delay=delay)`\n\nCurrently the following devices are supported:\n\n- `MR18`\n- `XR18`\n- `XR16`\n- `XR12`\n\nThe `X32` is partially supported. However, this document covers specifically the `XAir` series.\n\nThe following keyword arguments may be passed:\n\n- `ip`: ip address of the mixer\n- `port`: mixer port, defaults to 10023 for x32 and 10024 for xair\n- `delay`: a delay between each command (applies to the getters). Defaults to 20ms.\n  - a note about delay, stability may rely on network connection. For wired connections the delay can be safely reduced.\n\n## API\n\n### XAirRemote class (higher level)\n\n`mixer.lr`\n\nA class representing Main LR channel\n\n`mixer.strip`\n\nA Strip tuple containing a class for each input strip channel\n\n`mixer.bus`\n\nA Bus tuple containing a class for each output bus channel\n\n`mixer.dca`\n\nA DCA tuple containing a class for each DCA group\n\n`mixer.fx`\n\nAn FX tuple containing a class for each FX channel\n\n`mixer.fxsend`\n\nAn FXSend tuple containing a class for each FX Send channel\n\n`mixer.fxreturn`\n\nAn FXReturn tuple containing a class for each FX Return channel\n\n`mixer.auxreturn`\n\nA class representing auxreturn channel\n\n`mixer.config`\n\nA class representing the main config settings\n\n### `LR`\n\nContains the subclasses:\n(`Config`, `Dyn`, `Insert`, `EQ`, `Mix`)\n\n### `Strip`\n\nContains the subclasses:\n(`Config`, `Preamp`, `Gate`, `Dyn`, `Insert`, `GEQ`, `EQ`, `Mix`, `Group`, `Automix`, `Send`)\n\n### `Bus`\n\nContains the subclasses:\n(`Config`, `Dyn`, `Insert`, `EQ`, `Mix`, `Group`)\n\n### `FXSend`\n\nContains the subclasses:\n(`Config`, `Mix`, `Group`)\n\n### `FXRtn`\n\nContains the subclasses:\n(`Config`, `Preamp`, `EQ`, `Mix`, `Group`, `Send`)\n\n### `AuxRtn`\n\nContains the subclasses:\n(`Config`, `Preamp`, `EQ`, `Mix`, `Group`, `Send`)\n\n### `Subclasses`\n\nFor each subclass the corresponding properties are available.\n\n`Config`\n\n- `name`: string\n- `color`: int, from 0, 16\n- `inputsource`: int\n- `usbreturn`: int\n\n`Preamp`\n\n- `on`: bool\n- `usbtrim`: float, from -18.0 to 18.0\n- `usbinput`: bool\n- `invert`: bool\n- `highpasson`: bool\n- `highpassfilter`: int, from 20 to 400\n\n`Gate`\n\n- `on`: bool\n- `mode`: str, one of ('gate', 'exp2', 'exp3', 'exp4', 'duck')\n- `threshold`: float, from -80.0 to 0.0\n- `range`: int, from 3 to 60\n- `attack`: int, from 0 to 120\n- `hold`: float, from 0.02 to 2000\n- `release`: int, from 5 to 4000\n- `keysource`, from 0 to 22\n- `filteron`: bool\n- `filtertype`: int, from 0 to 8\n- `filterfreq`: float, from 20 to 20000\n\n`Dyn`\n\n- `on`: bool\n- `mode`: str, one of ('comp', 'exp')\n- `det`: str, one of ('peak', 'rms')\n- `env`: str, one of ('lin', 'log')\n- `threshold`: float, from -60.0 to 0.0\n- `ratio`: int, from 0 to 11\n- `knee`: int, from 0 to 5\n- `mgain`: float, from 0.0 to 24.0\n- `attack`: int, from 0 to 120\n- `hold`: float, from 0.02 to 2000\n- `release`: int, from 5 to 4000\n- `mix`: int, from 0 to 100\n- `keysource`: int, from 0 to 22\n- `auto`: bool\n- `filteron`: bool\n- `filtertype`: int, from 0 to 8\n- `filterfreq`: float, from 20 to 20000\n\n`Insert`\n\n- `on`: bool\n- `sel`: int\n\n`GEQ`\nThe following method names preceded by `slider_`\n\n- `20`, `25`, `31_5`, `40`, `50`, `63`, `80`, `100`, `125`, `160`,\n- `200`, `250`, `315`, `400`, `500`, `630`, `800`, `1k`, `1k25`, `1k6`, `2k`,\n- `2k5`, `3k15`, `4k`, `5k`, `6k3`, `8k`, `10k`, `12k5`, `16k`, `20k`: float, from -15.0 to 15.0\n\nfor example: `slider_20`, `slider_6k3` etc..\n\n`EQ`\n\n- `on`: bool\n- `mode`: str, one of ('peq', 'geq', 'teq')\n\nFor the subclasses: `low`, `low2`, `lomid`, `himid`, `high2`, `high` the following properties are available:\n\n- `type`: int, from 0 to 5\n- `frequency`: float, from 20.0 to 20000.0\n- `gain`: float, -15.0 to 15.0\n- `quality`: float, from 0.3 to 10.0\n\nfor example: `eq.low2.type`\n\n`Mix`\n\n- `on`: bool\n- `fader`: float, -inf, to 10.0\n- `lr`: bool\n\n`Group`\n\n- `dca`: int, from 0 to 15\n- `mute`: int, from 0 to 15\n\n`Automix`\n\n- `group`: int, from 0 to 2\n- `weight`: float, from -12.0 to 12.0\n\n### `DCA`\n\n- `on`: bool\n- `name`: str\n- `color`: int, from 0 to 15\n\n### `Config`\n\nThe following method names preceded by `chlink`\n\n- `1_2`, `3_4`, `5_6`, `7_8`, `9_10`, `11_12`, `13_14`, `15_16`\n\nThe following method names preceded by `buslink`\n\n- `1_2`, `3_4`, `5_6`\n\nfor example: `chlink1_2`, `buslink5_6` etc..\n\n- `link_eq`: bool\n- `link_dyn`: bool\n- `link_fader_mute`: bool\n- `amixenable`: bool\n- `amixlock`: bool\n\nFor the subclass `monitor` the following properties are available\n\n- `level`: float, -inf to 10.0\n- `source`: int, from 0 to 14\n- `sourcetrim`: float, from -18.0 to 18.0\n- `chmode`: bool\n- `busmode`: bool\n- `dim`: bool\n- `dimgain`: float, from -40.0 to 0.0\n- `mono`: bool\n- `mute`: bool\n- `dimfpl`: bool\n\nfor example: `config.monitor.chmode`\n\n#### `mute_group`\n\ntuple containing a class for each mute group\n\n- `on`: bool, from 0 to 3\n\nfor example: `config.mute_group[0].on = True`\n\n### `Send`\n\n- `level`: float, -inf to 10.0\n\nfor example: `mixer.strip[10].send[3].level = -16.5`\n\n### XAirRemote class (lower level)\n\nSend an OSC command directly to the mixer\n\n- `send(osc command, value)`\n\nfor example:\n\n```python\nmixer.send(\"/ch/01/mix/on\", 1)\nmixer.send(\"/bus/2/config/name\", \"somename\")\n```\n\nQuery the value of a command:\n\n- `query(osc command)`\n\nfor example:\n\n```python\nprint(mixer.query(\"/ch/01/mix/on\"))\n```\n\n### `Tests`\n\nUnplug any expensive equipment before running tests.\nSave your current settings to a snapshot first.\n\nFirst make sure you installed the [development dependencies](https://github.com/onyx-and-iris/xair-api-python#installation)\n\nTo run all tests:\n\n`pytest -v`.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n\n## Documentation\n\n[XAir OSC Commands](https://behringer.world/wiki/doku.php?id=x-air_osc)\n\n[X32 OSC Commands](https://wiki.munichmakerlab.de/images/1/17/UNOFFICIAL_X32_OSC_REMOTE_PROTOCOL_%281%29.pdf)\n\n## Special Thanks\n\n[Peter Dikant](https://github.com/peterdikant) for writing the base class\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Remote control Behringer X-Air | Midas MR mixers through OSC",
    "version": "2.3.1",
    "project_urls": {
        "Homepage": "https://github.com/onyx-and-iris/xair-api-python",
        "Repository": "https://github.com/onyx-and-iris/xair-api-python"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6d0088263dafe2717ec08ad68269ff571ebdbe53fa8cc75cfd7d6bbd9890c13a",
                "md5": "801538b44f5650ef3b57c338aace1e82",
                "sha256": "aa408714137462834b7d59289c5eb91996bb083a6b0035f4325bdf606a9982ec"
            },
            "downloads": -1,
            "filename": "xair_api-2.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "801538b44f5650ef3b57c338aace1e82",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10,<4.0",
            "size": 18656,
            "upload_time": "2024-02-15T18:36:14",
            "upload_time_iso_8601": "2024-02-15T18:36:14.753126Z",
            "url": "https://files.pythonhosted.org/packages/6d/00/88263dafe2717ec08ad68269ff571ebdbe53fa8cc75cfd7d6bbd9890c13a/xair_api-2.3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7cff28f567a4d37b9c06a69bf28676ebed4c06e53265ad287806743fd54aec21",
                "md5": "bd34fa0a9cbdd04a8d7d99863ef5469a",
                "sha256": "957a8275f2f7b38c72bbab073d561af9a280773d77d9d02316e17e07842efda8"
            },
            "downloads": -1,
            "filename": "xair_api-2.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "bd34fa0a9cbdd04a8d7d99863ef5469a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10,<4.0",
            "size": 15523,
            "upload_time": "2024-02-15T18:36:17",
            "upload_time_iso_8601": "2024-02-15T18:36:17.518767Z",
            "url": "https://files.pythonhosted.org/packages/7c/ff/28f567a4d37b9c06a69bf28676ebed4c06e53265ad287806743fd54aec21/xair_api-2.3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-15 18:36:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "onyx-and-iris",
    "github_project": "xair-api-python",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "xair-api"
}
        
Elapsed time: 0.19356s