
		eMusic player plugin API 0.1

   All player plugins must export the following functions, look in the
   player subdirectory for working examples...  players/common.h should
   provide all necessary data structs, and functions..  Using the audio output
   functions provided by eMusic is preferable, but not completely necessary.
   
   Look in players/tplay/tplay.c for a fairly clean example..

-------------------------------------------------------------------------------
FUNCTIONS PLUGINS NEED TO PROVIDE:
-------------------------------------------------------------------------------
The player plugins need to fill in the function prototypes of the player_plugin
structure by using the following function, as defined below:

struct player_plugin *setup_plugin(void)

	Just allocate a 'struct player_plugin', set all the function protos
	to what they're called in the plugin, and return the struct..

The plugin functions are:


struct player_plugin {
   void (*init)(void);
   void (*config)(char *left, char *right);
   void (*seek_to_frame)(int second);
   int (*play)(int start_second, char *song);
   void (*pause_it)(void);
   void (*stop)(int playing);
   int (*is_file)(char *path);
   void (*get_info)(struct playlist_item *song);
   void (*version_info)(char *id, char *version, char *copyright);
   char *id;
   char *version;
   char *copyright;
   void *handle;
   int loaded;
   char *soname;
   struct player_plugin *next;
};

What these functions need to do:
--------------------------------

void init(void)

	any memory allocation, initializing you want to get done goes here..
	plugins are not dynamically removed as of yet.. This will change in a 
	DR or two.

void config(char *left, char *right)
	
	takes strings from the MAIN.players file, left would be the key, right
        would be the value.  Any user configurable values will be parsed here.

void seek_to_frame(int second)

	Should seek in the audio file to 'second'.

int play(int start_second, char *song)

	plays the file given by 'song'.  It should honor the start_second, but
	this isn't necessary.  This function should start a separate thread for
	the actual playing process..  see the players/ subdir for examples

void pause_it(void)

	if the player needs to do anything special to pause playing, do it here

void stop(int playing)

	stop the stream..  If you care about whether it was playing or not 
	(eg. the cd player ejects the cd if it wasn't playing) that info is in
	'playing'

int is_file(char *path)

	returns TRUE if the player can handle the file at 'path', false
	otherwise

void get_info(struct playlist_item *song)

	get all info (id3 tag, length, song title) in the 'song' struct..
	needs to at LEAST set the song title..
 
void version_info(char *id, char *version, char *copyright)

	set's the plugins info for the banner at the beginning..

-------------------------------------------------------------------------------
eMusic FUNCTIONS THAT COULD BE USEFUL:
-------------------------------------------------------------------------------

int setup_audio(int frequency, int stereo, int sign, int big, int sixteen)

	Start up the audio buffer, in the format indicated...  stereo, sign, 
	big, and sixteen are all boolean values, represtenting the number of
	channels, signedness, endianness, and bit size of the audio stream.
	frequency is frequency in Hz.
        setup_audio() will return a 0 if it completes sucessfully.


void close_audio(void)

	close down the audio buffer..  please call when done =)

void flush_audio(void)

	if you need to stop audio playing abruptly

int audio_play(char *buffer, int size)

	play to eMusic's audio buffer..

int parsebool(char *data)

	returns TRUE or FALSE from a human entered 'data'

int end_of_song;

	this int MUST be set to TRUE when the song file has completed playing.
	Failure to do so will cause mass confusion, chaos, and death.
