Documentation on the Public Domain Clip Library (CPD)
-----------------------------------------------------

Though there is a corresponding binary format, only the ASCII format
is described.

This public library is able to load/save .clip files.

FILE FORMAT
-----------

The ASCII .clip file format is made up of two or three sections: the Clip
section, the Track section(s), and the [optional] Attribute section.  The
whole file must be surrounded by curly braces '{ ... }' and each of the 
track sections must also be surrounded by curly braces.

1) Clip Section
   ------------

    A clip is a collection of tracks or channels.

    rate: 	 float value for the sampling rate (frames per second).
    start:	 float value for the start position (start sample index).
    tracklength: int value for the track length (in samples).
    tracks:	 int value for the number of tracks.

    The first section of the file should look something like this
    (including the opening curly brace at the beginning of the file):

	{
	    rate = 30
	    start = 0
	    tracklength = 10
	    tracks = 3
	
2) Track Section
   -------------

    Each track contains the data for one channel.

    name:	the name of the track.
    lefttype:	the left extend region.
    righttype:	the right extend region.
    default:	float value for the "default" extend mode.
    data:	a list of float values, one for each frame up to tracklength

    The extend regions are the areas outside of the data provided for the
    track.  The left region defines the area before the first sample and
    the right region defines the area after the last sample.  The possible 
    values for these variables are the following:

	hold	- hold the first/last value and extend it left/right
	slope	- extend with the same slope as the first/last value
	cycle	- repeat the values in the forward order
	mirror	- repeat the values, reversing every other cycle 
	default	- hold at the default value

    A track section of the file with a track length of 10 frames should 
    look something like this:	

	    {
		name = chan1
		lefttype = hold
		righttype = hold
		default = 0
		data = 0 1 2 3 4 5 6 7 8 9
	    }

3) Attribute Section
   -----------------

    A clip may or may not contain other attributes.  Currently there is only
    one attribute type, a "quaternion".  This attribute type is used to group
    rotation channel triplets (rx,ry,rz) together.

    quaternions:  the rotation order and number of triplets

    The rotation order for the rotation triplet must be one of the following:
	
	xyz
	xzy
	yxz
	yzx
	zxy
	zyx

    Once the rotation order and number of triplets have been defined, the 
    channel triplets must be listed.  Each triplet is a list of three channel
    indices.

    The attribute section of the file should look something like this
    (with the closing brace at the end of the file):

	    quaternions = zyx 3
	    0 3 6
	    1 4 7
	    2 5 8
	}


