# The Process of Using Instruments

To use instruments, a task must first open the Audio folio then load and prepare the instruments. After the instrument environment is set, the task plays notes on the instruments. When it is finished, the task deletes all instruments and audio items it created and closes the Audio folio. The overall process is as follows:

1. Open the Audio folio

2. Prepare the instruments by loading an instrument template from disc.

   - Create an instrument from the instrument template, allocating RAM and audio resources.
   - Set the tuning of any instrument or template (optional).
   - Load a sample and attach it to the instrument (if it's a sampled sound instrument).
   - Create and attach an envelope to an instrument (optional).
   - Connect the output of one instrument to the input of another instrument (optional).
   - Connect the audio outputs of all instruments to one or more mixers (mandatory if you want to hear the instruments' output).
3. Grab any of an instrument's knobs for later tweaking (optional).

4. Tweak knobs to set an instrument's starting characteristics (optional).

5. Allocate part of the system global amplitude and set individual instrument amplitudes accordingly (optional).

6. Play the instruments.

   - Start a note on an instrument.
   - Wait a specified period of time.
   - Tweak knobs to change an instrument's operation while playing (optional).
   - Release a previously started note (sometimes optional).
   - Stop a previously started note (sometimes optional).
7. Independently play an instrument's attachment, such as an envelope (optional) by starting, releasing, and stopping the attachment.

8. Clean up when finished:

   - Delete all unused instruments.
   - Delete any unused instrument templates.
   - Delete all other unused Audio folio items.
   - Close the Audio folio.

As you can see, there are several optional steps. For example, many tasks do not have any need to set an instrument's tuning; they use the 12-tone, equal-tempered default tuning.

You should also note that the order shown above is not fixed, especially when it comes to playing an instrument. For example, a task can tweak instrument knobs before, during, or after note playing on the instrument. A task can also start a note on one instrument, then load and allocate a new instrument.

Nonetheless, there is some fixed order to the process: a task must load an instrument template before it can create an instrument; it must create an instrument before it can connect the instrument, grab and tweak knobs, or play notes on the instrument; and it must load and connect a sample to a sampled sound instrument before playing the instrument. Beyond the fact that audio items must be created before they are used, most Audio folio order is set by common sense and taste.

See beep.c and playsample.c for examples of the above.