SOURCE DEVICE

The source device generates packetized output on its source port from
a content stream using content format-specific rules.  Its output is
suitable for input to other MAS devices and for transmission over a
network.  Examples include: segmenting a MPEG stream into individual
MPEG frames, stripping headers off 16-bit, linear .WAV content and
doling out 20 millisecond-long packets, etc.  

The source can be used in two modes: file and transform.  In file
mode, a file is read by the device, rules are applied to the file's
contents, and the resultant output is posted to the device's source
port.  In transform mode, input is not from a file but rather from
incoming data to its sink port.  Some buffering of the incoming data
may be required.  [note: transform is not yet implemented -- 26 NOV
2002 - rocko]


The transform method should be viewed as a last resort:  Use of it
implies that the incoming data is in some kind of raw form not
understood by its originator.  This could happen if, for instance, MAS
server "A" had access to proprietary-format content, but not the
devices to interpret it, but MAS server "B" had the necessary
devices.  The content could be streamed with format-independent
packetization to the appropriate source device on MAS server "B".

We borrow some terms from the broadcast music industry: tracks and
playlists.  Each source device has its own playlist.  Notably, the
base device code has been designed to eliminate any perceivable gap
when switching tracks in the playlist.  Tracks that are truely
fragments of what was originally a continuous stream of information
will preserve the continuity.  This means that if the tracks came from
a record that had songs that ran together, or were just movements of a
single piece, that there wouldn't be gaps in the audio output when the
track changed.  Even if the device is handling one file at a time, a
playlist with one entry is allocated for that file.


SUMMARY OF FILES

playlist.[ch]		Playlist management routines.

source_internal.h	Source device internal format-independent structure
			definition and format-dependent (sourcex) function
			prototypes. 

source.c		The format-independent source device stub.
			Requires functions implemented in the format
                        dependent code.

<format>.[ch]		Format dependent file handling code.  <format>
			can be wav, au, mpeg, etc.  Must implement
                        functions defined in source_internal.h.

<format>_profile.h	The format dependent device profile.  



SUPPORTING NEW FORMATS

source.c makes calls to format dependent code defined in
<format>.[ch].	A new <format>.c file must implement the sourcex_
prefixed functions prototyped at the end of source_internal.h.

The <format>_profile.h files define symbols and may only be included
by one file: typically <format>.c.

Define a format-dependent state structure and a format-dependent
stream structure in <format>.h.	 

Try to make only minimal platform-dependent, #ifdef'ed changes to
source.c.  

