# ewi-usb-config-cli
Configure an Akai EWI USB MIDI wind controller via MIDI from the command line
on Linux, macOS or Windows.
### Installation
Via [pip](https://github.com/pypa/pip):
```con
pip install ewi-usb-config-cli
```
Via [pipx](https://github.com/pypa/pipx):
```con
pipx install ewi-usb-config-cli
```
## Usage
```
usage: ewi-usb-config [-h] [-d DEVICE_ID] [-a] [-f] [-r PATH] [--all-banks]
[-s PATH] [-p PORT] [-t TIMEOUT] [-v] [--version]
[setting ...]
Configure an Akai EWI USB MIDI wind controller via MIDI.
positional arguments:
setting Setting to send to EWI in the form name=value (can be
given more than once)
options:
-h, --help show this help message and exit
-d DEVICE_ID, --device-id DEVICE_ID
SysEx Device ID (default: 0x7F)
-a, --ascii Set SysEx dump output format to ASCII hexadecimal
values
-f, --force Allow overwriting existing file when writing received
SysEx dump
-r PATH, --receive PATH
Receive SysEx dump from EWI and save in file PATH (use
'-' to write to standard output)
--all-banks Request all settings banks (0-3) (the purpose of banks
1 and 3 is unclear)
-s PATH, --send PATH Send SysEx dump file PATH to EWI (use '-' to read from
standard input)
-p PORT, --port PORT Number or (part of) name of MIDI input/output port to
open (default: 'EWI-USB')
-t TIMEOUT, --timeout TIMEOUT
SysEx dump reception timeout (default: 5)
-v, --verbose Output verbose messages of program operation to stderr
--version show program's version number and exit
Settings:
breath-gain, bite-gain, bite-ac-gain, pb-gain, key-delay, unknown-1,
midi-channel, fingering, transposition, velocity, breath-cc-1, breath-cc-2,
unknown-2, bite-cc-1, bite-cc-2, pb-up-cc, pb-down-cc
```
## Examples
Connect your Akai EWI USB wind controller via USB and use your system's MIDI
tools to check that it shows up as MIDI input and output ports having names
with "EWI-USB" in them.
Then use the terminal to send commands to your EWI using the `ewi-usb-config`
program.
For example, to set the key delay to 10 (the factory default value is 7):
```con
ewi-usb-config key-delay=10
```
Configure the MIDI control change type, which is sent when biting on the rubber
mouth piece to only send *Modulation* (CC #1) and disable sending *Pitch Bend*
as well. Also set the bite gain to value 20 (the factory default value is 64):
```con
ewi-usb-config bite-cc-1=0 bite-cc-2=1 bite-gain=20
```
Configure the MIDI messages types, which are sent in response to breath input,
to *Breath Controller* (CC #2) and *Channel Aftertouch*, which is the factory
default behaviour:
```con
ewi-usb-config breath-cc-1=2 breath-cc-2=127
```
Retrieve all current settings from the device as a MIDI System Exclusive (SysEx)
dump and write it to the file `ewi-usb.syx` using the `-r|--receive` option:
```con
ewi-usb-config -r ewi-usb.syx
```
Send a SysEx dump to the device to restore all settings saved in the dump using
the `-s|--send` option:
```con
ewi-usb-config -s ewi-usb.syx
```
Retrieve a settings dump but output the SysEx data as hexadecimal numbers in
ASCII to the standard output by adding the `-a|--ascii` option and using `-` as
the output filename to indicate standard output:
```con
ewi-usb-config -ar -
```
This produces output like this:
```
F0 47 7F 6D 00 00 06 40 40 40 40 07 7F F7
F0 47 7F 6D 02 00 0B 00 00 40 78 02 7F 00 7F 00 7F 7F F7
```
Note that this format can not be loaded back into the EWI USB. It is meant
mainly as a debugging tool for developers.
## Settings Values
All settings take values from 0 to 127, unless noted otherwise here.
* For the controller settings, some values in that range have no effect.
See the table in the next section below for details.
* The `fingering` setting supports the following values:
| Value | Fingering System |
| - | ----------------------------------- |
| 0 | Standard EWI fingering |
| 1 | Saxophone |
| 2 | Flute |
| 3 | Oboe |
| 4 | EVI Valve 1 |
| 5 | EVI Valve 2 (reversed pitch plates) |
* The `midi-channel` settings takes a value from 0 (channel 1) to 15
(channel 16).
* The `transposition` setting takes a value of 52 - 76, with 64 being no
transposition and 56 = -12 semitones and 76 = +12 semitones.
* For the the `velocity` setting, a value of zero (0) means that the EWI will
use dynamic velocity values for note-on messages, according to the breath
strength, whereas values 1 - 127 will cause note-on messages to have a fixed
velocity of the set value.
### Controllers
| Value | Breath CC 1 | Breath CC 2 | Bite CC 1 | Bite CC 2 | Pitch Plate Up | Pitch Plate Down |
| ----- | ------------- | ------------- | ----------------- | ------------- | -------------- | ---------------- |
| 0 | OFF | OFF | OFF | OFF | OFF | OFF |
| 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 |
| 124 | - | - | Pitchbend UP | - | - | - |
| 125 | - | - | Pitchbend DOWN | - | - | - |
| 126 | - | - | Pitchbend up-down | - | - | - |
| 127 | Aftertouch | Aftertouch | Pitchbend down-up | Aftertouch | Pitchbend UP | Pitchbend DOWN |
*Aftertouch* is always *Channel Pressure*, aka *Mono Aftertouch*.
*Note Pressure*, aka *Poly Aftertouch*, is not supported.
## Development
Using the [hatch](https://hatch.pypa.io/) tool:
- `hatch run ewi-usb-config --version`
- `hatch run ewi-usb-config --help`
- `hatch status`
- `hatch project metadata | jq -C | less-R`
- `hatch version`
*Note:* `hatch run ewi-usb-config` can be abbreviated as `hatch run euc`.
## Deployment
```con
hatch version <new version number>
git add ewi_usb_config/version.py
git commit -m "Bump version to <new version number>"
git tag -a -m "Tagging new release <new version number>" vX.Y.Z
git push --tags master
```
... and let the GitHub Actions `release` workflow do the rest.
Raw data
{
"_id": null,
"home_page": null,
"name": "ewi-usb-config-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "akai, ewi, ewi usb, midi, sysex, wind controller",
"author": null,
"author_email": "Christopher Arndt <chris@chrisarndt.de>",
"download_url": "https://files.pythonhosted.org/packages/95/bd/d4a03bad1b61859ce0bf93f6d68792011a13b531ea9d0be3fb361aff43f2/ewi_usb_config_cli-0.1.0.tar.gz",
"platform": null,
"description": "# ewi-usb-config-cli\n\nConfigure an Akai EWI USB MIDI wind controller via MIDI from the command line\non Linux, macOS or Windows.\n\n\n### Installation\n\nVia [pip](https://github.com/pypa/pip):\n\n```con\npip install ewi-usb-config-cli\n```\n\nVia [pipx](https://github.com/pypa/pipx):\n\n```con\npipx install ewi-usb-config-cli\n```\n\n\n## Usage\n\n```\nusage: ewi-usb-config [-h] [-d DEVICE_ID] [-a] [-f] [-r PATH] [--all-banks]\n [-s PATH] [-p PORT] [-t TIMEOUT] [-v] [--version]\n [setting ...]\n\nConfigure an Akai EWI USB MIDI wind controller via MIDI.\n\npositional arguments:\n setting Setting to send to EWI in the form name=value (can be\n given more than once)\n\noptions:\n -h, --help show this help message and exit\n -d DEVICE_ID, --device-id DEVICE_ID\n SysEx Device ID (default: 0x7F)\n -a, --ascii Set SysEx dump output format to ASCII hexadecimal\n values\n -f, --force Allow overwriting existing file when writing received\n SysEx dump\n -r PATH, --receive PATH\n Receive SysEx dump from EWI and save in file PATH (use\n '-' to write to standard output)\n --all-banks Request all settings banks (0-3) (the purpose of banks\n 1 and 3 is unclear)\n -s PATH, --send PATH Send SysEx dump file PATH to EWI (use '-' to read from\n standard input)\n -p PORT, --port PORT Number or (part of) name of MIDI input/output port to\n open (default: 'EWI-USB')\n -t TIMEOUT, --timeout TIMEOUT\n SysEx dump reception timeout (default: 5)\n -v, --verbose Output verbose messages of program operation to stderr\n --version show program's version number and exit\n\nSettings:\n breath-gain, bite-gain, bite-ac-gain, pb-gain, key-delay, unknown-1,\n midi-channel, fingering, transposition, velocity, breath-cc-1, breath-cc-2,\n unknown-2, bite-cc-1, bite-cc-2, pb-up-cc, pb-down-cc\n```\n\n\n## Examples\n\nConnect your Akai EWI USB wind controller via USB and use your system's MIDI\ntools to check that it shows up as MIDI input and output ports having names\nwith \"EWI-USB\" in them.\n\nThen use the terminal to send commands to your EWI using the `ewi-usb-config`\nprogram.\n\nFor example, to set the key delay to 10 (the factory default value is 7):\n\n```con\newi-usb-config key-delay=10\n```\n\nConfigure the MIDI control change type, which is sent when biting on the rubber\nmouth piece to only send *Modulation* (CC #1) and disable sending *Pitch Bend*\nas well. Also set the bite gain to value 20 (the factory default value is 64):\n\n```con\newi-usb-config bite-cc-1=0 bite-cc-2=1 bite-gain=20\n```\n\nConfigure the MIDI messages types, which are sent in response to breath input,\nto *Breath Controller* (CC #2) and *Channel Aftertouch*, which is the factory\ndefault behaviour:\n\n```con\newi-usb-config breath-cc-1=2 breath-cc-2=127\n```\n\nRetrieve all current settings from the device as a MIDI System Exclusive (SysEx)\ndump and write it to the file `ewi-usb.syx` using the `-r|--receive` option:\n\n```con\newi-usb-config -r ewi-usb.syx\n```\n\nSend a SysEx dump to the device to restore all settings saved in the dump using\nthe `-s|--send` option:\n\n```con\newi-usb-config -s ewi-usb.syx\n```\n\nRetrieve a settings dump but output the SysEx data as hexadecimal numbers in\nASCII to the standard output by adding the `-a|--ascii` option and using `-` as\nthe output filename to indicate standard output:\n\n```con\newi-usb-config -ar -\n```\n\nThis produces output like this:\n\n```\nF0 47 7F 6D 00 00 06 40 40 40 40 07 7F F7\nF0 47 7F 6D 02 00 0B 00 00 40 78 02 7F 00 7F 00 7F 7F F7\n```\n\nNote that this format can not be loaded back into the EWI USB. It is meant\nmainly as a debugging tool for developers.\n\n\n## Settings Values\n\nAll settings take values from 0 to 127, unless noted otherwise here.\n\n* For the controller settings, some values in that range have no effect.\n See the table in the next section below for details.\n* The `fingering` setting supports the following values:\n\n | Value | Fingering System |\n | - | ----------------------------------- |\n | 0 | Standard EWI fingering |\n | 1 | Saxophone |\n | 2 | Flute |\n | 3 | Oboe |\n | 4 | EVI Valve 1 |\n | 5 | EVI Valve 2 (reversed pitch plates) |\n* The `midi-channel` settings takes a value from 0 (channel 1) to 15\n (channel 16).\n* The `transposition` setting takes a value of 52 - 76, with 64 being no\n transposition and 56 = -12 semitones and 76 = +12 semitones.\n* For the the `velocity` setting, a value of zero (0) means that the EWI will\n use dynamic velocity values for note-on messages, according to the breath\n strength, whereas values 1 - 127 will cause note-on messages to have a fixed\n velocity of the set value.\n\n\n### Controllers\n\n| Value | Breath CC 1 | Breath CC 2 | Bite CC 1 | Bite CC 2 | Pitch Plate Up | Pitch Plate Down |\n| ----- | ------------- | ------------- | ----------------- | ------------- | -------------- | ---------------- |\n| 0 | OFF | OFF | OFF | OFF | OFF | OFF |\n| 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 | MIDI CC 1-119 |\n| 124 | - | - | Pitchbend UP | - | - | - |\n| 125 | - | - | Pitchbend DOWN | - | - | - |\n| 126 | - | - | Pitchbend up-down | - | - | - |\n| 127 | Aftertouch | Aftertouch | Pitchbend down-up | Aftertouch | Pitchbend UP | Pitchbend DOWN |\n\n\n*Aftertouch* is always *Channel Pressure*, aka *Mono Aftertouch*.\n*Note Pressure*, aka *Poly Aftertouch*, is not supported.\n\n\n## Development\n\nUsing the [hatch](https://hatch.pypa.io/) tool:\n\n- `hatch run ewi-usb-config --version`\n- `hatch run ewi-usb-config --help`\n- `hatch status`\n- `hatch project metadata | jq -C | less-R`\n- `hatch version`\n\n*Note:* `hatch run ewi-usb-config` can be abbreviated as `hatch run euc`.\n\n\n## Deployment\n\n```con\nhatch version <new version number>\ngit add ewi_usb_config/version.py\ngit commit -m \"Bump version to <new version number>\"\ngit tag -a -m \"Tagging new release <new version number>\" vX.Y.Z\ngit push --tags master\n```\n\n... and let the GitHub Actions `release` workflow do the rest.\n",
"bugtrack_url": null,
"license": null,
"summary": "Configure an Akai EWI USB MIDI wind controller via MIDI from the command line",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/SpotlightKid/ewi-usb-config-cli",
"Issues": "https://github.com/SpotlightKid/ewi-usb-config-cli/issues",
"Source": "https://github.com/SpotlightKid/ewi-usb-config-cli"
},
"split_keywords": [
"akai",
" ewi",
" ewi usb",
" midi",
" sysex",
" wind controller"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c852c40d30f1696b3dc7fafcbfae185564721ba3481f1a6e7d28284d07b29817",
"md5": "a0a565eb96e7c3549cebd8407554f989",
"sha256": "706152e78b2ef63f895f8d5bcb600fc5dc7e2dc13f0e8f3d4dea153f69bb7078"
},
"downloads": -1,
"filename": "ewi_usb_config_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0a565eb96e7c3549cebd8407554f989",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11682,
"upload_time": "2024-04-06T13:47:35",
"upload_time_iso_8601": "2024-04-06T13:47:35.684301Z",
"url": "https://files.pythonhosted.org/packages/c8/52/c40d30f1696b3dc7fafcbfae185564721ba3481f1a6e7d28284d07b29817/ewi_usb_config_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95bdd4a03bad1b61859ce0bf93f6d68792011a13b531ea9d0be3fb361aff43f2",
"md5": "cc8a596578c0768e7a13edcaefa30486",
"sha256": "a1665ddf23cec714793992e6aa5c84ff38923bee46c823b6f8adec45669237d5"
},
"downloads": -1,
"filename": "ewi_usb_config_cli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cc8a596578c0768e7a13edcaefa30486",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10036,
"upload_time": "2024-04-06T13:47:37",
"upload_time_iso_8601": "2024-04-06T13:47:37.498018Z",
"url": "https://files.pythonhosted.org/packages/95/bd/d4a03bad1b61859ce0bf93f6d68792011a13b531ea9d0be3fb361aff43f2/ewi_usb_config_cli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 13:47:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpotlightKid",
"github_project": "ewi-usb-config-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ewi-usb-config-cli"
}
JSON
