Read Me

GSmartMix is a smart audio mixer for GNOME.
(see http://live.gnome.org/GSmartMix)

* Description of the elements

  - libgsmartmix (src/gsmart-dbus-helper)

     Provides common DBus objects for handling client/sink & server/manager
     over DBus with automatic registration and proxy methods

  - gsmart-manager (src/gsmart-manager)

     Handles the registration mechanism & manage the sinks.
     It provides  its own  mechanism to adjust  the sound  volume with
     class parameters (currently  not really implemented, more details
     later). 

     This manager is needed to have a working GUI or applet, because
     it is the only service who knows the sound sinks that are 
     currently available.

  - gsmart-gui-manager (src/gsmart-gui-manager)

     A widget-test application that will soon feature the class settings.
     Basically, it does what the applet provides too.

  - gsmart-mixer-applet (src/gsmart-mixer-applet)

     A GNOME panel applet to manage the volume of applications.
     It is based on the well known mixer applet, and thus should
     provide at least the same functionnality with the enhancement of
     GSmartMix control too.
  
  - gsmartaudiosink (src/gsmart-elements)

     The GStreamer sink element that implements a sound sink.
      
* Dependencies						
				libgsmart Manager Sink GUI  applet
  - libglib		2.8	     x       x     x    x     x
  - libgobject		2.4          x       x     x    x     x 
  - libgthread		2.4          x       x     x    x     x     
  - libgst		0.10                       x          x
  - libdbus		0.35         x	     x     x    x     x
  - libgconf		2.0                  x          x     x
  - libgconf-bridge	0.1                  x          x     x
  - libgtk		2.0.0	                        x     x
  - libwnck		2.12.0	             o                x
  - libpanelapplets	2.13.4	                              x
  - libgnomedesktop	2.11.1	                              x
		
NB: all this libraries are required to compile the package yet.
NB2: libgconf-bridge is a tiny wrapper for gconf that sync with 
gobject: grab it at http://projects.o-hand.com/libgconf-bridge

* Source code

You  can  get  the  bleeding  edge source  code  from  the  Subversion
repository by typing:

 $ svn co https://svn.sourceforge.net/svnroot/gsmartmix gsmartmix

* How to start playing with sounds

First  of all,  make sure  you have  least the  -dev  required package
installed on your system. Go  into the GSmartMix source directory, and
type: 
    $ ./autogen.sh
   You can override default configuration, for example:
    $ ./configure --enable-more-warnings --prefix=/usr/local 
   Then,
    $ make
    $ sudo make install

Make sure that you have set GST_PLUGIN_PATH to your $prefix directory:
GST_PLUGIN_PATH="/usr/local/lib/gstreamer-0.10:/usr/lib/gstreamer-0.10"

If everything has gone properly, you  should now be able to check that
gsmartaudiosink is installed by launching:

    $ gst-inspect gsmartaudiosink
** Message: no mixer, listen to NameOwnerChanged
Factory Details:
  Long name:    GSmartMix audio sink
  Class:        Sink/Audio
  Description:  GSmartMix Audio sink (alsasink as default output)
  Author(s):    Marc-André Lureau <marcandre.lureau@gmail.com>
  Rank:         none (0)
...

And then try this:

    $ gst-launch audiotestsrc ! gsmartaudiosink

If you have some problem to hear a sound, then you might want to set a
sink  instead of  the default  alsasink.  For  that, you  can  use the
"sink-description" property:

    $ gst-launch audiotestsrc ! gsmartaudiosink sink-description="pulsesink" 

Now, it's  time to update the  gconfsink with a  custom pipeline.  For
that, run  `gstreamer-properties` and edit the custom  output with the
gsmartaudiosink  line that you  have set  with gst-launch.   Make sure
that "Test" is still working.

Now, you can run the sound manager in the background:
    $ gsmart-manager &

Or let D-Bus  run it automatically for you instead if  you have a dbus
service search  path containing the directory  where gsmart-manager is
installed.   For   example,   if   $(prefix)   is   /usr/local,   then
/etc/dbus-1/session.conf should have this line:

    <servicedir>/usr/local/share/dbus-1/services</servicedir>

Install   the  GSmartMix   applet   as  usual   (it   will  be   under
$prefix/libexec).   It  might   help  to   add  this   line   of  your
/etc/bonobo-activation/bonobo-activation-config.xml file:

    <item>/usr/local/lib/bonobo/servers</item>

if you have $(prefix) set to /usr/local.

Of course, you will  have to add it manually to your GNOME panel.

Now you can  start any GNOME application using  GStreamer audio output
and enjoy the control of sounds. One day, there will be control of any
sound source thanks to PulseAudio.

In a near  future, there will be additional material on  how to set up
the smart feature easily.


FAQ
===
 
 * Supported Applications
(evaluation of each of these application is needed, with comments)

		CREATION	VOLUME	BEHAVIOR	STATE CONTROL	UI REFLECT	PATCH NEEDED	CLASS REGISTRATION  COMMENT

Rhythmbox	sink/file	guessed bad		yes		no		small		(Music)
Totem		sink/file	auto	bad		yes		no		small		(Video)		    the volume element is added to the pipeline after GSmartSink 
Sound Juicer	sink/cd(good)	guessed	good		yes		yes (except vol)very small	(Music)
Gaim		x		x	x		x		x		libgnome	(Event)		    don't use GStreamer
Ekiga		x		x	x		x		x		big		Chat/Event	    don't use GStreamer
Listen		sink/file	guessed	bad		yes
Muine		
Banshee
Telepathy		
Countdown

 * What is the relation with gconfaudiosink ?

This GStreamer GConf element purpose is to deal with the GNOME desktop
settings.   With this  key, you  can  set GSmartSink  has the  default
sink. It  will soon be enhanced  to support 3 sound  classes (in CVS):
chat,  music, video.   Each  of these  keys  can be  set  in order  to
describe the sound class:

-> gsmartaudiosink class="Music"
-> gsmartaudiosink class="Video"
-> gsmartaudiosink class="Voice"

 * Session or system wide ?

gsmart-manager  has  been developped  and  tested  with sound  session
management in mind.  The issue to make it system wide will be adressed
later.

 * How do you compete with the sound accessibility requirements ?

Much  of the difficult  requirement for  GSmartMix is  to have  a good
latency between  orders and  sound effect (if  you mute the  sound, it
should be effective quickly). The other problem is related to a system
wide management.  The solution might  be to use PulseAudio has backend
for  stream control (that  would need  some communication  between the
GstPulse sink and a future dbus-enhanced sink in PulseAudio).

Another request expressed by some people is to use Orbit instead of
D-Bus. It might become to be a compilation option after SoC, and if
it still necessary (especially for latency and system wide concerns)

 * How are treated exported $DISPLAY applications (or over a network)?

This  will be  one of  the GSmartMix  challange with  PulseAudio sound
daemon.