Fixes in implementation of animations

Author: ffont

README.md

@@ -4,8 +4,8 @@ Utils to interface with [Ableton's Push 2](https://www.ableton.com/en/push/) fro
 
 These utils follow Ableton's [Push 2 MIDI and Display Interface Manual](https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc) for comunicating with Push 2. I recommend reading Ableton's manual before using this tool.
 
-So far I only implemented some utils to **interface with the display** and some utils for **basic interaction with pads, buttons, encoders and the touchstrip**. More detailed interaction with each of these elements (e.g. changing color palettes, support for led blinking, advanced touchstrip configuration, etc.) has not been implemented. Contributions are welcome :)
-*EDIT*: customization of color palettes is now implemented!
+So far I only implemented some utils to **interface with the display** and some utils for **interaction with pads, buttons, encoders and the touchstrip**. More detailed interaction with each of these elements (e.g. changing color palettes, support for led blinking, advanced touchstrip configuration, etc.) has not been implemented. Contributions are welcome :)
+*EDIT*: customization of color palettes and led animations is now implemented!
 
 I only testd the package in **Python 3** and **macOS**. Some things will not work on Python 2 but it should be easy to port. I don't know how it will work on Windows/Linux. ~~It is possible that MIDI port names (see [push2_python/constants.py](https://github.com/ffont/push2-python/blob/master/push2_python/constants.py#L12-L13)) need to be changed to correctly reach Push2 in Windows/Linux~~. **UPDATE**: MIDI port names should now be cross-platform, but I have not tested them on Linux/Windows.
 
@@ -156,6 +156,21 @@ All pads support RGB colors, and some buttons do as well. However, some buttons
 For a list of avilable RGB colors check the `DEFAULT_COLOR_PALETTE` dictionary in [push2_python/constants.py](https://github.com/ffont/push2-python/blob/master/push2_python/constants.py). First item of each color entry corresponds to the RGB color name while second item corresponds to the BW color name. The color palette can be customized using the `set_color_palette_entry`, `update_rgb_color_palette_entry` and `reapply_color_palette` of Push2 object. See the documentation of these methods for more details.
 
 
+### Set pad and button animations
+
+Animations (e.g. led blinking) can be configured similarly to colors. To configiure an animation you need to define the *starting color* by sending a "set color" message with an animation code corresponding to "static", and then set the *second color* by sending another "set color" message with an animation code corresponding to the desired animation. For example, to condfigure the
+play button with a pulsing animation from white to green:
+
+```python
+push.buttons.set_button_color(push2_python.constants.BUTTON_PLAY, 'white')
+push.buttons.set_button_color(push2_python.constants.BUTTON_PLAY, 'green', animation=push2_python.constants.ANIMATION_PULSING_QUARTER)
+```
+
+By default, animations are synced to a clock of 120bpm. It is possible to change that tempo by sending MIDI clock messages to the Push2 device, but `push2-python` currently does not support that. Should be easy to implement though by sending MIDI clock messages using the `push.send_midi_to_push(msg)` method.
+
+For a list of available animations, check the variables names `ANIMATION_*` dictionary in [push2_python/constants.py](https://github.com/ffont/push2-python/blob/master/push2_python/constants.py). Also, see the animations section of the [Push 2 MIDI and Display Interface Manual](https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#268-led-animation) for more information about animations.
+
+
 ### Adjust pad sensitivity
 
 `push2-python` implements methods to adjust Push2 pads sensitivity, in particualr it incorporates methods to adjust the velocity curve (which applies to

push2_python/buttons.py

@@ -1,5 +1,5 @@
 import mido
-from .constants import ANIMATIONS, ANIMATIONS_DEFAULT, MIDO_CONTROLCHANGE, ACTION_BUTTON_PRESSED, ACTION_BUTTON_RELEASED
+from .constants import ANIMATION_DEFAULT, MIDO_CONTROLCHANGE, ACTION_BUTTON_PRESSED, ACTION_BUTTON_RELEASED
 from .classes import AbstractPush2Section
 
 
@@ -33,11 +33,13 @@ def button_name_to_button_n(self, button_name):
         """
         return self.button_names_index.get(button_name, None)
 
-    def set_button_color(self, button_name, color='white', animation='static'):
+    def set_button_color(self, button_name, color='white', animation=ANIMATION_DEFAULT):
         """Sets the color of the button with given name.
         'color' must be a valid RGB or BW color name present in the color palette. See push2_python.constants.DEFAULT_COLOR_PALETTE for default color names.
         If the button only acceps BW colors, the color name will be matched against the BW palette, otherwise it will be matched against RGB palette.
-        'animation' must be an existing key of push2_python.contants.ANIMATIONS dictionary.
+        'animation' must be a valid animation name from those defined in push2_python.contants.ANIMATION_*. Note that to configure an animation, both the 'start' and 'end'
+        colors of the animation need to be defined. The 'start' color is defined by setting a color with 'push2_python.contants.ANIMATION_STATIC' (the default).
+        The second color is set setting a color with whatever ANIMATION_* type is desired.
         See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#setting-led-colors
         """
         button_n = self.button_name_to_button_n(button_name)
@@ -47,15 +49,16 @@ def set_button_color(self, button_name, color='white', animation='static'):
                 color_idx = self.push.get_rgb_color(color)
             else:
                 color_idx = self.push.get_bw_color(color)
-            animation = ANIMATIONS.get(animation, ANIMATIONS_DEFAULT)
             msg = mido.Message(MIDO_CONTROLCHANGE, control=button_n, value=color_idx, channel=animation)
             self.push.send_midi_to_push(msg)
 
-    def set_all_buttons_color(self, color='white', animation='static'):
+    def set_all_buttons_color(self, color='white', animation=ANIMATION_DEFAULT):
         """Sets the color of all buttons in Push2 to the given color.
         'color' must be a valid RGB or BW color name present in the color palette. See push2_python.constants.DEFAULT_COLOR_PALETTE for default color names.
         If the button only acceps BW colors, the color name will be matched against the BW palette, otherwise it will be matched against RGB palette.
-        'animation' must be an existing key of push2_python.contants.ANIMATIONS dictionary.
+        'animation' must be a valid animation name from those defined in push2_python.contants.ANIMATION_*. Note that to configure an animation, both the 'start' and 'end'
+        colors of the animation need to be defined. The 'start' color is defined by setting a color with 'push2_python.contants.ANIMATION_STATIC' (the default).
+        The second color is set setting a color with whatever ANIMATION_* type is desired.
         See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#setting-led-colors
         """
         for button_name in self.available_names:

push2_python/constants.py

@@ -117,16 +117,23 @@ def is_push_midi_out_port_name(port_name, use_user_port=False):
 # Because push2-python does not send MIDI clock messages to push, all animations will run synced to a 120bpm tempo
 # See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#268-led-animation
 # for more info on what animation names mean
-ANIMATIONS = { 
-    'static': 1,
-    'pulsing_slow': 10,
-    'pulsing': 9,
-    'pulsing_fast': 8,
-    'blinking_slow': 15,
-    'blinking': 14,
-    'blinking_fast': 13
-}
-ANIMATIONS_DEFAULT = 1
+ANIMATION_STATIC = 0
+ANIMATION_ONESHOT_24TH = 1
+ANIMATION_ONESHOT_16TH = 2
+ANIMATION_ONESHOT_8TH = 3
+ANIMATION_ONESHOT_QUARTER = 4
+ANIMATION_ONESHOT_HALF = 5
+ANIMATION_PULSING_24TH = 6
+ANIMATION_PULSING_16TH = 7
+ANIMATION_PULSING_8TH = 8
+ANIMATION_PULSING_QUARTER = 9
+ANIMATION_PULSING_HALF = 10
+ANIMATION_BLINKING_24TH = 11
+ANIMATION_BLINKING_16TH = 12
+ANIMATION_BLINKING_8TH = 13
+ANIMATION_BLINKING_QUARTER = 14
+ANIMATION_BLINKING_HALF = 15
+ANIMATION_DEFAULT = ANIMATION_STATIC
 
 # Push2 actions
 ACTION_PAD_PRESSED = 'on_pad_pressed'

push2_python/encoders.py

@@ -1,5 +1,5 @@
 import mido
-from .constants import ANIMATIONS, ANIMATIONS_DEFAULT, MIDO_CONTROLCHANGE, \
+from .constants import ANIMATION_DEFAULT, MIDO_CONTROLCHANGE, \
     MIDO_NOTEON, MIDO_NOTEOFF, ACTION_ENCODER_ROTATED, ACTION_ENCODER_TOUCHED, ACTION_ENCODER_RELEASED
 from .classes import AbstractPush2Section
 

push2_python/pads.py

@@ -1,5 +1,5 @@
 import mido
-from .constants import ANIMATIONS, ANIMATIONS_DEFAULT, MIDO_NOTEON, MIDO_NOTEOFF, \
+from .constants import ANIMATION_DEFAULT, MIDO_NOTEON, MIDO_NOTEOFF, \
     MIDO_POLYAT, MIDO_AFTERTOUCH, ACTION_PAD_PRESSED, ACTION_PAD_RELEASED, ACTION_PAD_AFTERTOUCH, PUSH2_SYSEX_PREFACE_BYTES, \
     PUSH2_SYSEX_END_BYTES
 from .classes import AbstractPush2Section
@@ -97,18 +97,20 @@ def pad_ij_to_pad_n(self, i, j):
     def pad_n_to_pad_ij(self, n):
         return pad_n_to_pad_ij(n)
 
-    def set_pad_color(self, pad_ij, color='white', animation='static', optimize_num_messages=True):
+    def set_pad_color(self, pad_ij, color='white', animation=ANIMATION_DEFAULT, optimize_num_messages=True):
         """Sets the color of the pad at the (i,j) coordinate.
         'color' must be a valid RGB color name present in the color palette. See push2_python.constants.DEFAULT_COLOR_PALETTE for default color names.
-        'animation' must be an existing key of push2_python.contants.ANIMATIONS dictionary.
+        'animation' must be a valid animation name from those defined in push2_python.contants.ANIMATION_*. Note that to configure an animation, both the 'start' and 'end'
+        colors of the animation need to be defined. The 'start' color is defined by setting a color with 'push2_python.contants.ANIMATION_STATIC' (the default).
+        The second color is set setting a color with whatever ANIMATION_* type is desired.
+
         This funtion will keep track of the latest color/animation values set for each specific pad. If 'optimize_num_messages' is 
         set to True, set_pad_color will only actually send the MIDI message to push if either the color or animation that should 
         be set differ from those stored in the state.
         See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#261-setting-led-colors
         """
         pad = self.pad_ij_to_pad_n(pad_ij[0], pad_ij[1])
         color = self.push.get_rgb_color(color)
-        animation = ANIMATIONS.get(animation, ANIMATIONS_DEFAULT)
         if optimize_num_messages and pad in self.current_pads_state and self.current_pads_state[pad]['color'] == color and self.current_pads_state[pad]['animation'] == animation:
             # If pad's recorded state already has the specified color and animation, return method before sending the MIDI message
             return
@@ -130,29 +132,35 @@ def set_pads_color(self, color_matrix, animation_matrix=None):
             if animation_matrix is not None:
                 assert len(animation_matrix[i]) == 8, 'Wrong number of animation values in line ({0})'.format(len(animation_matrix[i]))
             for j, color in enumerate(line):
-                animation = None
+                animation = ANIMATION_DEFAULT
                 if animation_matrix is not None:
                     animation = animation_matrix[i][j]
                 self.set_pad_color((i, j), color=color, animation=animation)
 
-    def set_all_pads_to_color(self, color='white', animation='static'):
+    def set_all_pads_to_color(self, color='white', animation=ANIMATION_DEFAULT):
         """Set all pads to the given color/animation.
         'color' must be a valid RGB color name present in the color palette. See push2_python.constants.DEFAULT_COLOR_PALETTE for default color names.
+        'animation' must be a valid animation name from those defined in push2_python.contants.ANIMATION_*. Note that to configure an animation, both the 'start' and 'end'
+        colors of the animation need to be defined. The 'start' color is defined by setting a color with 'push2_python.contants.ANIMATION_STATIC' (the default).
+        The second color is set setting a color with whatever ANIMATION_* type is desired.
         """
         color_matrix = [[color for _ in range(0, 8)] for _ in range(0, 8)]
         animation_matrix = [[animation for _ in range(0, 8)] for _ in range(0, 8)]
         self.set_pads_color(color_matrix, animation_matrix)
 
-    def set_all_pads_to_white(self, animation='static'):
+    def set_all_pads_to_black(self, animation=ANIMATION_DEFAULT):
+        self.set_all_pads_to_color('black', animation=animation)
+    
+    def set_all_pads_to_white(self, animation=ANIMATION_DEFAULT):
         self.set_all_pads_to_color('white', animation=animation)
 
-    def set_all_pads_to_red(self, animation='static'):
+    def set_all_pads_to_red(self, animation=ANIMATION_DEFAULT):
         self.set_all_pads_to_color('red', animation=animation)
 
-    def set_all_pads_to_green(self, animation='static'):
+    def set_all_pads_to_green(self, animation=ANIMATION_DEFAULT):
         self.set_all_pads_to_color('green', animation=animation)
 
-    def set_all_pads_to_blue(self, animation='static'):
+    def set_all_pads_to_blue(self, animation=ANIMATION_DEFAULT):
         self.set_all_pads_to_color('blue', animation=animation)
 
     def on_midi_message(self, message):

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 setup(name='push2-python',
-      version='0.2',
+      version='0.3',
       description='Utils to interface with Ableton\'s Push 2 from Python',
       url='https://github.com/ffont/push2-python',
       author='Frederic Font',