README

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