ao/doc/overview.html

   1 <html>
   2
   3 <head>
   4 <title>libao - Documentation</title>
   5 <link rel=stylesheet href="style.css" type="text/css">
   6 </head>
   7
   8 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
   9 <table border=0 width=100%>
  10 <tr>
  11 <td><p class=tiny>libao documentation</p></td>
  12 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>libao Overview</h1>
  17
  18 <p>
  19 Libao is designed to make it easy to do simple audio output using
  20 various audio devices and libraries.  For this reason, complex audio
  21 control features are missing and will probably never be added.
  22 However, if you just want to be able to open whatever audio device is
  23 available and play sound, libao should be just fine.
  24
  25 <p>
  26 The libao API makes a distinction between drivers and devices.  A
  27 driver is a set of functions that allow audio to be played on a
  28 particular platform (i.e. Solaris, ESD, etc.).  A device is a
  29 particular output target that uses a driver.  In addition, libao
  30 distinguishes between <i>live</i> output drivers, which write audio to
  31 playback devices (sound cards, etc.), and <i>file</i> output drivers,
  32 which write audio to disk in a particular format.
  33
  34 <p>
  35 To use libao in your program, you need to follow these steps:
  36 <ul>
  37 <li>Include the &lt;ao/ao.h&gt; header into your program.
  38 <p>
  39
  40 <li>Call <a href="ao_initialize.html">ao_initialize()</a> to
  41 initialize the library.  This loads the plugins from disk, reads the
  42 libao <a href="config.html">configuration files</a>, and identifies an
  43 appropriate default output driver if none is specified in the
  44 configuration files.
  45 <p>
  46
  47 <li>Call <a
  48 href="ao_default_driver_id.html">ao_default_driver_id()</a> to get the
  49 ID number of the default output driver.  This may not be successful if
  50 no audio hardware is available, it is in use, or is not in the "standard"
  51 configuration.  If you want to specify a particular output driver, you
  52 may call <a href="ao_driver_id.html">ao_driver_id()</a> with a string
  53 corresponding to the short name of the device (i.e. "oss", "wav",
  54 etc.) instead.
  55 <p>
  56
  57 <li>If you are using the default device, no extra options are needed.
  58 However, if you wish to to pass special options to the driver, you
  59 will need to:
  60 <p>
  61
  62 <ul>
  63 <li>Create an option list pointer of type <tt>(<a
  64 href="ao_option.html">ao_option</a> *)</tt> and initialize it to
  65 <tt>NULL</tt>.
  66 <p>
  67
  68 <li>Through successive calls to <a
  69 href="ao_append_option.html">ao_append_option()</a>, add any
  70 driver-specific options you need.  Note that the options take the form
  71 of key/value pairs where supported keys are listed in the <a
  72 href="drivers.html">driver documentation</a>.
  73 </ul>
  74 <p>
  75
  76 <li>Call <a href="ao_open_live.html">ao_open_live()</a> and save the
  77 returned device pointer.  If you are using a file output driver, you
  78 will need to call <a href="ao_open_file.html">ao_open_file()</a>
  79 instead.
  80 <p>
  81
  82 <li>Call <a href="ao_play.html">ao_play()</a> to output each
  83 block of audio.
  84 <p>
  85
  86 <li>Call <a href="ao_close.html">ao_close()</a> to close the device.
  87 Note that this will automatically free the memory that was allocated
  88 for the device.  Do not attempt to free the device pointer yourself!
  89 <p>
  90
  91 <li>Call <a href="ao_shutdown.html">ao_shutdown()</a> to close the
  92 library.
  93 </ul>
  94
  95 <br><br>
  96 <hr noshade>
  97 <table border=0 width=100%>
  98 <tr valign=top>
  99 <td><p class=tiny>copyright &copy; 2001-2003 Stan Seibert</p></td>
 100 <td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:volsung@xiph.org">volsung@xiph.org</a></p></td>
 101 </tr><tr>
 102 <td><p class=tiny>libao documentation</p></td>
 103 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
 104 </tr>
 105 </table>
 106
 107 </body>
 108
 109 </html>