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