     [file texiutils.texi not included]

Architecture
Tim Janik
Stefan Westerfeld

Document revised:

This document provides an architectural overview of the audio synthesis package and related components.

Programs and Libraries
**********************

Programs and Libraries

 1. SFIDL - The IDL compiler (sfidl) used for language bindings and plugins

 2. BseWaveTool - A small program to generate multi-sample .BSEWAVE files

 3. BEAST - a Gtk+ based GUI front-end (beast) for

 4. GXK - a library containing extensions to Gtk+, such as XML-parser for widget templates or an action administration system

 5. BSESH - a Guile based scheme shell (bsesh) for

 6. - synthesis and sequencing library

 7. - Interface library, consisting of:

       * a value abstractiong SfiValue (based on GValue)

       * a serializable parameter abstraction based on GParamSpec

       * a threading abstraction SfiThread (based on GThread)

       * primitive type implementations (record, sequenzes, rings)

       * a glue layer to allow function calls and signals across process boundaries

       * a simple communication layer based on SfiValue for process boundaries

       * basic serialization mechanisms to allow implementations of persistent object storage

       * miscellaneous utilities.

 8. GLib-Extra - utility functions which are subject to be folded back into GLib at some point.

Components
**********

Components

 1. BSE-Shell - a Guile based scheme shell (bsesh) for used for scripting and to run standalone scripts

 2. - a Gtk+ based GUI front-end (beast) for

 3. - the sequencing and synthesis core, consisting of:

       * Plugin interface

       * MIDI Event processing logic

       * MIDI File import

       * Undo/redo stack

       * Object framework

       * Glue layer + scripting objects

       * Song, track, part, mixer and wave objects

       * Synthesis networks

       * Sequencer (seperately threaded)

       * Synthesis Engine (seperately threaded)

       * Input output drivers for PCM and MIDI

       * OSS MIDI and PCM driver

       * Standard synthesis modules

Samples and Wave Files
**********************

Sample Data is organized at three levels:

 1. Wave Chunks - a chunk contains one sample

 2. Waves - multiple chunks can be put into a wave; this allows storing different samples which should be played for different notes

 3. Wave Libraries - multiple waves can be put into a wave library

Extra Information (XInfo Strings) for Wave Files
================================================

XInfos consist of a list of ``key=value'' pairs. Values need to be valid UTF-8 strings, while keys may consist only of the lowercase letters 'a'-'z', the digits '0'-'9' and a dash '-'.

Wave Chunk specific XInfos
--------------------------

  * osc-freq - Note frequency (oscillator frequency) the chunk should be played back at. In other words, the note that was played when the chunk was recorded.

  * loop-type - The loop type needs to be set to indicate that the sample should be looped. Possible values are:

      1. "none" - no loop

      2. "jump" - plays from loop start to loop end, then jumps back to loop start

      3. "ping-pong" - plays from loop start to loop end and then backwards from loop end to loop start

  * loop-start - The offset in samples for the start of the loop.

  * loop-end - The offset in samples for the end of the loop.

  * loop-count - A maximum limit for how often the loop should be repeated.

  * gus-patch-envelope - Contains the envelope points for a GUS Patch envelope.

Wave specific XInfos
--------------------

  * authors - A list of the authors who participated in creating the wave file.

  * license - The license specifiing redistribution and other legal terms for the wave file.

  * blurb - A descriptive text for the wave file.

  * play-type - Indicates the set of required play back facilities for a wave. Supported values are:

      1. wave-mono - for mono wave files,

      2. gus-patch - for GUS Patches (which need a special envelope).

Wave Library specific XInfos
----------------------------

There are currently no XInfos defined for Wave Libraries, as Wave Libraries are not yet supported.