esound.sgml

linux下的终端管理工具源码

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 ]>

<book id="index">

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

  <bookinfo>
    <date>1998-01-13</date>
    <title>EsounD</title>
    <subtitle>The Enlightened Sound Daemon</subtitle>
    <releaseinfo>documentation in progress</releaseinfo>
    <authorgroup>
      <author>
	<firstname>Eric</firstname>
	<othername>'Ricdude</othername>
	<surname>Mitchell</surname>
      </author>
    </authorgroup>
    <address>
      <email>[e-mail]</email>
    </address>
    <copyright>
      <year>1998</year>
      <holder>Eric B. Mitchell</holder>
    </copyright>
    <legalnotice id="legalnotice">
      <para>
	This document can be freely redistributed according to the
	terms of the GNU General Public License.
      </para>
    </legalnotice>
  </bookinfo>
  
  <chapter id="introduction">
    <title>Introduction</title>
    
    <para>
      So you've got your (insert sound playing program here) cruising
      at full tilt, and you want to check out this cool Monty Python
      quote, but you don't want to kill the original sound?  This is
      just the fix, with a little tweaking, of course. =P
    </para>
    
    <para>
      The Enlightened Sound Daemon can mix several audio streams into
      one sound device.  It will mix in pre-loaded samples, too.  Want
      to play a frightening sound whenever the user presses the
      &quot;go&quot; button?  No problem, just cache it, and play it
      back by sample id number.
    </para>
    
    <sect1 id="caveats">
      <title>Caveats</title>
      
      <para>
	This is hot off the presses software, get it while it's still
	hot.  It's still got a ways to go yet.  Be prepared for a
	bumpy ride.  Any and all reasonable patches and improvements
	accepted.  I expect the communication protocol to change at
	least once more before it hits 1.0.
      </para>
      
    </sect1>
    
    <sect1 id="requirements">
      <title>Requirements</title>

      <para>
	The Enlightened Sound Daemon requires the following:
      </para>

      <para>
	Linux, version 2.??? or higher.  I run 2.0.34-RH5.1, but I don't think
	the sound API has significantly changed recently.  If you find it to
	be incompatible with different kernel/OSS revs, let me know.
      </para>

      <para>And of course, a sound device.
      </para>

      <para>
	Currently, this only runs under Linux.  Everything except recording
	seems to work ok on SGI/Irix soon.  Reports indicate it works ok on
	Solaris.  Ports to other platforms are requested.  Basic drivers for
	other platforms are in the distribution, but may need work from what's
	in the driver_platform.c files.
      </para>

    </sect1>

  </chapter>

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

  <chapter id="downloading-compiling-installing">
    <title>Downloading, Compiling, and Installing</title>

    <sect1 id="downloading">
      <title>Downloading</title>

      <para>
	The Enlightened Sound Daemon is available for download from

	<itemizedlist>
	  <listitem>
	    <para><ulink url="ftp://ftp.enlightenment.org/pub/ricware/esound-0.2.4.tar.gz">
		Enlightenment.org public ftp site</ulink></para>
	  </listitem>

	  <listitem>
	    <para><ulink url="http://winblowz.com/~e/files/TAR/esound-0.2.4.tar.gz">
		Winblowz.com Enlightenment Mirror Site</ulink></para>
	  </listitem>

	  <listitem>
	    <para><ulink url="http://www.netcom.com/~ericmit/esound_0_2_4.tgz">
		The EsounD Web Site</ulink></para>
	  </listitem>
	</itemizedlist>

      </para>

    </sect1>

    <sect1 id="compiling">
      <title>Compiling</title>

      <procedure>

	<step>
	  <para>Extract the contents of the archive.</para>
	  <literallayout>
	    <prompt>&gt; </prompt><userinput> tar xvfz esound-0.2.4.tar.gz</userinput>
	  </literallayout>
	</step>

	<step>
	  <para>To compile the package, change to the newly created
	    esound-0.2.4 directory, and type:</para>
	  <literallayout>
	    <prompt>&gt; </prompt><userinput> configure ; make all</userinput>
	  </literallayout>
	</step>

	<step>
	  <para>A sample test script is provided, follow the directions
	    given by the test script:</para>
	  <literallayout>
	    <prompt>&gt; </prompt><userinput> ./test-script</userinput>
	  </literallayout>
	</step>

      </procedure>

      <para>
	The sound daemon, and the command line toolset should build as is.
	All executables should run fine from the source directory.
      </para>

    </sect1>

    <sect1 id="installing">
      <title>Installing</title>

      <procedure>
	<para>
	  Installing the EsounD package is accomplished by typing:
	</para>

	<step>
	  <para>
	    <literallayout>
	      <prompt>&gt; </prompt><userinput> make isntall</userinput>
	    </literallayout>
	  </para>
	</step>
      </procedure>

      <para>
	This will copy all relevant files to useful/accessible places.
      </para>

    </sect1>

  </chapter>

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

  <chapter id="running-esound">
    <title>Running EsounD</title>

    <sect1 id="esd">
      <title>esd</title>

      <para>
	The Enlightened Sound Daemon
      </para>

      <para>
	<command>esd</command> <option>[options]</option>
      </para>

      <informaltable frame="all">
	<tgroup cols="2">
	  <thead>
	    <row><entry>option</entry><entry>purpose</entry></row></thead>
	  <tbody>
	    <row>
	      <entry>-nobeeps</entry>
	      <entry>inhibits the default startup tone sequence</entry>
	    </row>
	    <row>
	      <entry>-d DEVICE</entry>
	      <entry>use audio device DEVICE (esd -h for values)</entry>
	    </row>
	    <row>
	      <entry>-b</entry>
	      <entry>run server in 8 bit sound mode</entry>
	    </row>
	    <row>
	      <entry>-r RATE</entry>
	      <entry>run server at sample rate of RATE</entry>
	    </row>
	    <row>
	      <entry>-as SECS</entry>
	      <entry>free audio device after SECS of inactivity</entry>
	    </row>
	    <row>
	      <entry>-vt</entry>
	      <entry>enable trace diagnostic info (debug builds only)</entry>
	    </row>
	    <row>
	      <entry>-vc</entry>
	      <entry>enable comms diagnostic info (debug builds only)</entry>
	    </row>
	    <row>
	      <entry>-vm</entry>
	      <entry>enable mixer diagnostic info (debug builds only)</entry>
	    </row>
	    <row>
	      <entry>-port port</entry>
	      <entry>accept connections on given port (default=5001)</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>
	In addition, "kill -HUP esd-pid resets ownership of the daemon.
	The file, &tilde;/.esd-auth, is used for authentication, and is
	created if needed.
      </para>

    </sect1>

    <sect1 id="esdctl">
      <title>esdctl</title>

      <para>
	controls certain aspects of the sound daemon.  
      </para>

      <para>
	<command>esdctl</command> <option>[options]</option>
      </para>

      <informaltable frame="all">
	<tgroup cols="2">
	  <thead>
	    <row><entry>commands</entry><entry>purpose</entry></row></thead>
	  <tbody>
	    <row>
	      <entry>lock</entry>
	      <entry>foreign clients may not use the server</entry>
	    </row>
	    <row>
	      <entry>unlock</entry>
	      <entry>foreign clients may use the server</entry>
	    </row>
	    <row>
	      <entry>standby, off</entry>
	      <entry>suspend sound output for other programs</entry>
	    </row>
	    <row>
	      <entry>resume, on</entry>
	      <entry>resume sound output</entry>
	    </row>
	    <row>
	      <entry>cache SAMPLE</entry>
	      <entry>cache sample from file SAMPLE in the server</entry>
	    </row>
	    <row>
	      <entry>getid NAME</entry>
	      <entry>retrieve a sample id from its name</entry>
	    </row>
	    <row>
	      <entry>free NAME</entry>
	      <entry>uncache a sample in the server by NAME</entry>
	    </row>
	    <row>
	      <entry>play NAME</entry>
	      <entry>play a cached sample once</entry>
	    </row>
	    <row>
	      <entry>loop NAME</entry>
	      <entry>play a cached sample in a loop</entry>
	    </row>
	    <row>
	      <entry>stop NAME</entry>
	      <entry>stop a looping sample at end of sample</entry>
	    </row>
	    <row>
	      <entry>serverinfo</entry>
	      <entry>get server info from server</entry>
	    </row>
	    <row>
	      <entry>allinfo</entry>
	      <entry>get player and sample info from server</entry>
	    </row>
	    <row>
	      <entry>panstream ID LEFT RIGHT</entry>
	      <entry>set left and right volume levels for a stream</entry>
	    </row>
	    <row>
	      <entry>pansample ID LEFT RIGHT</entry>
	      <entry>set default left and right volume levels for a sample</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>
	lock - only the "owner" of the daemon can play sounds.  the first key
	(obtained from &tilde;/.esd-auth) submitted to the daemon identifies
	the owner.
      </para>

      <para>
	unlock - anyone can play sounds through the daemon.
      </para>

      <para>
	standby - frees the audio device for use by other programs.  all
	sounds are ignored until the daemon is resumed.
      </para>

      <para>
	resume - brings daemon out of standby mode
      </para>

      <para>
	NOTE: more than one option may be listed on the command line
      </para>

    </sect1>

    <sect1 id="esdcat-esdmon-esdrec">
      <title>esdcat, esdmon, esdrec</title>

      <para>
	esdcat plays a raw audio stream through the daemon. esdmon outputs the
	mixed stream from the daemon. esdrec outputs from the sound device's
	current input.
      </para>

      <para>
	<command>esdcat</command> <option>[options] [file=stdin]</option>
      </para>
      <para>
	<command>esdmon</command> <option>[options] [file=stdout]</option>
      </para>
      <para>
	<command>esdrec</command> <option>[options] [file=stdout]</option>
      </para>

      <informaltable frame="all">
	<tgroup cols="2">
	  <thead>
	    <row><entry>option</entry><entry>purpose</entry></row></thead>
	  <tbody>
	    <row>
	      <entry>-s SERVER</entry>
	      <entry>communicate with esound running at SERVER</entry>
	    </row>
	    <row>
	      <entry>-b</entry>
	      <entry>read/write 8 bit sample data</entry>
	    </row>
	    <row>
	      <entry>-m</entry>
	      <entry>read/write mono data</entry>
	    </row>
	    <row>
	      <entry>-r RATE</entry>
	      <entry>use a sampling rate of RATE</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>
	NOTE: options for esdcat, esdmon, and esdrec default to 16 bit
	(signed), stereo, 44.1kHz
      </para>

    </sect1>