

HOW TO PUT A YAF PLAYER IN THE STREAMING LIB
============================================


If you have written a yaf command line player you like
to put it in the streaming library

edit 

* decoder.h and create a new #define directive for your decoder.
* edit amplifierConfig.cpp and add the command line parameter in
  the a new static variable and then edit the method getExecutable

Thats it.

You now have integrated your decoder in the streaming library.



If you want to test it READ ON IN:

> widgetlib/widgetbasic/examples/example7



Further uninterrsting reading
=============================


This version of the library does not automatically scan for yaf decoders.

A future version searches for yaf-* executables and then 
includes them dynamically.

Why not dlopen decoders?
========================

Xmms or kmp3 and many more uses the BSD calls "dlopen". The decoders are shared 
libraries, and they are loaded with dlopen in the application.
Its a working concept, but IMHO a bad solution.

A streaming library or a server system based on this, must be robust.
Most decoders are very unreliable. And even if a decoder is reliable
then there is "somewhere on earth" a stream which chrases it.

To make this more illustrative:
For example:

If you surf the Web a WWW server does not "dlopen" your netscape communicator,
because if your communicator crashes the WWW server would crash as well.
This is why there is a protocol "http" between them.



Here is more uninteresting backgound
====================================




/*
  The yafAmplifier is the main part of yaf. It starts new decoders
  (like a wav decoder) and controls their behaviour. 

  But how does it work? For now yaf supports only a mp3 decoder
  but there may be more in the future. Thus we must have a few
  informations which decoder we should start with a given
  filename. (For this we have "Config entries".)
  The yafAmplifier can create a give decoder typ (like a mp3 decoder)
  and offers a handle to it.

  On startup the yafAmplifier reads its configurations.
  Example

  YafAmplifier* amplifier= new YafAmplifier();
  yafPlayer=amplifier->create(_MP3_DECODER);



  The create method creates a decoder which can decoder mp3
  files. (The name of the yaf-executabel is taken out of
  the configuration, eg : MP3_DECODER="mpg123-yaf")

  
  The return value of create is an object which gives you the whole control
  about the decoding process. This object then can be connected
  to a controlling GUI.

  But how to start the music?

  For now we have setup a decoder, and the decoder waits for
  input. 

  yafPlayer->open(filename);
  yafPlayer->play();

  But this doesn't play the music on /dev/dsp it simply starts
  decoding and fills the buffer (yafStream Class!)

  When the buffer is full the decoder idles (non active).
  Thus we must make sure that we put the stream "on air".

  yafPlayer->setDevice(_a_device_which_understand_pcm_data)

  In almost all cases this is (at least) an audiodevice.
  But you can create other device.
  


*/





/*
  How pre-buffering can be done:

  Assume that we are currently playing a file to /dev/dsp
  And we want to start the next file.

  int decoderID=amplifer->create(_MP3_DECODER);
  YafAudioDecoder* currentDecoder=amplifier->getDecoder(decoderId);
  int decoderID=amplifier->create(_MP3_DECODER);
  YafAudioDecoder* preBuffer=amplifier->getDecoder(decoderId);


  preBuffer->open("my.mp3");
  preBuffer->play();


  When the current Decoder is ready:

  amplifier->onAir(preBuffer);
  preBuffer=currentDecoder;


*/



/* Future Enhancements:

   Mixing of streams:

   amplifier->onAir(decoder1);
   amplifier->onAir(decoder2);
   ...

*/





