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

Quence PyBuzz 1.2
Python Script System for Buzz-Machines
Copyright (C) 2003 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).

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

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 python23.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.3.3)
    available can be found at:
    
    http://www.python.org/ftp/python/2.3.3/Python-2.3.3.exe
    
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.
    
    * Assign Peer Controller...
    
        Allows you to assign one of the 256 peer controllers
        to another machine's parameter.
        
        In case the target machine is a PyBuzz machine,
        the behaviour of subsequent control changes 
        is undefined.

    * 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.

    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. Legal Stuff
--------------

    Neither the author of this software, nor any of its
    contributors can me made liable for any loss or damage caused 
    by this software.