===============================================================

Quence PyBuzz 1.5
Python Script System for Buzz-Machines
Copyright (C) 2003,2004,2005 by 
Leonard :paniq: Ritter (paniq@gmx.net)
Parts of this program rely on BTDSys PeerCtrl source code 
copyright (C) 2003 by Ed Powley (e@btd2001.freeserve.co.uk)
and P. DooM's BUZZHACK source code copyright (C) 2001 by 
Peter "P. DooM" Kaufmann (p_doom@space.ch).

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 2 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, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

===============================================================

Quick Manual
============


1. What is PyBuzz?
------------------

    PyBuzz is a peer controller buzz machine that acts as a host
    for python scripts using the python interpreter engine
    developed by http://www.python.org.

    Python scripts loaded into the host have access to it's 256 
    peer controllers which can be routed to control virtually 
    any other machine's parameters.

    They can also read and react to specific buzz events such as
    changed input parameters, stop, tick, work, save, load,
    and others.
    
    Since version 1.2, basic sequencer control is also 
    possible.

2. Installation
---------------

    Usually you can just unzip the whole distribution zipfile
    into your buzz folder, given that the folder structure
    is maintained.
    
    PyBuzz will work without the python distribution as long as
    a local python24.dll in the buzz folder is provided.
    
    However you can install the full distribution of python
    if you plan to do some extraordinary processing. A
    recent distribution setup available for windows (2.4)
    available can be found at:
    
    http://www.python.org/ftp/python/2.4/python-2.4.msi    
    
3. Usage
--------

    When adding a machine, a text console window will open
    that is used by PyBuzz for printing out status and 
    error messages. 'print'-statements issued by scripts
    will also go there.

    You find four menu options when right clicking a PyBuzz
    machine:

    * Import Python Script...
    
        Opens a file dialog in which you can choose a 
        python script to load into the machine. Once the
        script is loaded, it is compiled and instantly
        executed.
        
        Scripts are always saved with songs, so no
        machine depends on external files and can be
        transferred to other pcs that do not have 
        the script.
    
    * Export Python Script...
    
        Opens a file dialog which you can use to store
        the script to disk that the machine currently 
        contains.
        
        This is especially useful if you are dealing with
        songs written by strangers or if you have lost
        the sources to your script.
    
    * Update Import
    
        Once you have loaded a script file into your
        host, you can use this as a shortcut to reload
        the script in case you have made changes.
        
        If the script has OnLoad/OnSave event handlers,
        the handlers will be called for update, allowing
        a script to manage its state during reloads.

    * Show Peer Controllers
    
		Opens the peer controller view. To connect a 
		peer controller to a machine, hold the left 
		mouse button on the controller, drag it
		to a parameter slider of any machine and let go.
		Right click the controller to disconnect it.
        
        In case the target machine is a PyBuzz machine,
        the behaviour of subsequent control changes 
        is undefined.

		You can open this window also by holding the
		CTRL key while doubleclicking the PyBuzz machine.

    * Import State...
    
        Opens a file dialog which lets you choose a state
        data file which is decoded to state objects and
        sent to the script.
        If a script is unable to import state data, you
        will get a python exception on the console.
        
    * Export State...
    
        Opens a file dialog in which you specify a target
        file name for saving the scripts state objects.
        If a script is unable to export state data, you
        will receive an error upon saving.

    * Show Console
    
		Opens the console.
		
		You can open this window also by holding the
		ALT key while doubleclicking the PyBuzz machine.

    When doubleclicking the machine, a python command line 
    interpreter window will open, routing the machine specific
    print messages to its output window.
        
    You can use the command line to run python statements and 
    send commands to the script.
    
    To send a command to a script, try '/<statement>' where 
    statement is a string that the script understands.
    
    BassDrum.py is delivered with this package to give a simple
    example of a PyBuzz script. Once triggered by note 
    on any track, this scripts sends a steady pulse of TPB 
    ticks length to peer controller 0. You can e.g. connect this
    controller to a HD MonsterKick Note parameter for instant
    kickdrum effect.
    
4. Known Bugs and Limitations
-----------------------------

    - PyBuzz machines can neither reroute themselves, nor can 
    they be wrapped. They will not work outside buzz due to the 
    hack methods used to modify parameters that are not open to 
    the buzzmachine API.
        
    - Given a complete python distribution is installed, malicious 
    code that might delete or infect your harddrives could be 
    executed on your machine upon loading of scripts and song 
    files. Therefore PyBuzz issues a warning once when a song is 
    loaded that enables you to disable script execution to export
    and check the scripts safely.

5. Project homepage
-------------------

	For new releases and source code, visit
	
	http://www.sourceforge.net/projects/pybuzz
   
6. Legal Stuff
--------------

	PyBuzz is Copyright (C) 2003, 2004, 2005 Leonard Ritter

	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 2 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, write to the Free Software
	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
