archived-doc-en/language/wrappers/audio.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="wrappers.audio" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
 <refnamediv>
  <refname>ogg://</refname>
  <refpurpose>Audio streams</refpurpose>
 </refnamediv>

 <refsect1 role="description"><!-- {{{ -->
  &reftitle.description;
  <para>
   Files opened for reading via the <filename>ogg://</filename> wrapper
   are treated as compressed audio encoded using the <literal>OGG/Vorbis</literal> codec.
   Similarly, files opened for writing or appending via the
   <filename>ogg://</filename> wrapper are written as compressed audio data.
   <function>stream_get_meta_data</function>, when used on an <literal>OGG/Vorbis</literal>
   file opened for reading will return various details about the stream
   including the <parameter>vendor</parameter> tag, any included
   <parameter>comments</parameter>, the number of
   <parameter>channels</parameter>, the sampling <parameter>rate</parameter>,
   and the encoding rate range described by:
   <parameter>bitrate_lower</parameter>, <parameter>bitrate_upper</parameter>,
   <parameter>bitrate_nominal</parameter>, and <parameter>bitrate_window</parameter>.
  </para>

  <simpara><filename>ogg://</filename> (PECL)</simpara>
  <note>
   <title>This wrapper is not enabled by default</title>
   <simpara>
    In order to use the <filename>ogg://</filename> wrapper,
    the
    <link xlink:href="&url.pecl.package;oggvorbis">OGG/Vorbis</link>
    extension available from &link.pecl; must be installed.
   </simpara>
  </note>
 </refsect1><!-- }}} -->

 <refsect1 role="usage"> <!-- {{{ -->
  &reftitle.usage;
  <itemizedlist>
   <listitem><simpara><filename>ogg://soundfile.ogg</filename></simpara></listitem>
   <listitem><simpara><filename>ogg:///path/to/soundfile.ogg</filename></simpara></listitem>
   <listitem><simpara><filename>ogg://http://www.example.com/path/to/soundstream.ogg</filename></simpara></listitem>
  </itemizedlist>
 </refsect1> <!-- }}} -->

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <para>
   <table>
    <title>Wrapper Summary</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Attribute</entry>
       <entry>Supported</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>No</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <!-- FIXME: This should not be here! context.audio... -->
  <para>
   <table>
    <title>Context options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>Usage</entry>
       <entry>Default</entry>
       <entry>Mode</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>pcm_mode</literal></entry>
       <entry>
        PCM encoding to apply while reading, one of:
        <constant>OGGVORBIS_PCM_U8</constant>, <constant>OGGVORBIS_PCM_S8</constant>,
        <constant>OGGVORBIS_PCM_U16_BE</constant>, <constant>OGGVORBIS_PCM_S16_BE</constant>,
        <constant>OGGVORBIS_PCM_U16_LE</constant>, and <constant>OGGVORBIS_PCM_S16_LE</constant>.
        (8 vs 16 bit, signed or unsigned, big or little <literal>endian</literal>)
       </entry>
       <entry>OGGVORBIS_PCM_S16_LE</entry>
       <entry>Read</entry>
      </row>
      <row>
       <entry><literal>rate</literal></entry>
       <entry>
        Sampling rate of input data, expressed in Hz
       </entry>
       <entry>44100</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>bitrate</literal></entry>
       <entry>
        When given as an integer, the fixed bitrate at which to encode. (16000 to 131072)
        When given as a float, the variable bitrate quality to use. (-1.0 to 1.0)
       </entry>
       <entry>128000</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>channels</literal></entry>
       <entry>
        The number of audio channels to encode, typically 1 (Mono), or 2 (Stereo).
        May range as high as 16.
       </entry>
       <entry>2</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>comments</literal></entry>
       <entry>
        An array of string values to encode into the track header.
       </entry>
       <entry/>
       <entry>Write/Append</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1> <!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
 </refsect1><!-- }}} -->

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->