The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Video-Dumper-QuickTime-1.0005
River stage zero No dependents
++
/ Video::Dumper::QuickTime

NAME

Video::Dumper::QuickTime - Dump QuickTime movie file structure

VERSION

Version 1.0004

SYNOPSIS

    use Video::Dumper::QuickTime;
    my $file = QuickTime->new( -filename => $filename, -progress => \&showProgress );

    eval {$file->Dump ()};
    print "Error during processing: $@\n" if $@;

    my $dumpStr = $file->Result ();

DESCRIPTION

Video::Dumper::QuickTime parses a QuickTime movie file and generates a multi-line string describing the structure of the file.

The module is intended primarily as a diagnostic tool, although it would be possible to subclass Video::Dumper::QuickTime to extract various sections of a QuickTime file.

Methods

The methods fall into two groups - those required to use the method, and those useful for subclassing it.

The general use methods are presented first, followed by the accessor and utility methods of more use in subclassing.

General use methods

new

Create a new Video::Dumper::QuickTime instance.

    my $msi = QuickTime->new (-filename => $filename);
-filename: required

the QuickTime movie file to open

-noise: optional

Set error reporting level.

Currently recognised levels are:

0: no reporting
1: report unknown atoms
2: report non-decoded parameters and nested atoms
-progress: optional

reference to a callback sub to display parsing progress.

The progress sub is passed two parameters, the current position and the total work to be done. A typical callback sub would look like:

    sub showProgress {
        my ( $pos, $total ) = @_;
        ...
    }

Dump

Parse the movie file and return the result string.

IndentStr

Returns the string used for indenting in the result string.

Result

Result returns the result string generated by Dump. This can be usefull if you need to wrap the call the Dump in an eval, but still want any output that was generated in the case when an exception was thrown.

Subclassing utility methods

The following methods are used internally to manipulate and decode the data in the movie file. The present documentation if rather scanty, but will be improved over time (sooner if you ask for it!).

Generally the method name and parameter list are given. Parameters in [] are optional. Parameters followed by ... may be repeated as required.

read ($length[, $offset]);

read takes two parameters - a length (required) and a starting offset (optional).

read returns a string containing the number of bytes asked for starting from the current position or the given offset.

read will die "end\n"; if the end of the file is reached without reading any further bytes.

read will croak "short read ($len/$n)" if fewer than the requested bytes are available.

append ($str, ...)

Append a list of strings to the result string.

If the last character in the result string before the append was a new line character prepend the current indent string first.

findAtom ($attribute[, $regexp])

Search down the atom stack for an atom with a matching attribute and return the atom if found,or undef if no matching atom is found.

If the regular expression is provided the value of the attribute mustmatch against the regular expression. The regex should be generated using qr//.

See also "setParentAttrib" and "findAtomValue"

findAtomValue ($attribute[, $regexp])

Search down the atom stack for an atom with a matching attribute and return the attribute value if found, or '' if no matching atom is found.

If the regular expression is provided the value of the attribute mustmatch against the regular expression. The regex should be generated using qr//.

See also "setParentAttrib" and "findAtom"

setParentAttrib ($attrib, $value)

Set an attribute on the parent of the current atom.

getParentAttribs

Return a hash ref containing all the attribute => value pairs for the parent atom.

describeAtom ($pos)

Add a descriptive header to the result string for the atom at the given position.

If "dump_xxxx" and "name_xxxx" are available for the atom they are called to dump the atom's contents. If specific decoding is not available the atom is flagged as unknown and raw data for it is shown in the Dump result.

dump_xxxx ($pos, $length)

xxxx is the four char code for an atom. name_xxxx is called with the start and length of an atom of type xxxx and is expected to decode the atom's contents.

name_xxxx

xxxx is the four char code for an atom. name_xxxx returns a string to be shown as the name for the atom xxxx.

describeAtoms ($pos, $count)

Calls "describeAtom" for each of $count atoms starting at $pos.

describeAtomsIn ($pos, $end)

Calls "describeAtom" for each atom starting at $pos and before $end.

unwrapAtoms ($pos, $len)

Calls "describeAtomsIn" for each atom in the given range. Used to decode an atom that is purely a container for other atoms.

atomList ($pos, $len)

Dump a version and flags header followed by a list of atoms.

dumpBlock

    $self->dumpBlock ($pos + 8, $len - 8);

Dump a raw block of data. Generally used where the block can not be further decoded.

dumpText ($pos, $len)

Append an ASCII string starting at $pos for $len characters to the Dump result.

dumpUnicodeText

Append a utf16 string starting at $pos for $len bytes to the Dump result.

showBogus

"appends" the next four bytes as a packed version and flags field then skips eight bytes.

showPlayMode

"appends" a play mode string decoded from the next four byte flags field.

showGMode

"appends" a graphics mode line decoded from the next two byte field.

showRGB

"appends" three RGB color lines decoded from the next six bytes.

showGraphicsXferMode

"appends" a graphics transfer mode string decoded fromthe next two byte field.

showDate

"appends" a date string decoded from the next four bytes.

showMatrix ([$matrix])

Returns a matrix string formedby decoding the 36 byte contents of $matrix or the next 36 bytes (if $matrix is not provided).

showStr ($pos)

"appends" the length prefixed string starting at $pos.

showUnknown

"append" out the next 12 bytes as three unknown signed numbers.

get4Char

Return the next four bytes as a four char code.

Helper functions

The following functions are not object members and should be called as:

    my $result = Video::Dumper::QuickTime::functionName (...);

groupDigits ($number)

Inserts commas into a number to group the digits into groups of 3.

show ($string)

Attempt to make sense of the series of bytes in $string. Maybe useful for attempting to make sense of unknown atom data.

Conversion helper functions

The following non-member function unpack strings of bytes into another representation.

NToFixed ($str)

fToFloat ($str)

NToFrac

NToSigned

NToUnsigned

NToHex

NToBin

nToSigned

nToUnsigned

cToBool

Subclassing QuickTime

Because there are a huge number of atom types used by QuickTime (many of them undocumented) and the number of atom types used is increasing over time, Video::Dumper::QuickTime makes no attempt to decode all atom types. Instead it is easy to subclass the QuickTime class to add decoders for atoms of interest, or to change the way atoms that are currently handled by the QuickTime class are decoded for some particular application.

Two methods need to be provided for decoding of an atom. They are of the form:

    sub name_xxxx {
        my $self = shift;
        return 'The xxxx atom';
    }

    sub dump_xxxx {
        my $self = shift;
        my ( $pos, $len ) = @_;

        ...
    }

where the xxxx is a placeholder for the atom four char code.

A complete subclass package that handles one atom might look like:

    package Subclass;

    use QuickTime;
    use base qw(QuickTime);

    sub name_smhd {
        my $self = shift;
        return 'The smhd atom';
    }

    sub dump_smhd {
        my $self = shift;
        my ( $pos, $len ) = @_;
    }

There is of course no limit practical to the number of handlers added by a subclass.

REMARKS

This module recognises a subset of the atoms actually used by QuickTime files. Generally, well formed files should not present a problem because unrecognised atoms will be reported and skipped.

Subclassing Video::Dumper::QuickTime as shown above allows handlers to be added for unrecognised atoms. The author would appreciate any such handler code being forwarded for inclusion in future versions of the module.

BUGS

Please report any bugs or feature requests to bug-video-dumper-quicktime at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Video-Dumper-QuickTime. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

This module is supported by the author through CPAN. The following links may be of assistance:

ACKNOWLEDGEMENTS

The author appreciates the receipt of a patch containing bug fixes and additional atom decoders from Nick Wellnhofer.

AUTHOR

    Peter Jaquiery
    CPAN ID: GRANDPA
    grandpa@cpan.org

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.