lib/Audio/Opusfile/PictureTag.pm

   1 package Audio::Opusfile::PictureTag;
   2 # Don't load this module directly, load Audio::Opusfile instead
   3
   4 use 5.014000;
   5 use strict;
   6 use warnings;
   7 use subs qw/parse/;
   8
   9 our $VERSION = '1.000';
  10
  11 sub new { parse $_[1] }
  12
  13 1;
  14 __END__
  15
  16 =encoding utf-8
  17
  18 =head1 NAME
  19
  20 Audio::Opusfile::PictureTag - A parsed METADATA_BLOCK_PICTURE tag
  21
  22 =head1 SYNOPSIS
  23
  24   use Audio::Opusfile;
  25   my $of = Audio::Opusfile->new_from_file('file.opus');
  26   my @pic_tags = $of->tags->query_all('METADATA_BLOCK_PICTURE');
  27   my @pictures = map { Audio::Opusfile::PictureTag->parse($_) } @pic_tags;
  28   my $pic = $pictures[0];
  29   say $pic->type; # Prints "3", which means Cover (front)
  30   say $pic->mime_type; # Prints "image/png"
  31   say $pic->description;
  32   say $pic->width;
  33   say $pic->height;
  34   say $pic->depth;
  35   say $pic->colors;
  36   say $pic->data_length; # The image size
  37   my $data = $pic->data; # The contents of the image
  38   say $pic->format; # One of the OP_PIC_* constants
  39
  40 =head1 DESCRIPTION
  41
  42 This module represents a METADATA_BLOCK_PICTURE tag. It has the
  43 following methods (descriptions taken from the libopusfile
  44 documentation):
  45
  46 =over
  47
  48 =item Audio::Opusfile::PictureTag->B<new>(I<$tag>)
  49
  50 Takes the contents of a METADATA_BLOCK_PICTURE tag (optionally
  51 prefixed by the string C<METADATA_BLOCK_PICTURE=>) and returns a new
  52 Audio::Opusfile::PictureTag object.
  53
  54 =item $pic->B<type>
  55
  56 The picture type according to the ID3v2 APIC frame
  57
  58    0.  Other
  59    1.  32x32 pixels 'file icon' (PNG only)
  60    2.  Other file icon
  61    3.  Cover (front)
  62    4.  Cover (back)
  63    5.  Leaflet page
  64    6.  Media (e.g. label side of CD)
  65    7.  Lead artist/lead performer/soloist
  66    8.  Artist/performer
  67    9.  Conductor
  68    10. Band/Orchestra
  69    11. Composer
  70    12. Lyricist/text writer
  71    13. Recording Location
  72    14. During recording
  73    15. During performance
  74    16. Movie/video screen capture
  75    17. A bright colored fish
  76    18. Illustration
  77    19. Band/artist logotype
  78    20. Publisher/Studio logotype
  79
  80 Others are reserved and should not be used. There may only be one each
  81 of picture type 1 and 2 in a file.
  82
  83 =item $pic->B<mime_type>
  84
  85 The MIME type of the picture, in printable ASCII characters 0x20-0x7E.
  86
  87 The MIME type may also be "-->" to signify that the data part is a URL
  88 pointing to the picture instead of the picture data itself. In this
  89 case, a terminating NUL is appended to the URL string in data, but
  90 data_length is set to the length of the string excluding that
  91 terminating NUL.
  92
  93 =item $pic->B<description>
  94
  95 The description of the picture, in UTF-8.
  96
  97 =item $pic->B<width>
  98
  99 The width of the picture in pixels.
 100
 101 =item $pic->B<height>
 102
 103 The height of the picture in pixels.
 104
 105 =item $pic->B<depth>
 106
 107 The color depth of the picture in bits-per-pixel (not
 108 bits-per-channel).
 109
 110 =item $pic->B<colors>
 111
 112 For indexed-color pictures (e.g., GIF), the number of colors used, or
 113 0 for non-indexed pictures.
 114
 115 =item $pic->B<data_length>
 116
 117 The length of the picture data in bytes. Equivalent to C<< length ($pic->data) >>.
 118
 119 =item $pic->B<data>
 120
 121 The binary picture data.
 122
 123 =item $pic->B<format>
 124
 125 The format of the picture data, if known. One of:
 126 OP_PIC_FORMAT_UNKNOWN, OP_PIC_FORMAT_URL, OP_PIC_FORMAT_JPEG,
 127 OP_PIC_FORMAT_PNG, or OP_PIC_FORMAT_GIF.
 128
 129 =back
 130
 131 =head1 SEE ALSO
 132
 133 L<Audio::Opusfile>,
 134 L<http://opus-codec.org/>,
 135 L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>,
 136 L<https://www.opus-codec.org/docs/opusfile_api-0.7/structOpusPictureTag.html>
 137
 138 =head1 AUTHOR
 139
 140 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 141
 142 =head1 COPYRIGHT AND LICENSE
 143
 144 Copyright (C) 2016-2017 by Marius Gavrilescu
 145
 146 This library is free software; you can redistribute it and/or modify
 147 it under the same terms as Perl itself, either Perl version 5.24.0 or,
 148 at your option, any later version of Perl 5 you may have available.
 149
 150
 151 =cut