A Java library for displaying images on the Ableton Push 2 instrument. The project name, which refers to Javanese shadow puppet artistry, was chosen because it ties together the concepts Java, Push, and images.
communicate with the Push. For that to work, you need to have
libusb installed on your system. If you are on
Linux it is likely already installed, or you can follow their
installation instructions. On the Mac, I recommend using
Homebrew for all such needs; once it’s
installed, you can simply run
brew install libusb.
Wayang is available through Maven Central, so to use it in your Maven project, all you need is to include the appropriate dependency.
Click the maven central badge above to view the repository entry for Wayang. The proper format for including the latest release as a dependency in a variety of tools, including Leiningen if you are using Wayang from Clojure, can be found in the Dependency Information section.
If you want to manually install Wayang, you can download the library
from the releases page
and put it on your project’s class path. Be sure you get the
right version: the much larger file whose name ends
-jar-with-dependencies.jar contains everything you need to
libusb from Java. The smaller Wayang jar is for use
with dependency management systems like Maven. You can download that
one if you’d like, but you will then also be responsible for
and any transitive dependencies it might have.
Once you have the Wayang library added as a dependency, all you need to do to draw to the Push display is:
import org.deepsymmetry.Wayang; // ... BufferedImage displayImage = Wayang.open(); Graphics2D graphics = displayImage.createGraphics(); // Perform whatever Java2D drawing operations you'd like to using the graphics object, // then, whenever you want to update what is showing on the Push: Wayang.sendFrame(); // If you want to maximize your frame rate, you can also send frames asynchronously: Wayang.sendFrameAsync(); // If you are done talking to it, you can close, as below. Otherwise, the library cleans // up for you when the JVM exits. Wayang.close();
The image you get from
Wayang.open() is 960 pixels wide and 160
pixels tall, the same as the physical display. These values are also
available as the constants
This photo shows the results of running
mvn test in the project directory:
Capturing Your Interface
You can save animated GIF files to provide highly meaningful documentation for your user interfaces, thanks to an embedded version of Elliot Kroo’s GifSequenceWriter. To do that, just call:
import org.deepsymmetry.GifSequenceWriter; // ... ImageOutputStream output = new FileImageOutputStream(new File("out.gif")); // Pass in the displayImage buffer that Wayang.open() gave you, the // interval in milliseconds at which you update the display, and // whether you want the animation to loop: GifSequenceWriter writer = new GifSequenceWriter(output, displayImage, 50, true); // Then whenever you are calling Wayang.SendFrame(), also call: writer.writeToSequence(displayImage); // When you are done recording, call: writer.close(); output.close();
Here is an example recording from Afterglow’s Push 2 interface:
Push Interface Documentation
Ableton has released the documentation that enabled the creation of this library as its own project on Github, push-interface.
Copyright © 2016–2020 Deep Symmetry, LLC
Distributed under the Eclipse Public License 1.0. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software. A copy of the license can be found in assets/epl-v10.html within this project.