/*

 *  COMPOSITION

 *

 *  CONTENTS

 *

 *  0. Each player's graphic objects, and how to use them

 *  1. What the audience sees and hears

 *  2. Routing diagram

 *

 *

 *  0. EACH PLAYER'S GRAPHIC OBJECTS, AND HOW TO USE THEM

 *

 *     Let's start by taking a look at each player's graphic

 *     objects.  Assuming you've already set up the network,

 *     open "openMeToPlay.html", set the values as appropriate,

 *     and run the code.  If you are player 0, you should see

 *     4 windows pop up: "CodingWindow", "MsgWindow", "SynthWindow",

 *     and "ConductorWindow".  Otherwise you should see only 3 windows

 *     (no "ConductorWindow").

 *

 *     A. CONDUCTORWINDOW

 *

 *        This is essentially a button to start and stop the piece.

 *        When player 0 clicks it, the clocks in each player's MsgWindow

 *        should start ticking; click it again, and the clocks stop.

 *        It interprets messages sent by each player's CodingWindow, and

 *        it relays sound, image, and message data to each player and

 *        to the projected graphics.

 *

 *     B. MSGWINDOW

 *

 *        MsgWindow displays the current time and any messages it receives

 *        through the ConductorWindow.  It is not interactive.

 *

 *     C. SYNTHWINDOW

 *

 *        Each player controls a crude impulse-wave oscillator with only two

 *        parameters: frequency and amplitude (an on/off switch).

 *        The SynthWindow displays the oscillator's frequency in Hz;

 *        the color of the number shows whether the oscillator is on

 *        (in which case it's green) or off (in which case it's red).

 *        SynthWindow is not interactive.

 *

 *     D. CODINGWINDOW

 * 

 *        This is an interactive window for typing messages, which each

 *        player uses to control their oscillator.

 *        By typing a time followed by a frequency, you can schedule a

 *        frequency change.  For example, the message

 * 

 *           1:30 4411.1

 *

 *        will change the oscillator frequency to 4411.1 Hz when the clock hits

 *        1:30.  The time needs to be between the clock's current time and the

 *        end of the piece;  e.g. if the current time is 04:15 and the piece

 *        lasts until 15:00, the `time' argument can be 8:13.015, but not 2:01

 *        or 20:50.  The time format is as follows:

 *        at least one minute value, a colon, exactly two second values

 *        (from 00 to 59), and an optional period and fractional second value, e.g.

 *

 *           12:34

 *           0:00.0001

 *           01:23.3521

 *

 *        Frequency is any number, though you should constrain your choices

 *        between 4410 and 4454.1.

 *

 *        Players can also schedule amplitude changes. A time followed by

 *        "+" turns on the synth at the appointed time, while a time followed

 *        by "-" turns it off.  For example:

 *

 *           1:45 +

 *           3:12.2 -

 *

 *        You can change frequency and amplitude at the same time:

 *

 *           14:59.99 4450.12 -

 *

 *        Oscillator-control messages only work when the clock is running.

 *        The ConductorWindow will try to interpret every message you send

 *        as an oscillator control message; if it succeeds, you'll get a

 *        message in your MsgWindow saying

 *

 *           Scheduled sound event at [whatever time you scheduled it for]

 *

 *        If it fails for any reason (a malformed message; a time that's too

 *        late), your message appears in every player's MsgWindow, including

 *        your own.  This is not so that the other players can make fun of

 *        you; rather, it allows you to use the MsgWindow as a simple

 *        communication channel, to organize musical events ahead of time.

 *        For example, if you are player 3, and you type:

 *

 *           2 + 4: let's turn on at 4:12

 *

 *        everyone, including players 2 and 4, will see the message

 *

 *           3 > 2 + 4: let's turn on at 4:12

 *

 *        Then players 2, 3, and 4 can each write

 *

 *           4:12 +

 *

 *        and, behold, at 4:12 you'll hear a three-voice chord.

 *

 *        THIS POWER TO ARRANGE MUSICAL EVENTS IN ADVANCE THROUGH

 *        MESSAGING IS THE CRUX OF THE PIECE!  YOU ARE ESSENTIALLY

 *        COMPOSING THE PIECE LIVE.

 *

 *        Most of your practice should be devoted to learning to work as a group to

 *        devise effective messaging strategies, and to use them to create

 *        interesting musical events with the most limited means.

 *        Messaging and planning ahead is so important that I imagine

 *        five minutes of typing (or more!) before any sound is even produced.

 *

 *

 *  1. WHAT THE AUDIENCE SEES AND HEARS

 *

 *     To demonstrate the piece in action, I've included an

 *     audiovisual simulation that's roughly five minutes long.

 *     It shows about 3 minutes of idealized typing and 2 minutes of sound.

 *     This is shorter than the piece should be, but I hope

 *     it's nevertheless helpful.  It should give you a sense of what the piece

 *     will look like to someone in the audience; it doesn't show what

 *     each player sees on their own computer screen.

 *     Run the following block of code:

 *

 */


(

b = SimulationBundle(

offset: 0,                   // the starting point, in seconds

projection: false,           // set to true if you're plugged into a projector

thisScreenWidth: 1280,       // the width of your monitor, in pixels

projectionScreenWidth: 1280, // the width of the projection, in pixels

displayHeight: 720           // the height of the display, in pixels (default 720)

);

)



/*

 *     There are three windows displayed: a CharWindow on top, a

 *     FreqTablesWindow in the middle, and a MsgWindow on the bottom.

 *

 *     A. CHARWINDOW

 *

 *        Displays characters as the players type, interleaving their messages.

 *

 *     B. FREQTABLESWINDOW

 *

 *        These are two tables of acoutic beats.

 *

 *        - On the left, a table showing the differences of the players'

 *          impulse wave oscillators' fundamental frequencies.

 *          Again, the frequencies should range from 4410 Hz to 4454.1 Hz;

 *          the beating frequencies should therefore

 *          vary from 0 Hz to 44.1 Hz.  4454.1 / 4410 = 101 / 100, an interval

 *          that's about one-seventieth the size of an octave (or, a little

 *          larger than a twelfth-tone).

 *

 *        - On the right, a table showing the ratios of impulse-wave sampling

 *          glitch frequencies.  If the sampling rate is 44100, then there are

 *          exactly 10 samples per 4410 Hz impulse.  An impulse wave tuned close

 *          to 4410 Hz causes the computer to add or skip a sample periodically:

 *          e.g. if the frequency is 4411 Hz, the sampler needs to "squeeze in" one

 *          more impulse every second, so every 0.1 second it has to shorten

 *          an impulse to 9 samples while keeping the others 10 samples long.

 *          This creates an audible 10 Hz glitch!  More generally, an impulse

 *          wave tuned close to 4410 Hz glitches at a frequency 10 times its

 *          deviation from 4410, or

 *

 *             10 * abs(freq - 4410)

 *

 *          In this piece, the glitch frequencies vary from 0 Hz to 441 Hz.

 *

 *     3. MSGWINDOW

 *

 *        Displays oscillator control messages at the moment the computer

 *        executes them.

 *

 *  2. ROUTING DIAGRAM

 *

 *     In "routing.pdf", I summarize each window and show what's sending messages

 *     to what.

 *

 *  That's it for now!  Open "openMeToPlay.html" and give it a shot.

 *

 */