
This file describes the basic concepts of yaf.



The yaf-approach

Most players avaiable today are command line tools. 
(amp,mpg123,wavplay,...)
To use these players in a GUI you have different possibilities.

1. You can integrate them in the GUI statically linked
2. or can communicate over shared memory with them
3. communicate with the player over streams.
4. write a shared libary for the player and dynamically link it


yaf takes the 3. approach.

The 1. approach has the disadvantage that the GUI must include
the source code. 
PROBLEMS:
* The player becomes an integrated part which leads to 
  the problem that the GUI-maintainer must maintain the player code as well.
* If the decoder crashes it takes the GUI away as well.
  (Very annoying,but very popular if you look at the current frontends today)
* And its impossible to add new decoders without compiling
* But what counts more: 
  The most decoders have really bad source code 
  (eg:global vars, look into your favourite decoder here) and
  this leads to the problem that you cannot ran multiple
  instances of it concurrently (without forks and IPC)
  But if you have an (internally) forked programm you can directly 
  make it a seperate program (see 2,3,4)
  

The 2 approach is better than the first. It defines an 
well known interface between the player and the GUI.
Its fast, you can ran mutiple instances as seperate programms, 
and in generall I think this is a good solution. 
But it has one disadvantage:
You cannot debug the player easily. Because you
always need 2 processes and a shared memory segment.
(I think for example the email SMTP protocol would not be that
 popular if it would use shared memory insted of text :)


The 3. approach is done by yaf. Every player with the yaf 
interface works on the command line, but
what counts more, is that you can test and debug the player
on the command line as well. No need for a shared memory
segment to test the player!
A programmer can test the player just by typing commands 
like: open or play or stop. 
Multiple instances are possible.(as seperate programs)
I think this is easier to maintain than 2.
But this has the problem that there has to be source code
which parses "text protocols".
If the decoder crashes because of bad streams the GUI is not
affected and can easily recover from that.



4. Another bad solution look at 1.
   But it has the advantage that you can keep the decoders
   and the gui in seperate source distributions.(like xmms does it)
   (But this is possible with approach 3. as well. And even better, because
   the seperate distribution is a standalone, full working decoder,
   which can work without any GUI or beter "loader program==dlopen")
   Another disadvantage:
   Your GUI must (obviously) link against the same libraries as
   the shared lib. 




backend/frontend


A yaf-player is a command line tool which understands
a set of basic commands. If a yaf-player is started
it waits on stdin for new commands.
This program is the backend of a controlling GUI, but
it does not need it. If a user enters these
commands or if they are "send" by a GUI is not
important for the backend.
The yaf packages includes classes which make a yaf
port of a player fairly easily.

The GUI is the frontend. It can start new yaf-players
and manage their behaviour. The main part is done
in the GUI. But because every player works with
a yaf-GUI it is worth the effort :)


The interaction between the GUI and the backend is done
with the yaf-Protocol. Its not a complex protocol
and a programmer of a yaf-player does not need
to know much about it. It works automatically.
The main things it does is to make sure the
GUI establish itsself as the output of the command line
decoder.
For example it establish a socket connection where
the audio data goes, or establish a shared memory
segment where the video data should go. (currently not implemented)
The text based outputs by the decoder are used to describe
the stream _content_ eg: audio: 44.1KHz stero 16 Bit ,
video: 350x240 32 Bit depth.


The directory structure of the package refect this.
In the backend directory are the yaf-wrappers for
the players and in the frontend directory are the
classes for the GUI. 




