Home | History | Annotate | Download | only in man3
      1 <!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
      2 <!--ArborText, Inc., 1988-1999, v.4002-->
      3 <!--ARC : LSARC 2001/201 GNOME 2.X on Solaris-->
      4 <!ENTITY cmd "libaudiofile">
      5 <!ENTITY % commonents SYSTEM "smancommon.ent">
      6 %commonents;
      7 <!ENTITY % booktitles SYSTEM "booktitles.ent">
      8 %booktitles;
      9 <!ENTITY suncopy "Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.">
     10 ]>
     11 <?Pub UDT _bookmark _target>
     12 <?Pub EntList brvbar bull cross dash diam diams frac12 frac13 frac14 hellip
     13  laquo lArr loz mdash nabla ndash para pound rArr raquo sect yen lt gt>
     14 <?Pub Inc>
     15 <refentry id="libaudiofile-3">
     16 <!-- %Z%%M% %I% %E% SMI; -->
     17 <refmeta><refentrytitle>&cmd;</refentrytitle><manvolnum>3</manvolnum>
     18 <refmiscinfo class="date">3 Apr2003</refmiscinfo>
     19 <refmiscinfo class="sectdesc">&man3;</refmiscinfo>
     20 <refmiscinfo class="software">&release;</refmiscinfo>
     21 <refmiscinfo class="arch">generic</refmiscinfo>
     22 <refmiscinfo class="copyright">&suncopy;</refmiscinfo>
     23 </refmeta>
     24 <indexterm><primary>&cmd;</primary></indexterm><indexterm><primary>
     25 audio file library</primary></indexterm><refnamediv id="libaudiofile-3-name">
     26 <refname>&cmd;</refname><refpurpose>audio file library</refpurpose></refnamediv>
     27 <refsynopsisdiv id="libaudiofile-3-synp"><title>&synp-tt;</title>
     28 <cmdsynopsis><command>#include &lt;audiofile.h></command>
     29 </cmdsynopsis>
     30 <cmdsynopsis><command>#include &lt;aupvlist.h></command>
     31 </cmdsynopsis>
     32 <cmdsynopsis><command>#include &lt;af_vfs.h></command>
     33 </cmdsynopsis></refsynopsisdiv>
     34 <refsect1 id="libaudiofile-3-desc"><title>&desc-tt;</title>
     35 <para>The audio file library provides a uniform programming interface to standard
     36 digital audio file formats. This library allows the processing of audio data
     37 to and from audio files of many common formats (currently AIFF, AIFF-C, WAVE,
     38 NeXT/Sun .snd/.au, and IRCAM).  The library also supports compression (currently
     39 G.711 mu-law, A-law, IMA, and MS ADPCM) as well as PCM formats of 	all flavors
     40 (signed and unsigned integer, floating point and double-precision floating
     41 point).</para>
     42 <para><filename>audiofile.h</filename> contains all of the public interfaces
     43 to the library. <filename>aupvlist.h</filename> contains the interfaces to
     44 the parameter value list data structures and routines. <filename>af_vfs.h
     45 </filename> should only be included if using audio file library through virtual
     46 file operations.</para>
     47 </refsect1>
     48 <refsect1 id="libaudiofile-3-exde"><title>&exde-tt;</title>
     49 <para>One premise of the audio file library is that the data presented to
     50 an application need not be in the same format as the data contained in the
     51 file.  Another, however, is that the capabilities of the file format are exposed
     52 to the application programmer should the programmer wish to take advantage
     53 of them.</para>
     54 <para>To read from a file containing audio data, you typically use the following
     55 sequence of function calls:</para>
     56 <screen>AFfilehandle afOpenFile (const char *filename, const char *mode, AFfilesetup setup);
     57 int afReadFrames (AFfilehandle, int track, void *buffer, int frameCount);
     58 int afCloseFile (AFfilehandle file);</screen>
     59 <para>To write to a file, you typically use a similar sequence of commands:
     60 </para>
     61 <screen>AFfilesetup afNewFileSetup (void);
     62 AFfilehandle afOpenFile (const char *filename, const char *mode, AFfilesetup setup);	
     63 int afWriteFrames (AFfilehandle, int track, const void *buffer,
     64 int frameCount);
     65 int afCloseFile (AFfilehandle file);</screen>
     66 <para>Data format transparency is achieved in the audio file library by providing
     67 the data in a virtual format. The virtual format consists of a virtual byte
     68 order and a virtual sample format. Virtual byte order is by default set to
     69 the host byte order and does not depend on the native byte order of the file
     70 format being used. Virtual sample format is by default in an uncompressed
     71 format.</para>
     72 <para>The current audio file library does not support the concept of a virtual
     73 sampling rate, but this may be supported in the future.</para>
     74 <para>At present, the audio file library supports only CCITT G.711 mu-law/A-law
     75 compression.</para>
     76 <para>An audio file is manipulated through the <literal>AFfilehandle</literal>
     77 opaque data type. Calls to the library are made with this file handle as an
     78 argument. When opening a file for writing, another opaque data structure called <literal>
     79 AFfilesetup</literal> is used. This structure is then passed to calls that
     80 set various file parameters at the time the file is created, such as its file
     81 type and data format. Such properties cannot be modified for an existing file.
     82 </para>
     83 <refsect2 id="libaudiofile-3-exde-func"><title>Functions</title>
     84 <para>The following functions are available through the library:</para>
     85 <variablelist><varlistentry><term>afNewFileSetup</term><listitem><para>Create
     86 a file setup structure.</para>
     87 </listitem></varlistentry>
     88 <varlistentry><term>afFreeFileSetup</term><listitem><para>Free a file setup
     89 structure.</para>
     90 </listitem></varlistentry>
     91 <varlistentry><term>afOpenFile</term><listitem><para>Create a file handle
     92 structure given a file name and optionally a file setup.</para>
     93 </listitem></varlistentry>
     94 <varlistentry><term>afCloseFile</term><listitem><para>Close an open audio
     95 file.</para>
     96 </listitem></varlistentry>
     97 <varlistentry><term>afSyncFile</term><listitem><para>Update an audio file
     98 that has been opened for writing.</para>
     99 </listitem></varlistentry>
    100 <varlistentry><term>afSetVirtual{ByteOrder,Channels,PCMMapping,SampleFormat}
    101 </term><listitem><para>Set virtual format for audio data within a specified
    102 track.</para>
    103 </listitem></varlistentry>
    104 <varlistentry><term>afInit{ByteOrder,Channels,Rate,SampleFormat}</term><listitem>
    105 <para>Set parameters of an <literal>AFfilesetup</literal> structure which
    106 will be used to open an audio file for writing.</para>
    107 </listitem></varlistentry>
    108 <varlistentry><term>afQuery</term><listitem><para>Query regarding the capabilities
    109 of the audio file library.</para>
    110 </listitem></varlistentry>
    111 <varlistentry><term>afQueryLong</term><listitem><para>Query whether the data
    112 is of type <literal>long</literal>.</para>
    113 </listitem></varlistentry>
    114 <varlistentry><term>afQueryPointer</term><listitem><para>Query whether the
    115 data is of type <literal>pointer</literal>.</para>
    116 </listitem></varlistentry>
    117 <varlistentry><term>afQueryDouble</term><listitem><para>Query whether the
    118 data is of type <literal>double</literal>.</para>
    119 </listitem></varlistentry>
    120 <varlistentry><term>afSetLoop*</term><listitem><para>The group of functions
    121 that set loop parameters.</para>
    122 </listitem></varlistentry>
    123 <varlistentry><term>afGetLoop*</term><listitem><para>The group of functions
    124 that get loop parameters.</para>
    125 </listitem></varlistentry>
    126 <varlistentry><term>afSetMark*</term><listitem><para>The group of functions
    127 that set mark parameters.</para>
    128 </listitem></varlistentry>
    129 <varlistentry><term>afGetMark*</term><listitem><para>The group of functions
    130 that get mark parameters.</para>
    131 </listitem></varlistentry>
    132 <varlistentry><term>afSetInst*</term><listitem><para>The group of functions
    133 that set instrument parameters.</para>
    134 </listitem></varlistentry>
    135 <varlistentry><term>afGetInst*</term><listitem><para>The group of functions
    136 that get instrument parameters.</para>
    137 </listitem></varlistentry>
    138 <varlistentry><term>afGetAESChannelData</term><listitem><para>Get AES channel
    139 data for a given audio file.</para>
    140 </listitem></varlistentry>
    141 <varlistentry><term>afSetAESChannelData</term><listitem><para>Set AES channel
    142 data for a given audio file.</para>
    143 </listitem></varlistentry>
    144 <varlistentry><term>afInitAESChannelData</term><listitem><para>Specify that
    145 storage space is to be allocated for AES channel status data in a given audio
    146 file.</para>
    147 </listitem></varlistentry>
    148 <varlistentry><term>afInitAESChannelDataTo</term><listitem><para>Specify whether
    149 storage space is to be allocated for AES channel status data in a given audio
    150 file.</para>
    151 </listitem></varlistentry>
    152 </variablelist></refsect2>
    153 </refsect1>
    154 <refsect1 id="libaudiofile-3-file"><title>&file-tt;</title>
    155 <para>The following files are used by this application:</para>
    156 <variablelist termlength="wide"><varlistentry><term><filename>/usr/&cmd;.so
    157 </filename></term><listitem><para>Audio file shared library</para>
    158 </listitem></varlistentry>
    159 <varlistentry><term><filename>/usr/include/audiofile.h</filename></term><listitem>
    160 <para>Public interfaces C header file</para>
    161 </listitem></varlistentry>
    162 <varlistentry><term><filename>/usr/include/aupvlist.h</filename></term><listitem>
    163 <para>Parameter value list C header file</para>
    164 </listitem></varlistentry>
    165 <varlistentry><term><filename>/usr/include/af_vfs.h</filename></term><listitem>
    166 <para>Virtual File System C header file</para>
    167 </listitem></varlistentry>
    168 </variablelist></refsect1>
    169 <refsect1 id="libaudiofile-3-attr"><title>&attr-tt;</title>
    170 <para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
    171 <refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
    172 for descriptions of the following attributes:</para>
    173 <informaltable frame="all">
    174 <tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
    175 <colspec colname="COLSPEC1" colwidth="1*">
    176 <thead>
    177 <row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
    178 valign="middle">ATTRIBUTE VALUE</entry></row>
    179 </thead>
    180 <tbody>
    181 <row><entry><para>Availability</para></entry><entry><para>SUNWgnome-audio</para></entry></row>
    182 <row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry colname="COLSPEC1"><para>Volatile</para></entry></row>
    183 </tbody>
    184 </tgroup>
    185 </informaltable>
    186 </refsect1>
    187 <refsect1 id="libaudiofile-3-also"><title>&also-tt;</title>
    188 <!--Reference to another man page-->
    189 <!--Reference to a Help manual-->
    190 <!--Reference to a book.-->
    191 <para>
    192 <citerefentry><refentrytitle>audiofile-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
    193 <citerefentry><refentrytitle>libesd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    194 <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    195 </para>
    196 </refsect1>
    197 <refsect1 id="libaudiofile-3-note"><title>&note-tt;</title>
    198 <para>Written by Ghee Teo, Sun Microsystems Inc., 2003. This library is provided
    199 as an Open Source project by Silicon Graphics.</para>
    200 </refsect1>
    201 </refentry>
    202