

Notice:


   This file is taken from eMusic, a mp3 player by 
   Isaac Richards <ijr@po.cwru.edu>.

   eMusic URL:
   http://www.icom.net/~smelecat/emp3/index.htm

   eMusic includes already a wav,cd,midi player and can
   play sound format I never heard of. Its the only player
   with a good interface between gui <-> decoder, this
   is the reason why I used it.

   After a few modifications this interface now is
   incompatible to the eMusic interface, this is why
   I renamed it.

   I have changed in this text all references from "eMusic"
   to "yaf" and made corrections where both interfaces are
   different, but originally the text was written by Isaac Richards.









		yaf 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 the interface is 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 (*construct)(void);
   void (*destruct)(void);
  
   int open(char* path);
   int close();

   void (*seek)(int second);
   int (*play)(int start_second, char *song);
   void (*pause)(void);
   int (*getStatus)(void);

   void (*getMusicInfo)(struct playlist_item *song);
   void (*getModuleInfo)(char *id, char *version, char *copyright);

   void (*config)(char *left, char *right);

  
};


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

void construct(void)

	any memory allocation, initializing you want to get done goes here..
        This creates a thread.

void (*destruct)(void);
     
        this removes the thread/frees memory.


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(int second)

	Should seek in the audio file to 'second'.

int open(char* path);

        opens a file. returns true if success.


int play();

	plays the file given by 'song'.  

void pause(void)

        pause

int close();

        close the file.


void getMusicInfo(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 getModulInfo(char *id, char *version, char *copyright)

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

int getStreamState();
       The plugin must return if the stream has reached eof or not.
       defined are:
          _STREAM_STATE_EOF
          _STREAM_STATE_NOT_EOF


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

They player never should have control over /dev/dsp.
This is done in other parts.But there must be functions
which inform these other parts about the kind of stream
the player creates. These functions are defined in extern
modules. Your player thread must call them.

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'

