[audio-opusfile.git] / lib / Audio / Opusfile / PictureTag.pm

package Audio::Opusfile::PictureTag;
# Don't load this module directly, load Audio::Opusfile instead

use 5.014000;
use strict;
use warnings;
use subs qw/parse/;

our $VERSION = '0.004';

sub new { parse $_[1] }

1;
__END__

=encoding utf-8

=head1 NAME

Audio::Opusfile::PictureTag - A parsed METADATA_BLOCK_PICTURE tag

=head1 SYNOPSIS

  use Audio::Opusfile;
  my $of = Audio::Opusfile->new_from_file('file.opus');
  my @pic_tags = $of->tags->query_all('METADATA_BLOCK_PICTURE');
  my @pictures = map { Audio::Opusfile::PictureTag->parse($_) } @pic_tags;
  my $pic = $pictures[0];
  say $pic->type; # Prints "3", which means Cover (front)
  say $pic->mime_type; # Prints "image/png"
  say $pic->description;
  say $pic->width;
  say $pic->height;
  say $pic->depth;
  say $pic->colors;
  say $pic->data_length; # The image size
  my $data = $pic->data; # The contents of the image
  say $pic->format; # One of the OP_PIC_* constants

=head1 DESCRIPTION

This module represents a METADATA_BLOCK_PICTURE tag. It has the
following methods (descriptions taken from the libopusfile
documentation):

=over

=item Audio::Opusfile::PictureTag->B<new>(I<$tag>)

Takes the contents of a METADATA_BLOCK_PICTURE tag (optionally
prefixed by the string C<METADATA_BLOCK_PICTURE=>) and returns a new
Audio::Opusfile::PictureTag object.

=item $pic->B<type>

The picture type according to the ID3v2 APIC frame

   0.  Other
   1.  32x32 pixels 'file icon' (PNG only)
   2.  Other file icon
   3.  Cover (front)
   4.  Cover (back)
   5.  Leaflet page
   6.  Media (e.g. label side of CD)
   7.  Lead artist/lead performer/soloist
   8.  Artist/performer
   9.  Conductor
   10. Band/Orchestra
   11. Composer
   12. Lyricist/text writer
   13. Recording Location
   14. During recording
   15. During performance
   16. Movie/video screen capture
   17. A bright colored fish
   18. Illustration
   19. Band/artist logotype
   20. Publisher/Studio logotype

Others are reserved and should not be used. There may only be one each
of picture type 1 and 2 in a file.

=item $pic->B<mime_type>

The MIME type of the picture, in printable ASCII characters 0x20-0x7E.

The MIME type may also be "-->" to signify that the data part is a URL
pointing to the picture instead of the picture data itself. In this
case, a terminating NUL is appended to the URL string in data, but
data_length is set to the length of the string excluding that
terminating NUL.

=item $pic->B<description>

The description of the picture, in UTF-8.

=item $pic->B<width>

The width of the picture in pixels.

=item $pic->B<height>

The height of the picture in pixels.

=item $pic->B<depth>

The color depth of the picture in bits-per-pixel (not
bits-per-channel).

=item $pic->B<colors>

For indexed-color pictures (e.g., GIF), the number of colors used, or
0 for non-indexed pictures.

=item $pic->B<data_length>

The length of the picture data in bytes. Equivalent to C<< length ($pic->data) >>.

=item $pic->B<data>

The binary picture data.

=item $pic->B<format>

The format of the picture data, if known. One of:
OP_PIC_FORMAT_UNKNOWN, OP_PIC_FORMAT_URL, OP_PIC_FORMAT_JPEG,
OP_PIC_FORMAT_PNG, or OP_PIC_FORMAT_GIF.

 =back

=head1 SEE ALSO

L<Audio::Opusfile>,
L<http://opus-codec.org/>,
L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>,
L<https://www.opus-codec.org/docs/opusfile_api-0.7/structOpusPictureTag.html>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.24.0 or,
at your option, any later version of Perl 5 you may have available.


=cut
Commit	Line	Data
2f4b5b1b MG	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
60230f2b	9	our $VERSION = '0.004';
6116de10	10
2f4b5b1b MG	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 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