.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Decoder 3pm"
.TH Decoder 3pm "2010-12-24" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Ogg::Vorbis::Decoder \- An object\-oriented Ogg Vorbis to decoder
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  use Ogg::Vorbis::Decoder;
\&  my $decoder = Ogg::Vorbis::Decoder\->open("song.ogg");
\&  my $buffer;
\&  while ((my $len = $decoder\->read($buffer) > 0) {
\&    # do something with the PCM stream
\&  }
\&
\&  OR
\&
\&  open OGG, "song.ogg" or die $!;
\&  my $decoder = Ogg::Vorbis::Decoder\->open(\e*OGG);
\&
\&  OR
\&
\&  # can also be IO::Socket or any other IO::Handle subclass.
\&  my $fh = IO::Handle\->new("song.ogg");
\&  my $decoder = Ogg::Vorbis::Decoder\->open($fh);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides users with Decoder objects for Ogg Vorbis files.
One can read data in \s-1PCM\s0 format from the stream, seek by raw bytes,
pcm samples, or time, and gather decoding-specific information not
provided by Ogg::Vorbis::Header.  Currently, we provide no support for
the callback mechanism provided by the Vorbisfile \s-1API\s0; this may be
included in future releases.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS """open ($filename)"""
.el .SS "\f(CWopen ($filename)\fP"
.IX Subsection "open ($filename)"
Opens an Ogg Vorbis file for decoding. It opens a handle to the file or uses
an existing handle and initializes all of the internal vorbis decoding
structures.  Note that the object will maintain open file descriptors until
the object is collected by the garbage handler. Returns \f(CW\*(C`undef\*(C'\fR on failure.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.ie n .SS """read ($buffer, [$size, $word, $signed])"""
.el .SS "\f(CWread ($buffer, [$size, $word, $signed])\fP"
.IX Subsection "read ($buffer, [$size, $word, $signed])"
Reads \s-1PCM\s0 data from the Vorbis stream into \f(CW$buffer\fR.  Returns the
number of bytes read, 0 when it reaches the end of the stream, or a
value less than 0 on error.
.PP
The optional parameters include (with corresponding default values):
.PP
\&\f(CW\*(C`size = 4096\*(C'\fR
\&\f(CW\*(C`word = 2\*(C'\fR
\&\f(CW\*(C`signed = 1\*(C'\fR
.PP
Consult the Vorbisfile \s-1API \s0(http://www.xiph.org/ogg/vorbis/doc/vorbisfile/reference.html) 
for an explanation of the various values.
.ie n .SS """sysread ($buffer, [$size, $word, $signed])"""
.el .SS "\f(CWsysread ($buffer, [$size, $word, $signed])\fP"
.IX Subsection "sysread ($buffer, [$size, $word, $signed])"
An alias for \f(CW\*(C`read\*(C'\fR
.ie n .SS """raw_seek ($pos)"""
.el .SS "\f(CWraw_seek ($pos)\fP"
.IX Subsection "raw_seek ($pos)"
Seeks through the compressed bitstream to the offset specified by
\&\f(CW$pos\fR in raw bytes.  Returns 0 on success.
.ie n .SS """pcm_seek ($pos, [$page])"""
.el .SS "\f(CWpcm_seek ($pos, [$page])\fP"
.IX Subsection "pcm_seek ($pos, [$page])"
Seeks through the bitstream to the offset specified by \f(CW$pos\fR in pcm
samples.  The optional \f(CW$page\fR parameter is a boolean flag that, if
set to true, will cause the method to seek to the closest full page
preceding the specified location.  Returns 0 on success.
.ie n .SS """time_seek ($pos, [$page])"""
.el .SS "\f(CWtime_seek ($pos, [$page])\fP"
.IX Subsection "time_seek ($pos, [$page])"
Seeks through the bitstream to the offset specified by \f(CW$pos\fR in
seconds.  The optional \f(CW$page\fR parameter is a boolean flag that, if
set to true, will cause the method to seek to the closest full page
preceding the specified location.  Returns 0 on success.
.ie n .SS """current_bitstream ()"""
.el .SS "\f(CWcurrent_bitstream ()\fP"
.IX Subsection "current_bitstream ()"
Returns the current logical bitstream of the decoder.  This matches the
bitstream paramer optionally passed to \f(CW\*(C`read\*(C'\fR.  Useful for saving a
bitstream to jump to later or to pass to various information methods.
.ie n .SS """bitrate ([$stream])"""
.el .SS "\f(CWbitrate ([$stream])\fP"
.IX Subsection "bitrate ([$stream])"
Returns the average bitrate for the specified logical bitstream.  If
\&\f(CW$stream\fR is left out or set to \-1, the average bitrate for the entire
stream will be reported.
.ie n .SS """bitrate_instant ()"""
.el .SS "\f(CWbitrate_instant ()\fP"
.IX Subsection "bitrate_instant ()"
Returns the most recent bitrate read from the file.  Returns 0 if no
read has been performed or bitrate has not changed.
.ie n .SS """streams ()"""
.el .SS "\f(CWstreams ()\fP"
.IX Subsection "streams ()"
Returns the number of logical bitstreams in the file.
.ie n .SS """seekable ()"""
.el .SS "\f(CWseekable ()\fP"
.IX Subsection "seekable ()"
Returns non-zero value if file is seekable, 0 if not.
.ie n .SS """serialnumber ([$stream])"""
.el .SS "\f(CWserialnumber ([$stream])\fP"
.IX Subsection "serialnumber ([$stream])"
Returns the serial number of the specified logical bitstream, or that
of the current bitstream if \f(CW$stream\fR is left out or set to \-1.
.ie n .SS """raw_total ([$stream])"""
.el .SS "\f(CWraw_total ([$stream])\fP"
.IX Subsection "raw_total ([$stream])"
Returns the total number of bytes in the physical bitstream or the
specified logical bitstream.
.ie n .SS """pcm_total ([$stream])"""
.el .SS "\f(CWpcm_total ([$stream])\fP"
.IX Subsection "pcm_total ([$stream])"
Returns the total number of pcm samples in the physical bitstream or the
specified logical bitstream.
.ie n .SS """time_total ([$stream])"""
.el .SS "\f(CWtime_total ([$stream])\fP"
.IX Subsection "time_total ([$stream])"
Returns the total number of seconds in the physical bitstream or the
specified logical bitstream.
.ie n .SS """raw_tell ()"""
.el .SS "\f(CWraw_tell ()\fP"
.IX Subsection "raw_tell ()"
Returns the current offset in bytes.
.ie n .SS """pcm_tell ()"""
.el .SS "\f(CWpcm_tell ()\fP"
.IX Subsection "pcm_tell ()"
Returns the current offset in pcm samples.
.ie n .SS """time_tell ()"""
.el .SS "\f(CWtime_tell ()\fP"
.IX Subsection "time_tell ()"
Returns the current offset in seconds.
.SH "REQUIRES"
.IX Header "REQUIRES"
libogg, libvorbis, libogg-dev, libvorbis-dev
.SH "CURRENT AUTHOR"
.IX Header "CURRENT AUTHOR"
Dan Sully <daniel@cpan.org>
.SH "AUTHOR EMERITUS"
.IX Header "AUTHOR EMERITUS"
Dan Pemstein <dan@lcws.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2004\-2010, Dan Sully.  All Rights Reserved.
.PP
Copyright (c) 2003, Dan Pemstein.  All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at
your option) any later version.  A copy of this license is included
with this module (\s-1LICENSE.GPL\s0).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ogg::Vorbis::Header