[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/;

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
	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