NAME

Audio::M4P::QuickTime -- Perl M4P/MP4/M4a audio / video tools

DESCRIPTION

Perl manipulation of Quicktime Audio files, including protected audio M4P files. Allows extraction and modification of meta information in Apple QuickTime AAC/m4a music files.

About QuickTime File Structure and Atoms

M4P is a QuickTime protected audio file format. It is composed of a linear stream of bytes which are segmented into units called atoms. Some atoms may be containers for other atoms. iTunes Music Store M4P music files are Quicktime audio files which are encrypted using a combination of information in the file's drms atom and information which is commonly stored on the computer or audio player.

SYNOPSIS

use Audio::M4P::QuickTime;

my $mp4file = "file.m4p";

my $qt = new Audio::M4P::QuickTime(file => $mp4file);

my $tags = $qt->GetMetaInfo;

print "Artist is $tags->{ARTIST}\n" if $tags->{ARTIST};

METHODS

Object Methods

new

my $qt = Audio::M4P::QuickTime->new;

$qt = new Audio::M4P::QuickTime(
  DEBUG => 2, 
  DEBUGDUMPFILE => 'quicktime_treedump.html'
);

$qt = new Audio::M4P::QuickTime(file => 'qt_audio_file.m4p');

Create a new Audio::M4P::QuickTime object. DEBUG => 1 as argument causes parse and other information to be printed to stdout during processing. DEBUG => 2, DEBUGDUMPFILE => "file" causes an HTML tree representation of the QuickTime file to be emitted to the file given as value to the argument pair. file => "filename.m4p" causes the named QuickTime file to be read and parsed during object initialization.

ReadFile

$qt->ReadFile("filename.m4a");

Read the named file into the QuickTime object buffer.

ParseBuffer

$qt->ParseBuffer;

Parse the file that has been read as a QuickTime stream.

WriteFile

$qt->WriteFile("ouput.m4p");

Write the (possibly modified) file back to the output file argument.

GetMetaInfo

my $hashref = $qt->GetMetaInfo(1);
while(my($tag, $value) = each %{$hashref}) { 
   print "$tag => $value\n";
}

Returns a hash reference to meta tag information. Attempts to be compatible with tag information formats in MP3::Info and MP4::Info. Potential tags are AAID, ALBUM, ARTIST, COMMENT, COM, CPIL, CPRT, YEAR, DISK, GENRE, GRP, NAM, RTNG, TMPO, TOO, TRKN, and WRT. Note that, due to preservation of compatibility with MP3::Info by returning tag info as a hash reference, duplicate entries of the same tag name, such as multiple comment fields, will not be returned in the hash reference. An optional second argument, if 1 or true, should convert some binary fields to text in the tags, for instance my $hashref = $qt->GetMetaInfo(1);

GetMP4Info

my $hashref = $qt->GetMP4Info;
while(my($tag, $value) = each %{$hashref}) { 
   print "$tag => $value\n";
}

Returns a hash reference to MP3 tag audio information. Attempts to be compatible with tag information formats in MP3::Info and MP4::Info. Potential tags are LAYER (1), VERSION (4), SIZE, SECONDS, SS, MM, and BITRATE.

SetMetaInfo

my $comment = "After paying for this music file, I have fair use rights to change it.";

$qt->SetMetaInfo(COMMENT => $comment);
$qt->SetMetaInfo(GENRE => "Bebop", 1, 'day');

Set a meta information field. The third argument, if given and true, indicates that the program should replace all instances of meta data of this type with the new entry, rather than adding the tag to the existing meta data. The fourth argument, if given and true, indicated a tag value before which the new tag is to be placed in the file. The fifth argument indicates the values are in text form, ie for meta type 'trkn', value is something like 'Track 5 of 11'.

iTMS_MetaInfo

my $hashref = $qt->iTMS_MetaInfo;

$hashref->{comments} = "A new comment";
$qt->iTMS_MetaInfo($hashref);

Get or set a meta information field via a hash reference to an Apple iTMS type dict data structure. Possible fields are copyright, comments, songName, genre, playlistArtistName, genreID, composerName, playlistName, year, trackNumber, trackCount, discNumber, discCount, and artworkURL. iTMS meta data entries may not be compatible with MP3::Info type meta data. An optional second argument, if true, prevents the method from replacing old meta information, as in $qt->iTMS_MetaInfo($hashref, 1);

Note that although this method of manipulating M4P data tags is closest to the way iTMS and iTunes do metadata, it may be less intuitive for most audio tag programmers than the MP3::Tag and Audio::TagLib compatible methods below.

GetCoverArt

my $artwork = $qt->GetCoverArt();
foreach my $pic (@{$artwork}) { 
    # do stuff with art
}

Returns a reference to an array of cover artwork. Note: the artwork routines were suggested and largely contributed by pucklock. (Thanks!)

DeleteAllCoverArt

$qt->DeleteAllCoverArt;

Delete all cover art from the file. This removes all data from the covr atom, if any. Returns the number of cover data atoms deleted.

AddCoverArt

$qt->AddCoverArt( $jpeg_art, 13 );  # $jpeg_art is an iTunes compatible jpeg 
$qt->AddCoverArt( $jpeg_art );      # the same as above, defaults to type 13
$qt->AddCoverArt( $png_art, 14 );   # PNG graphics are data type 14

Add cover artwork to the file. Creates a new covr atom if needed. Returns 1 if successful, otherwise null.

The method adds a single album cover by either adding one covr atom or by adding one cover's data to an existing covr atom. Takes a argument which should be a compatible graphic format binary, but does NO checks for compatibility with iTunes' cover art display. The type should be 13 for jpeg, 14 for png graphics format, but defaults to 13.

MP3::Tag and Audio::TagLib Compatible Functions

autoinfo

my($title, $tracknum, $artist, $album, $comment, $year, $genre) =
  $qt->autoinfo;

Returns an array of tag metadata, similar to the same method in MP3::Tag.

album

my $album = $qt->album;
$new_album = "My New Album Name";
$qt->album($new_album);

Get and set title tag data. Similar to the same method in MP3::TagLib.

Note this and other tag functions below will usually return the empty string "" when there is tag data lacking, unless an integer result is expected, in which case 0 is returned. This is for compatibility with MP3::Tag and Audio::TagLib's implementation of these methods.

artist

my $artist = $qt->artist;
$new_artist = "My New Artist";
$qt->artist($new_artist);

Get and set artist tag data. Similar to the same method in MP3::TagLib.

comment

my $comment = $qt->comment;
$new_comment = "My Comment Goes Here";
$qt->comment($new_comment);

Get and set comment tag data. Similar to the same method in MP3::Tag.

genre

my $genre = $qt->genre;
$new_genre = 18;
$qt->genre($new_genre);

Get and set genre tag data BY NUMBER.

genre_as_text

my $text_genre = $qt->genre_as_text;
$new_genre = "Rock";
$qt->genre_as_text($new_genre);

Get and set genre tag data as text. Note that the given text tag must exist in the genre database to work. See the "our @genre_strings" object in the code, which can be imported by the declaration "our @genre_strings;" in code using the module.

title

my $title = $qt->title;
$new_title = "My New One";
$qt->title($new_title);

Get and set title tag data. Similar to the same method in MP3::Tag.

track

my $track = $qt->track;
my $new_track = 3;
$qt->track($new_track);

Get or set the track number.

tracks

my ($track, $count) = $qt->tracks;
my $new_track_number = 3;
my $total_tracks_on_CD = 17;
$qt->tracks($new_track_number, $total_tracks_on_CD);

Get or set both the track number and the total tracks on the originating media work. Not actually an MP3::Tag method, but MP4 files, unlike many MP3 files, regularly contain both track number and the total originating CD's track count.

total

my $total = $qt->total;
my $new_total = 15;
$qt->total($new_total);

Get or set the track total number.

year

my $year = $qt->year;
$new_year = "My New One";
$qt->year($new_year);

Get and set year tag data. Similar to the same method in MP3::Tag.

all_tags

my $tref = $qt->all_tags( album => "My new album", genre => 21 );
print $tref->{artist};

Similar to the Audio::File::Tag all method. Set or get all the above tags. To set the tags pass a hash reference with the names of the tags as keys and the tag values as hash values. Returns a hash reference if no argument is specified.

The following tag names are supported by this method: album artist comment genre ( the integer value genre ) title track total

Other Audio::TagLib syntactic compatibility

The following 'set' methods are equivalent to methods above used with an argument. They are included in this module for Audio::TagLib compatibility:
Method equivalent to
------------------------
setAlbum album
setArtist artist
setTitle title
setComment comment
setGenre genre
setTrack track
setTracks tracks
setTotal total tracks

Apple m4a personal data removal function

CleanAppleM4aPersonalData

my $file_name = "mp4aIDfile.m4a";
my $qt = Audio::M4P::QuickTime->new(file => $file_name);
$qt->CleanAppleM4aPersonalData();
$qt->WriteFile('cleaned' . $file_name);

...OR...

#!/usr/bin/perl 

use Tk;
use Cwd;
use strict;
use warnings;
use Audio::M4P::QuickTime;

my $backup_requested = "yes";

my $win = new MainWindow;
my $frm = $win->Frame()->pack;
$frm->Label( 
  -text => "Anonymize Apple iTunes Plus .m4a Files",
  -font => "Garamond 20 bold",
)->pack;

my $do_backup_choice = $frm->Radiobutton(
  -text  => "Back Up (append .old.m4a to old files)",
  -value => 'yes',
  -variable => \$backup_requested,
  -font => "Garamond 14 bold",
)->pack;

my $do_no_backup_choice = $frm->Radiobutton(
  -text     => "Do Not Back Up (files will be over-written!)",
  -value    => 'no',
  -variable => \$backup_requested,
  -font => "Garamond 14 bold",
)->pack;

my $convert_button = $win->Button(
  -text    => "Convert Files",
  -command => \&push_button,
  -font => "Garamond 17 bold",
)->pack;

my $exit_button = $win->Button(
  -text    => "Exit",
  -command => sub { exit 0 },
  -font => "Garamond 17 bold",
)->pack;

MainLoop;

sub push_button {
  my $write_extension = $backup_requested eq 'no' ? '' : '.old.m4a';
  my @file_list = $win->getOpenFile(
      -defaultextension => ".pl",
      -filetypes        => [ [ 'MP4a files', '.m4a', ], [ 'All Files', '*', ], ],
      -initialdir       => Cwd::cwd(),
      -initialfile      => "getopenfile",
      -title    => "Choose Purchased Apple iTunes Plus Files to Anonymize",
      -multiple => 1,
  );

  foreach my $filename (@file_list) {
      my $qt = Audio::M4P::QuickTime->new( file => $filename );
      if ( $qt->FindAtom("mp4a") ) {
          $qt->CleanAppleM4aPersonalData();
          rename( $filename, $filename . $write_extension );
          $qt->WriteFile($filename);
      }
      else {
          $win->messageBox(
              -message => "Error: $filename is not a valid m4a file.",
              -type    => 'ok',
              -icon    => 'error'
          );
      }
  }
}

Remove personal identifiers from Apple's iTMS .m4a format files.

Note: to prevent inadvertent alteration of non-Apple .m4a files, the function
requires a m4a atom to be part of the file unless the "force" argument is used, eg.

$qt->CleanAppleM4aPersonalData( force => 1, zero_free_atoms => 1 );

Here, the zero_free_atoms => 1 named argument forces all data in free atoms 
to be nulled out as well.

Class Internal Methods and Functions

AtomList
AtomTree
ConvertDrmsToMp4a
DeleteAtom
DeleteAtomWithStcoFix
DumpTree
FindAtom
FindAtomData
FixStco
GetSampleTable
MakeIlstAtom
MetaInfo
ParseDrms
ParseMP4Container
ParseMeta
ParseStsd
ParseMp4a
genre_num_to_genre_text
genre_text_to_genre_num
isMetaDataType
Get3GPInfo
GetFtype
Set3GPInfo
asset_language_pack_iso_639_2T

BUGS

The Audio::M4P::* code is not re-entrant on a per-file basis, due to recursive changes to containers not being thread-safe. Threaded code using these modules may need to lock down all method calls with a semaphore or other serialization method, unless only one thread is used to modify any given audio file.

AUTHOR

William Herrera wherrera@skylightview.com.

SUPPORT

Questions, feature requests and bug reports should go to <wherrera@skylightview.com>.

COPYRIGHT

To install Audio::M4P::Atom, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Audio::M4P::Atom

CPAN shell

perl -MCPAN -e shell
install Audio::M4P::Atom

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

About QuickTime File Structure and Atoms

SYNOPSIS

METHODS

Object Methods

MP3::Tag and Audio::TagLib Compatible Functions

Other Audio::TagLib syntactic compatibility

Apple m4a personal data removal function

Class Internal Methods and Functions

BUGS

SEE ALSO WITH THIS MODULE

SEE ALSO

AUTHOR

SUPPORT

COPYRIGHT

NAME

DESCRIPTION

About QuickTime File Structure and Atoms

SYNOPSIS

METHODS

Object Methods

MP3::Tag and Audio::TagLib Compatible Functions

Other Audio::TagLib syntactic compatibility

Apple m4a personal data removal function

Class Internal Methods and Functions

BUGS

SEE ALSO WITH THIS MODULE

SEE ALSO

AUTHOR

SUPPORT

COPYRIGHT

Module Install Instructions