Author image Benjamin R. Ginter


MPEG::LibMPEG3 - Perl interface to libmpeg3 module


  use strict;
  use MPEG::LibMPEG3;

  my $mpeg = MPEG::LibMPEG3->new( $filename );

  $mpeg->set_cpus(1);   ## I only have 1 cpu but you can put whatever
  $mpeg->set_mmx(1);    ## but it has mmx instructions

  printf "Audio Streams: %d\n", $mpeg->astreams;
  for ( 0..$mpeg->astreams() - 1 ) {
      print  "  Stream #$_\n";
      printf "\tachans  : %d\n", $mpeg->achans( $_ );
      printf "\tarate   : %d\n", $mpeg->arate( $_ );
      printf "\taformat : %s\n", $mpeg->acodec( $_ );
      printf "\tduration: %0.2f\n", $mpeg->aduration( $_ );
      print "\n";

  printf "Video Streams: %d\n", $mpeg->vstreams;
  for ( 0..$mpeg->vstreams() - 1 ) {
      print  "  Stream #$_\n";
      printf "\tWidth        : %d\n"   , $mpeg->width( $_ );
      printf "\tHeight       : %d\n"   , $mpeg->height( $_ );
      printf "\tAspect Ratio : %d\n"   , $mpeg->aspect( $_ );
      printf "\tFrame Rate   : %0.2f\n", $mpeg->fps( $_ );
      printf "\tTotal Frames : %d\n"   , $mpeg->vframes( $_ );
      printf "\tColor Model  : %d\n"   , $mpeg->colormodel( $_ );
      printf "\tDuration     : %0.2f\n", $mpeg->vduration( $_ );

      print "Dumping frames as YUV\n";
      for ( my $i = 0; $i < $mpeg->vframes; $i++ ) {
          my $output_rows = $mpeg->get_yuv;
          my $frame_yuv   = sprintf( "%s-%05d.yuv", $file, $i );
          # printf "Opening $frame_yuv\n";
          print '.';
          open OUT, "> $frame_yuv" or 
              die "Can't open file $frame_yuv for output: $!\n";

          print OUT $output_rows;
          close OUT;

          if ( $i > 1 && $i % $mpeg->fps($_) == 0 ) {
              printf " %0.0f sec/s\n", $i/$mpeg->fps($_);
      printf " %0.2f sec/s\n", $mpeg->duration;  


The Moving Picture Experts Group (MPEG) is a working group in charge of the development of standards for coded representation of digital audio and video.

MPEG audio and video clips are ubiquitous but using Perl to programmatically collect information about these bitstreams has to date been a kludge at best.

This module uses the libmpeg3 library to parse and extract information from the bitstraems. It supports the following types of files:

        MPEG-1 Layer II Audio
        MPEG-1 Layer III Audio
        MPEG-2 Layer III Audio
        MPEG-1 program streams
        MPEG-2 program streams
        MPEG-2 transport streams
        AC3 Audio
        MPEG-2 Video
        MPEG-1 Video
        IFO files
        VOB files


While MPEG::LibMPEG3 uses libmpeg3, the interface has been simplified for your programming (and viewing) pleasure.

new( [ [ filename => ] FILE ] )

Constructor. Takes an optional filename argument and returns an MPEG::LibMPEG3 object.

probe( [( FILE )] )

If a filename wasn't provided to the constructor, it must be passed to probe. In this way an MPEG::LibMPEG3 object can be instantiated and probe() can be called multiple times with different filenames.

This method calls the libmpeg3 mpeg3_open() or mpeg3_open_copy() function as appropriate. Returns an mpeg3_t structure on success.

set_cpus( n )

Optional. Sets the number of threads to spawn while decoding a bitstream. If you have multiple CPUs, you may benefit by increasing this. By default, a thread is created for each video and audio stream.

set_mmx( n )

If your CPU has MMX instructions, passing a 1 to this method will enable MMX decoding which may provide faster decoding. I have not profiled this though I can not think of a reason it wouldn't work.



Returns the number of audio streams.


Returns the number of video streams.


Returns true if the MPEG has video.


Returns true if the MPEG has audio.


Closes the currently opened MPEG file.

The following methods take an optional STREAM argument. If not provided, defaults to the first stream (0).

achans( [ STREAM ] )

Returns the number of channels in an audio stream.

arate( [ STREAM ] )

Returns the sampling rate (e.g. 22050, 44100, 48000 )

acodec( [ STREAM ] )

Returns the audio codec used to encode the stream. This is usually either MPEG, AC3, or ''.

aduration( [ STREAM ] )

Returns the duration of the audio stream in seconds.

width( [ STREAM ] )

Returns the width of the video stream in pixels.

height( [ STREAM ] )

Returns the height of the video stream in pixels.

aspect( [ STREAM ] )

Returns the aspect ratio of the video stream. I've only ever seen this return 0.

fps( [ STREAM ] )

Returns the number of frames per second as a floating point number.

vframes( [ STREAM ] )

Returns the number of frames in the video stream.

colormodel( [ STREAM ] )

Returns the color model of the video stream. This is either 12 for YUV420 or 13 for YUV422. Never have seen a YUV422.

vduration( [ STREAM ] )

Returns the duration of the video stream in seconds.

duration( [ STREAM ] )

Returns the video duration if it exists, otherwise the audio duration.


The follow methods provide absolute or percentage seeking. Note that once you perform one type of seeking, libmpeg3 doesn't let you change to the other method.

seek_percentage( n.nn )

Seeks to a percentage of the file. E.g. 0.50 == 50% of the file.

set_frame( FRAME, STREAM )

Seeks to a particular FRAME number of STREAM.


And the method everyone has been waiting for... *drumroll*


Returns a YUV coded frame. This is returned as a single scalar though you can break out the individual planes of the image if you know how a YUV file is composed.

  Y plane = width x height
  U plane = width x height / 4
  V plane = width x height / 4




Benjamin R. Ginter, <>


Copyright (c) 2002 Benjamin R. Ginter


Free for non-commercial use.






2 POD Errors

The following errors were encountered while parsing the POD:

Around line 234:

You forgot a '=back' before '=head2'

Around line 236:

'=item' outside of any '=over'