Skip to content

Commit d2ce73c

Browse files
MaboroshyMaboroshy
authored
Merge pull request #1 from Maboroshy/v0.3
V0.3
2 parents 3eacb2e + c26f895 commit d2ce73c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+848
-459
lines changed

‎.github/workflows/ruff.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,7 @@ jobs:
99
- uses: actions/checkout@v4
1010
- uses: chartboost/ruff-action@v1
1111
with:
12-
args: 'format --check'
12+
args: 'check'
13+
- uses: chartboost/ruff-action@v1
14+
with:
15+
args: 'format'

‎CHANGELOG.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Changelog
2+
3+
## v0.3 - 07.05.2024
4+
5+
### Added
6+
7+
- Linux and macOS support.
8+
- On Linux and macOS declaration of unavailable MIDI port will create a virtual
9+
port that show up in ports widget with `[v]` prefix.
10+
11+
## Fixed
12+
13+
- MIDI port send issues
14+
- Sending with closed port behaviour
15+
- Port re-enabling behaviour
16+
- Running starter from IPython now raises exception.
17+
18+
## v0.2 - 30.04.2024
19+
20+
Initial release

‎README.md

Lines changed: 69 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,27 @@
11
# MIDI Scripter
22

3-
MIDI Scripter is a framework for scripting MIDI, keyboard and Open Sound Control (OSC) input and output with a few lines of Python code.
3+
MIDI Scripter is a framework for scripting MIDI, keyboard and Open Sound
4+
Control (OSC) input and output with only a few lines of Python code.
45

5-
MIDI Scripter is intended for digital audio workstation (DAW) controls scripting but can also be used for general input conversion and automation. It fits where controller mappings are not enough but rewriting DAW controller integration is too much.
6+
MIDI Scripter listens to selected input ports and feed incoming messages to
7+
subscribed callables (functions, methods, etc.). These callables or any
8+
other Python code can send modified or brand-new messages with
9+
output ports. MIDI Scripter can act as a proxy to filter and transform and
10+
convert the input.
11+
12+
MIDI Scripter included customizable GUI that provides messages logging,
13+
"ready to paste" port and message declarations and one line of code widgets for
14+
monitoring / controlling scripts.
615

716
An octave transposer with GUI controls in 10 lines of code:
817

918
``` python
10-
from midiscripter import * # safe * import with no bloat
19+
from midiscripter import *
1120

12-
midi_keyboard = MidiIn('Port name') # GUI will provide you with port names
13-
proxy_output = MidiOut('loopMIDI Port') # using loopMIDI virtual port for output
21+
midi_keyboard = MidiIn('MIDI Keyboard') # GUI will provide you with port names
22+
proxy_output = MidiOut('To DAW') # using virtual port for output
1423

15-
# GUI control in a single line, many widget available, custom widgets supported
24+
# GUI control in a single line
1625
octave_selector = GuiButtonSelectorH(('-2', '-1', '0', '+1', '+2'), select='0')
1726

1827
@midi_keyboard.subscribe # decorated function will receive port's messages
@@ -25,42 +34,70 @@ if __name__ == '__main__': # combine multiple scripts by importing them
2534
start_gui() # opens helpful customizable GUI
2635
```
2736

28-
![Screenshot](https://github.com/Maboroshy/midi-scripter/blob/master/examples/octave_transposer/screenshot.png?raw=true)
37+
![Screenshot after some widget arrangement](https://github.com/Maboroshy/midi-scripter/blob/master/examples/octave_transposer/screenshot.png?raw=true)
2938

3039
[You can find more examples here.](https://github.com/Maboroshy/midi-scripter/tree/master/examples)
3140

3241
[Scripting guide and API documentation available.](https://maboroshy.github.io/midi-scripter)
3342

34-
Currently MIDI Scripter is at "beta" development stage. It's fully functional but needs some more testing. It targets only Windows for now. Linux and macOS support will follow.
43+
Currently MIDI Scripter is at "beta" development stage. It's fully
44+
functional but needs more user feedback. It works on Windows and Linx and
45+
should work on macOS.
46+
47+
## What it can do
48+
49+
For writing Python code:
50+
51+
- Prepare MIDI, OSC and keyboard inputs and outputs with a single line,
52+
without boilerplate code.
53+
- Feed input messages to functions or any callables by "decorating" them.
54+
- Work with common message objects instead of raw data different for each port
55+
type.
56+
- Send MIDI, OSC and keyboard output messages.
57+
- Create GUI widgets with one line and arrange them with mouse on your script's
58+
dashboard.
59+
60+
For live performance setups:
3561

36-
## Features
37-
Easy tasks for MIDI Scripter:
38-
1. Filter, modify and route MIDI, OSC and keyboard messages in any way.
39-
2. Map MIDI, OSC and keyboard to each other.
40-
3. Map any Python code to input message.
41-
4. Make extra "shift" keys to multiply MIDI controls.
42-
5. Organize mappings into sets / scenes with GUI controls.
43-
6. Make an extra overlay mappings on top of MIDI controller's default DAW integration by using proxy.
62+
- Make extra layers to multiply MIDI controls.
63+
- Organize mappings into sets / scenes with GUI dashboard.
64+
- Make an extra overlay mappings on top of MIDI controller's DAW integration by
65+
using proxies.
66+
- Create and map complex macros.
4467

45-
Complex tasks for MIDI Scripter:
46-
1. Create and map complex macros involving multiple hardware or virtual MIDI controllers.
47-
2. Make custom sequencer or MIDI input generator.
48-
3. Make music education or trainer GUI application based on MIDI input.
68+
For MIDI related apps:
69+
70+
- Make custom sequencers or MIDI output generators.
71+
- Make basic music training GUI applications based on MIDI input.
72+
73+
For software control and automation:
74+
75+
- Use MIDI controllers or keyboard shortcuts to run any Python code.
76+
- Use keyboard macros to control apps.
4977

5078
## Installation
51-
1. [Python 3.11+](https://www.python.org/downloads/) with "Add python.exe to PATH" option.
52-
2. [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html) for virtual MIDI output ports on Windows.
53-
3. `pip install midiscripter` in console.
5479

55-
## Setup
56-
Run loopMIDI and add virtual ports you want to send MIDI messages. You can enable its autostart option.
80+
1. Install [Python 3.11+](https://www.python.org/downloads/) including pip.
81+
2. Run `pip install midiscripter`.
5782

58-
Enable virtual MIDI output ports as MIDI inputs in DAW.
83+
Extra steps for Windows:
84+
85+
1. Enable `Add python .exe to PATH` option in Python installer.
86+
2. Install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
87+
and set required virtual MIDI ports inside it.
5988

6089
## Quick Start
61-
1. Paste [script template](examples/script_template.py) to Python IDE or plain text editor. IDE is greatly recommended.
62-
2. Run unchanged template script from IDE or by `python .\script_template.py` to open GUI for more info on available ports and their input.
63-
3. Turn on the ports' checkboxes to enable them and watch the log for input messages.
64-
4. Click on port names and messages to copy their declarations to the clipboard. Paste the declarations to your script.
65-
5. Write the functions you need. Subscribe them to messages with `@input_port.subscribe` decorator. Use `log('messages')` for debugging. Use `output_port.send(msg)` to send modified or created messages from a function.
66-
6. Restart the script from GUI.
90+
91+
1. Paste [script template](examples/script_template.py) to Python IDE or plain
92+
text editor. IDE is greatly recommended.
93+
2. Run unaltered template script from IDE or by `python` command to open GUI for
94+
more info on available ports and their input.
95+
3. Turn on available ports' checkboxes to enable them, and watch the log for
96+
input messages.
97+
4. Click on port names and messages to copy their declarations to the clipboard.
98+
Paste the declarations to your script.
99+
5. Write the functions you need. Subscribe them to input messages with
100+
`@input_port.subscribe` decorator. Use `log('messages')` for debugging.
101+
Use `output_port.send(msg)` to send modified or created messages from a
102+
function.
103+
6. Restart the script from GUI to check how in works.

0 commit comments

Comments
 (0)