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.