midiscripter 0.2__tar.gz → 0.4__tar.gz

{midiscripter-0.2 → midiscripter-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: midiscripter
-Version: 0.2
+Version: 0.4
 Summary: Framework for scripting MIDI, keyboard and Open Sound Control input and output
 Project-URL: Documentation, https://maboroshy.github.io/midi-scripter
 Project-URL: Issues, https://github.com/Maboroshy/midi-scripter/issues
@@ -175,11 +175,8 @@ License-File: LICENSE
 Keywords: MIDI,OSC,automation,input,script
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -191,72 +188,116 @@ Requires-Dist: python-osc~=1.7
 Requires-Dist: python-rtmidi~=1.5
 Requires-Dist: pywin32; platform_system == 'Windows'
 Requires-Dist: watchdog~=4.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: doc
 Requires-Dist: griffe-inherited-docstrings; extra == 'doc'
 Requires-Dist: mkdocs-material; extra == 'doc'
 Requires-Dist: mkdocstrings; extra == 'doc'
 Description-Content-Type: text/markdown
 
-# MIDI Scripter
+# <img src="docs/icon.svg" width="24"/> MIDI Scripter
 
-MIDI Scripter is a framework for scripting MIDI, keyboard and Open Sound Control (OSC) input and output with a few lines of Python code.
+MIDI Scripter is a framework filtering, modifying, routing and any other
+scripting for MIDI, Open Sound Control (OSC), keyboard and mouse input and
+output with Python.
 
-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. 
+MIDI Scripter listens to the input ports and feeds incoming messages to
+subscribed callables (functions, methods, etc.). These callables or any
+other Python code can send modified or created messages with output ports. 
+MIDI Scripter can act as a proxy to filter, transform and convert the input.
+
+MIDI Scripter includes customizable GUI for message logging, coding
+assistance and GUI controls and indicators to use in scripts.
 
 An octave transposer with GUI controls in 10 lines of code:
 
 ``` python
-from midiscripter import *  # safe * import with no bloat
+from midiscripter import *
 
-midi_keyboard = MidiIn('Port name')  # GUI will provide you with port names
-proxy_output = MidiOut('loopMIDI Port') # using loopMIDI virtual port for output
+midi_keyboard = MidiIn('MIDI Keyboard')  # GUI will provide you with port names
+proxy_output = MidiOut('To DAW')  # using virtual proxy port for output
 
-# GUI control in a single line, many widget available, custom widgets supported
+# GUI control in a single line
 octave_selector = GuiButtonSelectorH(('-2', '-1', '0', '+1', '+2'), select='0')
 
 @midi_keyboard.subscribe  # decorated function will receive port's messages
 def transpose(msg: MidiMsg) -> None:
 	if msg.type == MidiType.NOTE_ON or msg.type == MidiType.NOTE_OFF:  # filter
 		msg.data1 += 12 * int(octave_selector.selected_item_text)  # modify
-		proxy_output.send(msg)  # route
+	proxy_output.send(msg)  # route
 
 if __name__ == '__main__':  # combine multiple scripts by importing them
 	start_gui()  # opens helpful customizable GUI
 ```
 
-![Screenshot](https://github.com/Maboroshy/midi-scripter/blob/master/examples/octave_transposer/screenshot.png?raw=true)
+![Screenshot after some widget arrangement](https://github.com/Maboroshy/midi-scripter/blob/master/examples/octave_transposer/screenshot.png?raw=true)
+
+[You can find more examples here.](https://github.com/Maboroshy/midi-scripter/tree/master/examples)
+
+[Overview and API documentation available.](https://maboroshy.github.io/midi-scripter)
+
+The average measured roundtrip latency for the script above is less than 0.25 
+milliseconds.
+
+Currently MIDI Scripter is at "beta" development stage. It's fully
+functional but needs more user feedback. It works on Windows and Linux and
+should work on macOS.
+
+## What it can do
 
-[Scripting guide and API documentation available](https://maboroshy.github.io/midi-scripter)
+The basics:
 
-Easy tasks for MIDI Scripter:  
-1. Filter, modify and route MIDI, OSC and keyboard messages in any way.  
-2. Map MIDI, OSC and keyboard to each other.  
-3. Map any Python code to input message.  
-4. Make extra "shift" keys to multiply MIDI controls.  
-5. Organize mappings into sets / scenes with GUI controls.  
-6. Make an extra overlay mappings on top of MIDI controller's default DAW integration by using proxy.  
+- Receive MIDI, OSC, keyboard and mouse input messages.
+- Filter, modify and do anything Python can with the messages.
+- Send out modified or generated MIDI, OSC, keyboard and mouse messages.
 
-Complex tasks for MIDI Scripter:
-1. Create and map complex macros involving multiple hardware or virtual MIDI controllers.
-2. Make custom sequencer or MIDI input generator.
-3. Make music education ot trainer GUI application based on MIDI input.
+For performance MIDI setups:
 
-Currently MIDI Scripter is at "beta" development stage. It's fully functional but needs some more testing. It targets only Windows for now but Linux and macOS support will follow.
+- Make extra banks and layers to multiply MIDI controls.
+- Organize mappings into sets / scenes with GUI dashboard.
+- Make an extra overlay mappings on top of MIDI controller's DAW integration by
+  using proxies.
+
+For software control and automation:
+
+- Map or convert the messages to each other with any conditions and logic.
+- Use MIDI controllers or keyboard shortcuts to run any Python code.
+- Use keyboard and mouse macros.
+
+For writing MIDI related Python code:
+
+- Prepare MIDI, OSC keyboard and mouse inputs and outputs with a single line,
+  without boilerplate code.
+- Feed input messages to functions or any callables by decorators.
+- Work with message objects instead of raw data different for each input type.
+- Create GUI widgets with a single line and arrange them with mouse.
+- Write basic MIDI related GUI applications with very little Python code.
 
 ## Installation
-1. [Python 3.11+](https://www.python.org/downloads/) with "Add python.exe to PATH" option.
-2. [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html) for virtual MIDI output ports on Windows.
-3. `pip install midiscripter` in console.
 
-## Setup
-Run loopMIDI and add virtual ports you want to send MIDI messages. You can enable its autostart option.
+1. Install [Python 3.11+](https://www.python.org/downloads/) including pip.
+2. Run `pip install midiscripter`.
+
+Extra steps for Windows:
 
-Enable virtual MIDI output ports as MIDI inputs in DAW. 
+1. Enable `Add python .exe to PATH` option in Python installer.
+2. Install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
+   and set required virtual MIDI ports inside it.
 
 ## Quick Start
-1. Paste [script template](examples/script_template.py) to Python IDE or plain text editor. IDE is greatly recommended.
-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.
-3. Turn on the ports' checkboxes to enable them and watch the log for input messages.
-4. Click on port names and messages to copy their declarations to the clipboard. Paste the declarations to your script.
-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.
-6. Restart the script from GUI.
+
+1. Paste [script template](examples/script_template.py) to Python IDE or plain
+   text editor. IDE is recommended.
+2. Run template script as-is from IDE or by `python your_script.py` command to
+   open GUI for more info on available ports and incoming input.
+3. Turn on available ports' checkboxes to enable them, watch the log for
+   input messages.
+4. Click on port names and messages in log to copy their declarations to the
+   clipboard. Paste the declarations to your script.
+5. Modify the template function to make it do what you want.
+   Use `log('messages')` for debugging.
+6. Restart the script from GUI to check how in works.
+7. Write more complex scripts. Use more inputs, outputs and functions
+   (callables). Subscribe callables to input messages with
+   `@input_port.subscribe` decorator.

midiscripter-0.4/README.md

@@ -0,0 +1,105 @@
+# <img src="docs/icon.svg" width="24"/> MIDI Scripter
+
+MIDI Scripter is a framework filtering, modifying, routing and any other
+scripting for MIDI, Open Sound Control (OSC), keyboard and mouse input and
+output with Python.
+
+MIDI Scripter listens to the input ports and feeds incoming messages to
+subscribed callables (functions, methods, etc.). These callables or any
+other Python code can send modified or created messages with output ports. 
+MIDI Scripter can act as a proxy to filter, transform and convert the input.
+
+MIDI Scripter includes customizable GUI for message logging, coding
+assistance and GUI controls and indicators to use in scripts.
+
+An octave transposer with GUI controls in 10 lines of code:
+
+``` python
+from midiscripter import *
+
+midi_keyboard = MidiIn('MIDI Keyboard')  # GUI will provide you with port names
+proxy_output = MidiOut('To DAW')  # using virtual proxy port for output
+
+# GUI control in a single line
+octave_selector = GuiButtonSelectorH(('-2', '-1', '0', '+1', '+2'), select='0')
+
+@midi_keyboard.subscribe  # decorated function will receive port's messages
+def transpose(msg: MidiMsg) -> None:
+	if msg.type == MidiType.NOTE_ON or msg.type == MidiType.NOTE_OFF:  # filter
+		msg.data1 += 12 * int(octave_selector.selected_item_text)  # modify
+	proxy_output.send(msg)  # route
+
+if __name__ == '__main__':  # combine multiple scripts by importing them
+	start_gui()  # opens helpful customizable GUI
+```
+
+![Screenshot after some widget arrangement](https://github.com/Maboroshy/midi-scripter/blob/master/examples/octave_transposer/screenshot.png?raw=true)
+
+[You can find more examples here.](https://github.com/Maboroshy/midi-scripter/tree/master/examples)
+
+[Overview and API documentation available.](https://maboroshy.github.io/midi-scripter)
+
+The average measured roundtrip latency for the script above is less than 0.25 
+milliseconds.
+
+Currently MIDI Scripter is at "beta" development stage. It's fully
+functional but needs more user feedback. It works on Windows and Linux and
+should work on macOS.
+
+## What it can do
+
+The basics:
+
+- Receive MIDI, OSC, keyboard and mouse input messages.
+- Filter, modify and do anything Python can with the messages.
+- Send out modified or generated MIDI, OSC, keyboard and mouse messages.
+
+For performance MIDI setups:
+
+- Make extra banks and layers to multiply MIDI controls.
+- Organize mappings into sets / scenes with GUI dashboard.
+- Make an extra overlay mappings on top of MIDI controller's DAW integration by
+  using proxies.
+
+For software control and automation:
+
+- Map or convert the messages to each other with any conditions and logic.
+- Use MIDI controllers or keyboard shortcuts to run any Python code.
+- Use keyboard and mouse macros.
+
+For writing MIDI related Python code:
+
+- Prepare MIDI, OSC keyboard and mouse inputs and outputs with a single line,
+  without boilerplate code.
+- Feed input messages to functions or any callables by decorators.
+- Work with message objects instead of raw data different for each input type.
+- Create GUI widgets with a single line and arrange them with mouse.
+- Write basic MIDI related GUI applications with very little Python code.
+
+## Installation
+
+1. Install [Python 3.11+](https://www.python.org/downloads/) including pip.
+2. Run `pip install midiscripter`.
+
+Extra steps for Windows:
+
+1. Enable `Add python .exe to PATH` option in Python installer.
+2. Install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
+   and set required virtual MIDI ports inside it.
+
+## Quick Start
+
+1. Paste [script template](examples/script_template.py) to Python IDE or plain
+   text editor. IDE is recommended.
+2. Run template script as-is from IDE or by `python your_script.py` command to
+   open GUI for more info on available ports and incoming input.
+3. Turn on available ports' checkboxes to enable them, watch the log for
+   input messages.
+4. Click on port names and messages in log to copy their declarations to the
+   clipboard. Paste the declarations to your script.
+5. Modify the template function to make it do what you want.
+   Use `log('messages')` for debugging.
+6. Restart the script from GUI to check how in works.
+7. Write more complex scripts. Use more inputs, outputs and functions
+   (callables). Subscribe callables to input messages with
+   `@input_port.subscribe` decorator.

{midiscripter-0.2 → midiscripter-0.4}/midiscripter/__init__.py

@@ -1,8 +1,10 @@
-from .base.shared import restart_script, run_after_ports_opened
+from .shared import restart_script, run_after_ports_opened
+from .base import *
 from .cli import *
 from .file_event import *
 from .gui import *
 from .keyboard import *
+from .mouse import *
 from .logger import *
 from .metronome import *
 from .midi import *

midiscripter-0.4/midiscripter/base/__init__.py

@@ -0,0 +1 @@
+from .msg_base import Msg, Not

midiscripter-0.4/midiscripter/base/msg_base.py

@@ -0,0 +1,114 @@
+import enum
+from typing import Any
+from collections.abc import Container
+
+import midiscripter.shared
+from midiscripter.base.port_base import Input
+
+
+class Not:
+    def __init__(self, value: Container | Any):
+        self.value = value
+
+
+class AttrEnum(enum.StrEnum):
+    def __repr__(self):
+        return f'{self.__class__.__name__}({self.value.__repr__()})'
+
+
+class Msg:
+    """The data object generated by input port that is sent as an argument to its subscribed calls
+    and can be sent with an output port"""
+
+    type: str
+    """Message type description for filtering and representation"""
+
+    ctime: float
+    """Message creation time in ["Unix time"](https://wikipedia.org/wiki/Unix_time) format"""
+
+    source: Input
+    """Input port instance that generated the message"""
+
+    __match_args__: tuple[str] = ('type',)
+
+    def __init__(self, type: str, source: Input | None = None):
+        """
+        Args:
+            source: Input port instance that generated the message
+        """
+        self.type = type
+        self.source = source
+        self.ctime = midiscripter.shared.precise_epoch_time()
+
+        self.ctime: float  # workaround for mkdocstrings issue #607
+        """Message creation time in ["Unix time"](https://wikipedia.org/wiki/Unix_time) format"""
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}({", ".join(repr(value) for value in self.__as_tuple())})'
+
+    def __str__(self):
+        return ' | '.join(str(value) for value in self.__as_tuple() if value is not None)
+
+    def __eq__(self, other_msg: 'Msg'):
+        return type(self) is type(other_msg) and self.__as_tuple() == other_msg.__as_tuple()
+
+    def matches(self, *conditions_args, **conditions_kwargs) -> bool:
+        """Checks if message's attributes match all provided attribute conditions:
+
+        1. If condition is `None` or omitted, it matches anything.
+
+        2. If condition equals attribute, it matches the attribute.
+
+        3. If condition is a container and contains the attribute, it matches the attribute.
+
+        Use `Not(condition)` to invert condition matching.
+
+        Returns:
+            `True` if all attributes match, `False` if any does not match
+        """
+        attr_conditions = dict(zip(self.__match_args__, conditions_args, strict=False))
+        attr_conditions.update(conditions_kwargs)
+
+        for parameter_name, condition in attr_conditions.items():
+            if condition is None:
+                continue
+
+            try:
+                attr = getattr(self, parameter_name)
+            except AttributeError:
+                if isinstance(condition, Not):
+                    continue
+                else:
+                    return False
+
+            if attr == condition:
+                if isinstance(condition, Not):
+                    return False
+                else:
+                    continue
+
+            try:
+                if attr in condition and not isinstance(condition, str):
+                    if isinstance(condition, Not):
+                        return False
+                    else:
+                        continue
+            except TypeError:  # condition is not a container
+                pass
+
+            return False
+        return True
+
+    @property
+    def _age_ms(self) -> float:
+        """Time passed since message creation in milliseconds"""
+        # Using faster rounding
+        return int((midiscripter.shared.precise_epoch_time() - self.ctime) * 1000000) / 1000
+
+    def __as_tuple(self) -> tuple:
+        """Converts message to a tuple based on message's __match_args__ class attribute
+
+        Returns:
+            Tuple with values of attributes specified in __match_args__ class attribute
+        """
+        return tuple(getattr(self, attr_name) for attr_name in self.__match_args__)