 <sect1 id="soundmonitorapplet">
  <title>Sound Monitor Applet</title>

  <para>
   <application>Sound Monitor</application> applet, shown in its
   default theme (appearance) in <xref
   linkend="soundmonitorapplet-fig">, is a sound volume display and an
   interface for controlling ESD (the Enlightened Sound Daemon) --
   GNOME component responsible for sound output. To add this applet to
   a <interface>Panel</interface>,  
   right-click on the <interface>Panel</interface> and choose
   <menuchoice>
    <guimenu>Panel</guimenu>
    <guisubmenu>Add to panel</guisubmenu>
    <guisubmenu>Applet</guisubmenu>
    <guisubmenu>Multimedia</guisubmenu>
    <guimenuitem>Sound Monitor</guimenuitem>
   </menuchoice>.
  </para>

  <figure id="soundmonitorapplet-fig">
   <title>Sound Monitor Applet</title>
   <screenshot>
    <screeninfo>Sound Monitor Applet</screeninfo>
    <graphic format="png" fileref="figures/soundmonitor_applet" 
    srccredit="muet">
    </graphic>
   </screenshot>
  </figure>

  <!-- ============= Waht is ESD?  ================================ -->
  <sect2 id="soundmonitorapplet-esd">
   <title>Sound in GNOME</title>
   <para>
      GNOME uses a special program, called ESD (the Enlightened Sound
      Daemon), as an intermediary between applications and sound
      card. ESD allows mixing sound from several applications, so that
      you can play a game and hear the sound effects while listening
      to an aduio CD. To hear any sound from GNOME applications, ESD
      must be running. Normally GNOME is configured so that ESD is
      started every time you login; if for some reason this is not so,
      click on the <guibutton>Main Menu</guibutton> button (the foot
      icon) and select
     <menuchoice>
      <guimenu>Programs</guimenu>
      <guisubmenu>Setting</guisubmenu>
      <guisubmenu>Multimedia</guisubmenu>
      <guimenuitem>Sound</guimenuitem>
     </menuchoice>
      and make sure that the option <guilabel>Enable sound server
      startup</guilabel> is enabled, so that the next time you login,
      ESD will be started. You can also start or stop ESD
      using the <application>Sound Monitor</application> applet as
      described below.
    </para>
    <para>
      Non-GNOME applications usually are not aware of ESD and need
      full control of the audio card --- they can not share audio card
      with other applications. This means with such applications, you
      can either have sound from GNOME or sound from non-GNOME
      application, but not both. In many cases, this means that you
      have to temporarily stop ESD to get sound from  non-GNOME
      applications (otherwise, you get error messages like
      <command>Device /dev/dsp busy</command>). 
    </para>
  </sect2>

 
  <!-- ============= Usage  ================================ -->
  <sect2 id="soundmonitorapplet-usage">
   <title>Usage</title>
   <para>
    <application>Sound Monitor</application> always displays the
    volume of sound being produced on your system graphically.
    You may control sound by turning ESD on or off by right-clicking
    on the applet and selecting <guimenuitem>Place Esound in
    standby</guimenuitem> or <guimenuitem>Resume Esound</guimenuitem>
    respectively, as described below.  
   </para>

   <para>
    Right-clicking on the applet brings up a menu containing the
    following items:
    <itemizedlist>

     <listitem>
      <para>
       <guimenuitem>Manager&hellip;</guimenuitem> &mdash; brings
       up the <link linkend="soundmonitorapplet-manager">
       <interface>Sound Monitor Manager</interface></link> dialog,
       which allows you to view and control current ESD settings.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>Place Esound in
       standby</guimenuitem>/<guimenuitem>Resume
       Esound</guimenuitem>/<guimenuitem>Start
       Esound</guimenuitem> &mdash; At any time, you will only
       have one of these three items, depending on whether ESD is
       running and what its status is. The first two menu items
       allow you to
       temporarily place ESD in standby and then resume ESD.
       This is useful if you have a sound application which is
       unable to work with ESD, but needs direct access to the
       sound device. The third allows you to start
       <application>Esound</application> if it is not started. 
      </para>
     </listitem>


     <listitem>
      <para>
       <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
       opens the <link linkend="soundmonitorapplet-prefs">
       <guilabel>Properties</guilabel></link> dialog.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>Help</guimenuitem> &mdash;
       displays this document.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>About&hellip;</guimenuitem> &mdash;
       shows basic information about <application>Sound
       Monitor</application>, inluding the applet's version and the
       author's name.
      </para>
     </listitem>

    </itemizedlist>
   </para>
  </sect2>


  <!-- ============= Customization ============================= -->
  <sect2 id="soundmonitorapplet-prefs">
    <title>Customization</title>
    <para>
      You can customize <application>Sound Monitor</application>
      applet by right-clicking on it and choosing
      <guimenuitem>Properties&hellip;</guimenuitem>. This will open the
      <interface>Properties</interface> dialog (shown in <xref
      linkend="soundmonitor-settings-fig">), which allows you to
      change various settings.
    </para>

    <figure id="soundmonitor-settings-fig">
     <title>Properties dialog</title>
     <screenshot>
      <screeninfo>Properties dialog</screeninfo>
      <graphic format="png" fileref="figures/soundmonitor_applet_settings"
      srccredit="muet">
      </graphic>
     </screenshot>
    </figure>

    <para>
     The properties in the <guilabel>General</guilabel> tab are:
     <itemizedlist>

      <listitem>
       <para>
        Peak indicator &mdash; This controls the behavior of the peak
        indicator (the bright line which tracks the peak volume),
        either turning it off (<guilabel>off</guilabel>), having it
        follow the peak as if it is floating on top
        (<guilabel>active</guilabel>), or having it follow the peak
        smoothing out short spikes and drops
        (<guilabel>smooth</guilabel>). 
       </para>
      </listitem>

      <listitem>
       <para>
        Peak indicator falloff speed &mdash; This controls the speed
        the peak indicator falls back to zero volume (for active mode)
        or moves toward the current volume (for smooth mode).
       </para>
      </listitem>
      <listitem>
       <para>
        Scope (scale 1:X, where X=?) &mdash; This controls the
        horizontal (time) axis scale for <application>Sound
        Monitor</application> "scope-like" themes, i.e., themes that
        show a graph of sound level, with time along the horizontal
        axis. (Since
        the default theme is not a scope, this control does not do
        anything until you have modified the theme, as described
        below.) A value of 1 corresponds to time scale of 44 100
        pixels/second; value of X gives 44 100/X pixels/second. (These
        numbers appear because the standard for CD-quality audio
        stipulates that there should be 44 100 sound samplings per second.)
       </para>
      </listitem>

      <listitem>
       <para>
        Connect points in scope &mdash; This determines whether the
        sampled volume points are connected. (For scope themes only.)
       </para>
      </listitem>

      <listitem>
       <para>
        Screen refresh (frames per second) &mdash; This controls the
        number of times the <application>Sound Monitor</application>
        display is updated each second.
       </para>
      </listitem>
     </itemizedlist>
    </para>

    <para>
     The properties in the <guilabel>Theme</guilabel> tab are:
     <itemizedlist>

      <listitem>
       <para>
        Theme file (directory) &mdash; This is the theme for you
        <application>Sound Monitor</application>, which determines the
        overall appearance of the applet.  You can either select a
        theme from the list <guilabel>Themes:</guilabel>, or else type
        in the directory and name of another theme if available. Some
        of the standard themes are shown in <xref
        linkend="soundmonitorappletthemes-fig">. 
 
        <figure id="soundmonitorappletthemes-fig">
        <title>Example Sound Monitor Themes</title>
        <screenshot>
         <screeninfo>Example Sound Monitor Themes</screeninfo>
         <graphic format="png" fileref="figures/soundmonitor_applet_themes"
         srccredit="muet">
         </graphic>
        </screenshot>
       </figure>
       </para>

      </listitem>

     </itemizedlist>
    </para>
 
    <para>
     The properties in the <guilabel>Advanced</guilabel> tab are:
     <itemizedlist>

      <listitem>
       <para>
        ESD host to monitor &mdash; This option allows you to listen
        to sound being played by ESD on another computer. To do so, 
        enter the network address (or IP address) of a computer to
        monitor in the format <replaceable>host:port</replaceable>.
        The host specified must be running ESD and have their esound
        daemon "unlocked" to allow other machines to connect. Note
        that the default port for ESD is 5001.  Leave
        this entry blank to monitor sound on the local machine.
       </para>
      </listitem>

     </itemizedlist>
    </para>

    <para> 
      After you have made all the changes you want, click on
      <guibutton>OK</guibutton> to apply the changes and close the
      <interface>Properties</interface> dialog. To cancel the changes
      and return to previous values, click the
      <guibutton>Cancel</guibutton> button.
    </para>
  </sect2>


  <!-- ============= Manager ================================== -->
  <sect2 id="soundmonitorapplet-manager">
    <title>The Sound Monitor Manager</title>
    <para>
      To start the <interface>Sound Monitor Manager</interface>,
      right-click on the applet and choose
      <guimenuitem>Manager&hellip;</guimenuitem>. This will open the
      <interface>Sound Monitor - Manager</interface> dialog (shown in <xref
      linkend="soundmonitorappletmanager-fig">), which allows you to 
      view and modify various ESD settings.
    </para>
    <figure id="soundmonitorappletmanager-fig">
     <title>Properties dialog</title>
     <screenshot>
      <screeninfo>Sound Monitor Manager dialog</screeninfo>
      <graphic format="png" fileref="figures/soundmonitor_manager_server"
      srccredit="muet">
      </graphic>
     </screenshot>
    </figure>

    <para>
     The <guilabel>Server</guilabel> tab displays the following information:
     <itemizedlist>

      <listitem>
       <para>
        Server information &mdash; This is a brief description of the
        esound server daemon's current status, including the sound
        output rate to the sound card, the number of currently playing
        sounds (connected streams), and the number of sound samples
        cached in the server.
       </para>
      </listitem>

     </itemizedlist>
    </para>

     <para>
     The properties in the <guilabel>Streams</guilabel> tab are:
     <itemizedlist>

      <listitem>
       <para>
        Connected Streams &mdash; This displays a list of basic
	information for the current sound streams playing through the
	sound server. The user can adjust the volume and balance of a
	stream by first selecting the stream's line, then adjusting
	the volume and balance sliders. 
       </para>
      </listitem>

     </itemizedlist>
    </para>
 
    <para>
     The properties in the <guilabel>Samples</guilabel> tab are:
     <itemizedlist>

      <listitem>
       <para>
        Cached Samples &mdash; This displays a list of basic
	information for the current sounds cached in the sound
	server. The user can adjust the volume and balance of a cached
	sound by first selecting the sound's line, then adjusting the
	volume and balance sliders. To toggle between displaying the
	sound's length as bytes or time (format MM:SS.S) click on the
	length or time column heading.
       </para>
      </listitem>

     </itemizedlist>
    </para>

    <para> After you made all the choices you want, click on
      <guibutton>OK</guibutton> to make the changes and close the
      <interface>Properties</interface> dialog. To cancel the changes
      and return to previous values, click the
      <guibutton>Cancel</guibutton> button.
    </para>

  </sect2>

  <!-- ============= ESDPVD ================================== -->
  <sect2 id="esdpvd">
   <title>The Esound Persistent Volume Daemon (ESDPVD)</title>
   <para>
    The <application>Sound Monitor</application> applet comes with a
    companion program called the <application>Esound Persistent Volume
    Daemon</application>
    (ESDPVD), which can run in the background and remembers the volume
    and balance of each stream that connects to the sound server. The
    main purpose of <application>ESDPVD</application> is to be used in
    conjunction with the <application>Sound Monitor</application>
    applet's <interface>Manager</interface> dialog 
    to retain volume levels for individual streams that
    connect to the ESD sound server.
   </para>
   <para>
    As an example, suppose you are running the
    <application>GTCD</application> CD Player and you 
    lower its volume using the <interface>Manager</interface> window. Normally
    the volume setting will be lost when the program (in this case
    <application>GTCD</application>) is exited and
    restarted. However, if <application>esdpvd</application> is
    running and you start <application>GTCD</application> again, the
    volume will be restored to its previous (in this case, 
    lower) value from before. 
   </para>
   <para>
    If you configure GNOME to start <application>ESDPVD</application>
    each time GNOME is started (using the
    <interface>control-center</interface>'s <interface>Startup 
    Programs</interface> section), <application>ESDPVD</application>
    will remember  sound volume and balance customizations between
    GNOME sessions. 
   </para>
   <para>
    <application>ESDPVD</application> also remembers volume and
    balance adjustments to cached samples (often used for interface
    sound events such as button clicks, menus, etc.).
   </para>
  </sect2>


  <!-- ============= Bugs ================================== -->
  <!-- This section should describe known bugs and limitations of
       the program if there are any - please be frank and list all
       problems you know of -->
  <sect2 id="bugs">
   <title>Known Bugs and Limitations</title>
   <para>
    This applet only shows the sound volume for sound produced by
    GNOME applications (to be precise, sounds passing through ESD); it
    will not show sound volume for applications that directly connect
    to audio card. 
   </para>
  </sect2>


  <!-- ============= Authors ================================ -->

  <sect2 id="authors">
   <title>Authors</title>
   <para>
    <application>Sound Monitor</application> was written by John Ellis
    (<email>johne@bellatlantic.net</email>).  Please send all comments,
    suggestions, and bug 
    reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
    bug tracking database</ulink>. (Instructions for submitting bug
    reports can be found <ulink
    url="http://bugs.gnome.org/Reporting.html" type="http">
    on-line</ulink>. You can also use <application>Bug Report
    Tool</application> (<command>bug-buddy</command>), available in the
    <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
    Menu</guimenu>, for submitting bug reports.
   </para>

   <para>
    This manual was written by Dan Mueth
    (<email>d-mueth@uchicago.edu</email>) and John Ellis
    (<email>johne@bellatlantic.net</email>). Please send all comments
    and suggestions regarding this manual to the <ulink type="http"
    url="http://developer.gnome.org/projects/gdp/">GNOME Documentation
    Project</ulink> by sending an email to
    <email>docs@gnome.org</email>. You can also submit comments online
    by using the <ulink type="http"
    url="http://developer.gnome.org/projects/doctable/">GNOME Documentation
    Status Table</ulink>.
   </para>

   <!-- For translations: uncomment this:

   <para>
    Latin translation was done by ME
    (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
    suggestions regarding this translation to SOMEWHERE.
   </para>

   -->

  </sect2>


  <!-- ============= Application License ============================= -->

  <sect2 id="license">
   <title>License</title>
   <para>
    This program is free software; you can redistribute it and/or
    modify it under the terms of the <citetitle>GNU General Public
    License</citetitle> as published by the Free Software Foundation;
    either version 2 of the License, or (at your option) any later
    version.
   </para>
   <para>
    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    <citetitle>GNU General Public License</citetitle> for more details.
   </para>
   <para>
    A copy of the <citetitle>GNU General Public License</citetitle> is
    included as an appendix to the <citetitle>GNOME Users
    Guide</citetitle>.  You may also obtain a copy of the
    <citetitle>GNU General Public License</citetitle> from the Free
    Software Foundation by visiting <ulink type="http"
    url="http://www.fsf.org">their Web site</ulink> or by writing to
    <address>
     Free Software Foundation, Inc.
     <street>59 Temple Place</street> - Suite 330
     <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
     <country>USA</country>
    </address>
   </para>
  </sect2>

 </sect1>






