NAME

Ogg::Vorbis::LibVorbis - XS Interface for calling Vorbis Audio Codec functions in Perl.

DESCRIPTION

Ogg::Theora::LibVorbis is a glue between vorbis/codec.h, vorbis/vorbisenc.h and vorbis/vorbisfile.h Please read the XS code to understand how the gluing happens.

SYNOPSIS ENCODE

Encoding .wav format to Vorbis Audio format http://svn.xiph.org/trunk/vorbis/examples/encoder_example.c

##############################################################################################################################################################
# (1) Initialize a vorbis_info structure by calling vorbis_info_init and then functions from libvorbisenc on it.			   		       #
# (2) Initialize a vorbis_dsp_state for encoding based on the parameters in the vorbis_info by using vorbis_analysis_init.				       #
# (3) Initialize a vorbis_comment structure using vorbis_comment_init, populate it with any comments you wish to store 				       #
#     in the stream, and call vorbis_analysis_headerout to get the three Vorbis stream header packets. Output the packets.				       #
# (4) Initialize a vorbis_block structure using vorbis_block_init.											       #
# (5) While there is more audio to encode:														       #
#       (5.a) Submit a chunk of audio data using vorbis_analysis_buffer and vorbis_analysis_wrote.							       #
#       (5.b) Obtain all available blocks using vorbis_analysis_blockout in a loop. For each block obtained:						       #
#           (5.b.1) Encode the block into a packet (or prepare it for bitrate management) using vorbis_analysis.					       #
#           (5.b.2) If you are using bitrate management, submit the block using vorbis_bitrate_addblock and obtain packets using vorbis_bitrate_flushpacket. #
#           (5.b.3) Output any obtained packets.													       #
# (6) Submit an empty buffer to indicate the end of input; this will result in an end-of-stream packet after all encoding steps are done to it.	       #
# (7) Destroy the structures using the appropriate vorbis_*_clear routines.										       #
##############################################################################################################################################################


use Ogg::LibOgg ':all';
use Ogg::Vorbis::LibVorbis;
use Audio::Wav;

## Wav Audio File Info
my $wav = new Audio::Wav; 
my $read = $wav->read("t/test.wav"); 
my $details = $read->details();
my $channels = $details->{channels}; # 2
my $rate = $details->{sample_rate};  # 22050
my $length = $read->length_samples(); # 48066

## Ogg Pages
my $op_h      = make_ogg_packet();
my $op_hcomm = make_ogg_packet();
my $op_hcode = make_ogg_packet();
my $op_audio   = make_ogg_packet();
my $os   = make_ogg_stream_state();
my $og = make_ogg_page();

my $vi = Ogg::Vorbis::LibVorbis::make_vorbis_info(); # vorbis_info
my $vc = Ogg::Vorbis::LibVorbis::make_vorbis_comment(); # vorbis_comment
my $vb = Ogg::Vorbis::LibVorbis::make_vorbis_block(); # vorbis_block
Ogg::Vorbis::LibVorbis::vorbis_info_init($vi);
my $v = Ogg::Vorbis::LibVorbis::make_vorbis_dsp_state(); # vorbis_dsp_state
my $ret = Ogg::Vorbis::LibVorbis::vorbis_encode_init_vbr($vi, $channels, $rate, 1.0);
$ret = Ogg::Vorbis::LibVorbis::vorbis_analysis_init($v, $vi);
$ret = Ogg::Vorbis::LibVorbis::vorbis_encode_setup_init($vi);
Ogg::Vorbis::LibVorbis::vorbis_comment_init($vc);
$ret = Ogg::Vorbis::LibVorbis::vorbis_block_init($v, $vb);
$ret = Ogg::Vorbis::LibVorbis::vorbis_analysis_headerout($v, $vc, $op_h, $op_hcomm, $op_hcode);

$ret = ogg_stream_init($os, int(rand(1000)));
$ret = ogg_stream_packetin($os, $op_h);
$ret = ogg_stream_packetin($os, $op_hcomm);
$ret = ogg_stream_packetin($os, $op_hcode);

my $filename = "t/vorbis_encode.ogg";
open OUT, ">", "$filename" or die "can't open $filename for writing [$!]";
binmode OUT;

save_page();
1 while (add_frames());

close OUT;

sub save_page {
  ## forms packets to pages 
  if (ogg_stream_pageout($os, $og) != 0) {
    my $h_page = get_ogg_page($og);
    ## writes the header and body 
    print OUT $h_page->{header};
    print OUT $h_page->{body};
  } else {
    # pass, we don't have to worry about insufficient data
  }
}

sub add_frames {
  my $data = $read->read_raw_samples($channels);
  my $no = $read->position_samples();  

  # vorbis_encode_wav_frames(v, vals, channels, buffer)
  my $status = Ogg::Vorbis::LibVorbis::vorbis_encode_wav_frames($v, 1024, $channels, $data);

  # while (vorbis_analysis_blockout(self.vd, self.vb) == 1)
  # 	vorbis_analysis(self.vb,self.audio_pkt)
  # 	ogg_stream_packetin(self.to,self.audio_pkt)
  while (($status = Ogg::Vorbis::LibVorbis::vorbis_analysis_blockout($v, $vb)) == 1) {
    $status = Ogg::Vorbis::LibVorbis::vorbis_analysis($vb, $op_audio);
    if ($status < 0) {
      diag ("Crap Out, some error [$status]");
      exit -1;
    }
    ogg_stream_packetin($os, $op_audio);
  }

  save_page();

  return $length == $no ? 0 : 1
}

SYNOPSIS DECODE (vorbisfile)

Decoding Vorbis file using vorbisfile http://xiph.org/vorbis/doc/vorbisfile/example.html

use Ogg::Vorbis::LibVorbis;
use Ogg::LibOgg ':all';

my $vf = Ogg::Vorbis::LibVorbis::make_oggvorbis_file();  # OggVorbis_File
my $vi = Ogg::Vorbis::LibVorbis::make_vorbis_info();     # vorbis_info

my $filename = "t/test.ogg";
open IN, $filename or die "can't open [$filename] : $!"; 

$status = Ogg::Vorbis::LibVorbis::ov_open_callbacks(*IN, $vf, 0, 0);  # $status == 0
my $pcmout = 0;		# i know setting to -1 is of no use, but to avoid warning (_xs_ says NO_INIT)
my $bit = 0;
my $ret = -1;
open OUT, "> output.pcm" or die "can't open output.pcm\n";
binmode OUT;
my $total = 0;
while ($ret != 0) {
  $ret = Ogg::Vorbis::LibVorbis::ov_read($vf, $pcmout, 4096, 0, 2, 1, $bit);
  print OUT $pcmout;
}
close OUT;

Ogg::Vorbis::LibVorbis::ov_clear($vf);

EXPORT

Only constants are exported by DEFAULT

use Ogg::Theora::LibVorbis ':all'; # to export everything to current namespace

Exportable constants

INITSET
NOTOPEN
OPENED
OV_EBADHEADER
OV_EBADLINK
OV_EBADPACKET
OV_ECTL_IBLOCK_GET
OV_ECTL_IBLOCK_SET
OV_ECTL_LOWPASS_GET
OV_ECTL_LOWPASS_SET
OV_ECTL_RATEMANAGE2_GET
OV_ECTL_RATEMANAGE2_SET
OV_ECTL_RATEMANAGE_AVG
OV_ECTL_RATEMANAGE_GET
OV_ECTL_RATEMANAGE_HARD
OV_ECTL_RATEMANAGE_SET
OV_EFAULT
OV_EIMPL
OV_EINVAL
OV_ENOSEEK
OV_ENOTAUDIO
OV_ENOTVORBIS
OV_EOF
OV_EREAD
OV_EVERSION
OV_FALSE
OV_HOLE
PARTOPEN
STREAMSET

Functions (malloc)

http://www.xiph.org/vorbis/doc/vorbisfile/datastructures.html

make_oggvorbis_file

Creates a memory allocation for OggVorbis_File datastructure

-Input: Void

-Output: Memory Pointer

make_vorbis_info

Creates a memory allocation for vorbis_info

-Input: void

-Output: Memory Pointer to vorbis_info

make_vorbis_comment

Creates a memory allocation for vorbis_comment

-Input: void

-Output: Memory Pointer to vorbis_comment

make_vorbis_block

Creates a memory allocation for vorbis_block

-Input: void

-Output: Memory Pointer to vorbis_block

make_vorbis_dsp_state

Creates a memory allocation for vorbis_dsp_state

-Input: void

-Output: Memory Pointer to vorbis_dsp_state

Functions (vorbisfile)

http://www.xiph.org/vorbis/doc/vorbisfile/reference.html

ov_open

ov_open is one of three initialization functions used to initialize an OggVorbis_File structure and prepare a bitstream for playback. http://www.xiph.org/vorbis/doc/vorbisfile/ov_open.html

-Input: FILE *, File pointer to an already opened file or pipe, OggVorbis_File, A pointer to the OggVorbis_File structure, char *, Typically set to NULL, int, Typically set to 0.

-Output: 0 indicates succes, less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream is not Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_fopen

This is the simplest function used to open and initialize an OggVorbis_File structure. http://www.xiph.org/vorbis/doc/vorbisfile/ov_fopen.html

-Input: char *, (null terminated string containing a file path suitable for passing to fopen()) OggVorbis_File

-Output: 0 indicates success less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_open_callbacks

an alternative function used to open and initialize an OggVorbis_File structure when using a data source other than a file, when its necessary to modify default file access behavior. http://www.xiph.org/vorbis/doc/vorbisfile/ov_open.html

Please read the official ov_open_callbacks doc before you use this. The perl version uses a different approach and uses vorbis_callbacks with custom functions to read, seek tell and close.

this module can accept file name, network socket or a file pointer.

-Input: void *, (data source) OggVorbis_File, A pointer to the OggVorbis_File structure, char *, Typically set to NULL, int, Typically set to 0.

-Output: 0 indicates succes, less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream is not Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_test

This partially opens a vorbis file to test for Vorbis-ness. http://www.xiph.org/vorbis/doc/vorbisfile/ov_test.html

-Input: FILE *, File pointer to an already opened file or pipe, OggVorbis_File, A pointer to the OggVorbis_File structure, char *, Typically set to NULL, int, Typically set to 0.

-Output: 0 indicates succes, less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream is not Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_test_open

Finish opening a file partially opened with ov_test() or ov_test_callbacks(). http://www.xiph.org/vorbis/doc/vorbisfile/ov_test_open.html

-Input: OggVorbis_File

-Output: 0 indicates succes, less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream is not Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_test_callbacks

an alternative function used to open and test an OggVorbis_File structure when using a data source other than a file, when its necessary to modify default file access behavior. http://www.xiph.org/vorbis/doc/vorbisfile/ov_test_callbacks.html

Please read the official ov_test_callbacks doc before you use this. The perl version uses a different approach and uses vorbis_callbacks with custom functions to read, seek tell and close.

this module can accept file name, network socket or a file pointer.

-Input: void *, (data source) OggVorbis_File, A pointer to the OggVorbis_File structure, char *, Typically set to NULL, int, Typically set to 0.

-Output: 0 indicates succes, less than zero for failure:

OV_EREAD - A read from media returned an error.
OV_ENOTVORBIS - Bitstream is not Vorbis data.
OV_EVERSION - Vorbis version mismatch.
OV_EBADHEADER - Invalid Vorbis bitstream header.
OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

ov_clear

ov_clear() to clear the decoder's buffers and close the file http://www.xiph.org/vorbis/doc/vorbisfile/ov_clear.html

-Input: OggVorbis_File

-Output: 0 for success

ov_seekable

This indicates whether or not the bitstream is seekable. http://www.xiph.org/vorbis/doc/vorbisfile/ov_seekable.html

-Input: OggVorbis_File

-Output: 0 indicates that the file is not seekable. nonzero indicates that the file is seekable.

ov_time_total

Returns the total time in seconds of the physical bitstream or a specified logical bitstream. http://www.xiph.org/vorbis/doc/vorbisfile/ov_time_total.html

-Input: OggVorbis_File, int (link to the desired logical bitstream)

-Output: OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable. n total length in seconds of content if i=-1. n length in seconds of logical bitstream if i=0 to n.