{code:none} OVERVIEW shado is a compositing and sprite library for the monome. It is written in Java, but designed to be dynamically scripted in a language like Python and hosted in MaxMSP (or Pluggo, for VST plugins). The common usage scenario is to install shado alongside our Java Python interpreter in a MaxMSP system, and drive it via Python scripts triggered and controlled by MaxMSP messages. The file README.MANUAL will eventually be the manual for shado; for now, it contains an explanation of the shado architecture - quite possibly, along with the examples, just about enough to start writing shado "programs". See README.RELEASES for information about releases, and any API changes. INSTALLATION There is a quick-install note online, at: http://www.loadbang.net/space/Software/net.loadbang.shado/Tutorials/Installation What follows is somewhat more detailed. This package contains the core shado library, plus a copy of the net.loadbang OSC (Open SoundControl) library, plus all sources and javadocs. If you are a hardcore Java developer as well as a monome user, this might be all you need, but it's more likely that you will want to run MaxMSP and use Python as your scripting language. (NB: we have used Max 5 for our example patchers. Since most of the work is in Python, and since the script systems also run under Max 4, we've back-ported the "simple" demo patcher to Max 4.) For Python, you need the net.loadbang.jython package: http://www.loadbang.net/space/Software/net.loadbang.jython Feel free to opt for the Groovy interpreter instead, but all our example scripts are in Python, and we much prefer it as a language: it's clearer to read, better designed and supported, and it has generators and list comprehensions, which are very well suited to building sequencers and musical algorithms. shado now makes some use of net.loadbang.lib so we now include it here. This library is also used by the Jython and Groovy packages. We need net.loadbang.lib-1.4; older releases of Jython and Groovy have 1.3 or earlier, so discard these versions. The net.loadbang.jython release comes with its own example patcher and a pile of scripts, so it may be a good familiarisation exercise to explore these before working with shado proper. Once you have installed net.loadbang.jython as per its instructions, copy the enclosed JAR files (net.loadbang.osc-[...].jar and net.loadbang.shado-[...].jar) into the Cycling '74/java/lib directory (or modify max.java.config.txt to include the appropriate directory). Be sure to remove old or obsolete versions. Copy the files in the shado-examples/ directory into Max's search path. (If you are using the free Max Runtime, copy them into a directory inside the MaxMSP application directory.) GETTING STARTED Try to get the examples in the "simple" directory up and running. Since shado uses OSC, you will need to run MonomeSerial in OSC mode. If your monome is on the same machine as Max, and you use a prefix "/shado" with the default OSC ports, then the workspace patcher (max5/workspace.maxpat) and its scripts should run unaltered (although the examples assume a monome sixty four). Fire up the patcher, select the name of a script from the tabs, turn on the metros, and push some monome buttons. If you want to configure anything, edit the file config.py and change the declarations at the top. All the examples use this module to build the OSC renderer. Change the "udpreceive" statement in the Max patcher if you want to listen on a different OSC port. (If you don't have a Max 5 license, you can edit the .maxpat file directly in a text editor.) More detailed documentation will be coming soon. In the meantime, look at the file README.MANUAL: it contains an overview of shado's architecture and components, and should have enough fragments of Python code to get you started. Peruse the javadocs for more detail. This release contains all the Python scripts and the patcher for the Gerry Anderson UFO demo - the system is called "tapestry". If you feel brave, have a poke around. ISSUES We're not yet using our OSC library for input - it needs a tidy-up - so button press events are currently captured in Max and routed into the system via Python. (This makes it a bit tricky to kick off a shado program standalone from a console, although this is definitely one of our aims.) Our fireflash multi-monome emulator works as a console application, so look to that for example code. ZEROCONF / BONJOUR Shado now supports the new protocol provided by SerialOSC (MonomeSerial is deprecated). SerialOSC is Zeroconf/Bonjour-based and part of the protocol provides a facility to set a "back channel" port for SerialOSC to send OSC to the application. (In MonomeSerial, ports were set manually.) We don't yet support the configuration parts of the protocol, so ports need to be set manually in shado code. See: http://docs.monome.org/doku.php?id=app:serialosc which details where port settings are stored in preference files on disk. LICENSE This software is issued under the terms of the GNU General Public License (see COPYING). NOTE: the other loadbang.net libraries are issued under the GNU Lesser General Public License, but the shado library has a more restrictive (or, if you prefer, "more free") license in that the library cannot be used in proprietary programs - we regard shado as a component of artistic expression, and do not feel that proprietary use fits with this philosophy. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see < http://www.gnu.org/licenses/ >. CONTACT Nick Rothwell, nick@cassiel.com / nick@loadbang.net {code} 2011-05-24 11:17:55.855 2008-06-27 21:33:10.0