mirror of
https://github.com/onyx-and-iris/xair-api-python.git
synced 2024-09-27 06:47:00 +01:00
353 lines
8.0 KiB
Markdown
353 lines
8.0 KiB
Markdown
[](https://badge.fury.io/py/xair-api)
|
|
[](https://github.com/onyx-and-iris/xair-api-python/blob/dev/LICENSE)
|
|
[](https://github.com/psf/black)
|
|
[](https://pycqa.github.io/isort/)
|
|
|
|
|
|
# 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=0.02, connect_timeout=2)`
|
|
|
|
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.
|
|
- `connect_timeout`: amount of time to wait for a validated connection. Defaults to 2s.
|
|
|
|
## 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"))
|
|
```
|
|
|
|
### Errors
|
|
|
|
- `errors.XAirRemoteError`: Base error class for XAIR Remote.
|
|
- `errors.XAirRemoteConnectionTimeoutError`:Exception raised when a connection attempt times out.
|
|
- The following attributes are available:
|
|
- `ip`: IP of the mixer.
|
|
- `port`: Port of the mixer.
|
|
|
|
### `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
|