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

package Audio::Opusfile;

use 5.014000;
use strict;
use warnings;
use Carp;

use parent qw/Exporter/;
use AutoLoader;

my @constants =
  qw/OPUS_CHANNEL_COUNT_MAX
	 OP_ABSOLUTE_GAIN
	 OP_DEC_FORMAT_FLOAT
	 OP_DEC_FORMAT_SHORT
	 OP_DEC_USE_DEFAULT
	 OP_EBADHEADER
	 OP_EBADLINK
	 OP_EBADPACKET
	 OP_EBADTIMESTAMP
	 OP_EFAULT
	 OP_EIMPL
	 OP_EINVAL
	 OP_ENOSEEK
	 OP_ENOTAUDIO
	 OP_ENOTFORMAT
	 OP_EOF
	 OP_EREAD
	 OP_EVERSION
	 OP_FALSE
	 OP_GET_SERVER_INFO_REQUEST
	 OP_HEADER_GAIN
	 OP_HOLE
	 OP_HTTP_PROXY_HOST_REQUEST
	 OP_HTTP_PROXY_PASS_REQUEST
	 OP_HTTP_PROXY_PORT_REQUEST
	 OP_HTTP_PROXY_USER_REQUEST
	 OP_PIC_FORMAT_GIF
	 OP_PIC_FORMAT_JPEG
	 OP_PIC_FORMAT_PNG
	 OP_PIC_FORMAT_UNKNOWN
	 OP_PIC_FORMAT_URL
	 OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
	 OP_TRACK_GAIN/;

our @EXPORT_OK = @constants;
our @EXPORT = @constants;

our $VERSION = '0.002001';

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.

    my $constname;
    our $AUTOLOAD;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "&Audio::Opusfile::constant not defined" if $constname eq 'constant';
    my ($error, $val) = constant($constname);
    if ($error) { croak $error; }
    {
	no strict 'refs';
	# Fixed between 5.005_53 and 5.005_61
#XXX	if ($] >= 5.00561) {
#XXX	    *$AUTOLOAD = sub () { $val };
#XXX	}
#XXX	else {
	    *$AUTOLOAD = sub { $val };
#XXX	}
    }
    goto &$AUTOLOAD;
}

require XSLoader;
XSLoader::load('Audio::Opusfile', $VERSION);
require Audio::Opusfile::Tags;
require Audio::Opusfile::PictureTag;

# Preloaded methods go here.

sub new_from_file {
	my ($class, $file) = @_;
	open_file($file)
}

sub new_from_memory {
	my ($class, $buf) = @_;
	open_memory($buf)
}

1;
__END__

=encoding utf-8

=head1 NAME

Audio::Opusfile - Very incomplete interface to the libopusfile Ogg Opus library

=head1 SYNOPSIS

  use Audio::Opusfile;
  my $of = Audio::Opusfile->new_from_file('silence.opus');
  my $tags = $of->tags;
  say $tags->query('TITLE'); # Cellule

=head1 DESCRIPTION

Opus is a totally open, royalty-free, highly versatile audio codec.
Opus is unmatched for interactive speech and music transmission over
the Internet, but is also intended for storage and streaming
applications. It is standardized by the Internet Engineering Task
Force (IETF) as RFC 6716 which incorporated technology from Skype's
SILK codec and Xiph.Org's CELT codec.

libopusfile is a library for decoding and basic manipulation of Ogg
Opus files.

Audio::Opusfile is an interface to libopusfile. At the moment its only
function is reading metadata and tags from an Ogg Opus file. Future
versions will give access to a larger part of the libopusfile API.

Expect the API to change in future versions.

=head1 METHODS

=over

=item Audio::Opusfile->B<new_from_file>(I<$file>)

Creates a new Audio::Opusfile object from an Ogg Opus file.

Dies if the given file does not exist or is not a valid Ogg Opus file.

=item B<$of>->head

Returns an L<Audio::Opusfile::Head> object corresponding to the file.

=item B<$of>->tags

Returns an L<Audio::Opusfile::Tags> object corresponding to the file.

=back

=head1 EXPORT

All constants are exported by default:

  OPUS_CHANNEL_COUNT_MAX
  OP_ABSOLUTE_GAIN
  OP_DEC_FORMAT_FLOAT
  OP_DEC_FORMAT_SHORT
  OP_DEC_USE_DEFAULT
  OP_EBADHEADER
  OP_EBADLINK
  OP_EBADPACKET
  OP_EBADTIMESTAMP
  OP_EFAULT
  OP_EIMPL
  OP_EINVAL
  OP_ENOSEEK
  OP_ENOTAUDIO
  OP_ENOTFORMAT
  OP_EOF
  OP_EREAD
  OP_EVERSION
  OP_FALSE
  OP_GET_SERVER_INFO_REQUEST
  OP_HEADER_GAIN
  OP_HOLE
  OP_HTTP_PROXY_HOST_REQUEST
  OP_HTTP_PROXY_PASS_REQUEST
  OP_HTTP_PROXY_PORT_REQUEST
  OP_HTTP_PROXY_USER_REQUEST
  OP_PIC_FORMAT_GIF
  OP_PIC_FORMAT_JPEG
  OP_PIC_FORMAT_PNG
  OP_PIC_FORMAT_UNKNOWN
  OP_PIC_FORMAT_URL
  OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
  OP_TRACK_GAIN


=head1 SEE ALSO

L<Audio::Opusfile::Tags>,
L<http://opus-codec.org/>,
L<http://opus-codec.org/docs/opusfile_api-0.7/index.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
a3f1cbda MG	1	package Audio::Opusfile;
	2
	3	use 5.014000;
	4	use strict;
	5	use warnings;
	6	use Carp;
	7
	8	use parent qw/Exporter/;
	9	use AutoLoader;
	10
	11	my @constants =
	12	qw/OPUS_CHANNEL_COUNT_MAX
	13	OP_ABSOLUTE_GAIN
	14	OP_DEC_FORMAT_FLOAT
	15	OP_DEC_FORMAT_SHORT
	16	OP_DEC_USE_DEFAULT
	17	OP_EBADHEADER
	18	OP_EBADLINK
	19	OP_EBADPACKET
	20	OP_EBADTIMESTAMP
	21	OP_EFAULT
	22	OP_EIMPL
	23	OP_EINVAL
	24	OP_ENOSEEK
	25	OP_ENOTAUDIO
	26	OP_ENOTFORMAT
	27	OP_EOF
	28	OP_EREAD
	29	OP_EVERSION
	30	OP_FALSE
	31	OP_GET_SERVER_INFO_REQUEST
	32	OP_HEADER_GAIN
	33	OP_HOLE
	34	OP_HTTP_PROXY_HOST_REQUEST
	35	OP_HTTP_PROXY_PASS_REQUEST
	36	OP_HTTP_PROXY_PORT_REQUEST
	37	OP_HTTP_PROXY_USER_REQUEST
	38	OP_PIC_FORMAT_GIF
	39	OP_PIC_FORMAT_JPEG
	40	OP_PIC_FORMAT_PNG
	41	OP_PIC_FORMAT_UNKNOWN
	42	OP_PIC_FORMAT_URL
	43	OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
	44	OP_TRACK_GAIN/;
	45
	46	our @EXPORT_OK = @constants;
	47	our @EXPORT = @constants;
	48
74630599	49	our $VERSION = '0.002001';
a3f1cbda MG	50
	51	sub AUTOLOAD {
	52	# This AUTOLOAD is used to 'autoload' constants from the constant()
	53	# XS function.
	54
	55	my $constname;
	56	our $AUTOLOAD;
	57	($constname = $AUTOLOAD) =~ s/.*:://;
	58	croak "&Audio::Opusfile::constant not defined" if $constname eq 'constant';
	59	my ($error, $val) = constant($constname);
	60	if ($error) { croak $error; }
	61	{
	62	no strict 'refs';
	63	# Fixed between 5.005_53 and 5.005_61
	64	#XXX if ($] >= 5.00561) {
	65	#XXX *$AUTOLOAD = sub () { $val };
	66	#XXX }
	67	#XXX else {
	68	*$AUTOLOAD = sub { $val };
	69	#XXX }
	70	}
	71	goto &$AUTOLOAD;
	72	}
	73
	74	require XSLoader;
	75	XSLoader::load('Audio::Opusfile', $VERSION);
	76	require Audio::Opusfile::Tags;
2f4b5b1b	77	require Audio::Opusfile::PictureTag;
a3f1cbda MG	78
	79	# Preloaded methods go here.
	80
	81	sub new_from_file {
	82	my ($class, $file) = @_;
	83	open_file($file)
	84	}
	85
5fbea9a2 MG	86	sub new_from_memory {
	87	my ($class, $buf) = @_;
	88	open_memory($buf)
	89	}
	90
a3f1cbda MG	91	1;
	92	__END__
	93
	94	=encoding utf-8
	95
	96	=head1 NAME
	97
	98	Audio::Opusfile - Very incomplete interface to the libopusfile Ogg Opus library
	99
	100	=head1 SYNOPSIS
	101
	102	use Audio::Opusfile;
	103	my $of = Audio::Opusfile->new_from_file('silence.opus');
	104	my $tags = $of->tags;
	105	say $tags->query('TITLE'); # Cellule
	106
	107	=head1 DESCRIPTION
	108
	109	Opus is a totally open, royalty-free, highly versatile audio codec.
	110	Opus is unmatched for interactive speech and music transmission over
	111	the Internet, but is also intended for storage and streaming
	112	applications. It is standardized by the Internet Engineering Task
	113	Force (IETF) as RFC 6716 which incorporated technology from Skype's
	114	SILK codec and Xiph.Org's CELT codec.
	115
	116	libopusfile is a library for decoding and basic manipulation of Ogg
	117	Opus files.
	118
	119	Audio::Opusfile is an interface to libopusfile. At the moment its only
2f4b5b1b MG	120	function is reading metadata and tags from an Ogg Opus file. Future
2f4b5b1b MG	121	versions will give access to a larger part of the libopusfile API.
a3f1cbda MG	122
	123	Expect the API to change in future versions.
	124
	125	=head1 METHODS
	126
	127	=over
	128
	129	=item Audio::Opusfile->B<new_from_file>(I<$file>)
	130
	131	Creates a new Audio::Opusfile object from an Ogg Opus file.
	132
	133	Dies if the given file does not exist or is not a valid Ogg Opus file.
	134
2f4b5b1b MG	135	=item B<$of>->head
	136
	137	Returns an L<Audio::Opusfile::Head> object corresponding to the file.
	138
a3f1cbda MG	139	=item B<$of>->tags
	140
	141	Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
	142
	143	=back
	144
	145	=head1 EXPORT
	146
	147	All constants are exported by default:
	148
	149	OPUS_CHANNEL_COUNT_MAX
	150	OP_ABSOLUTE_GAIN
	151	OP_DEC_FORMAT_FLOAT
	152	OP_DEC_FORMAT_SHORT
	153	OP_DEC_USE_DEFAULT
	154	OP_EBADHEADER
	155	OP_EBADLINK
	156	OP_EBADPACKET
	157	OP_EBADTIMESTAMP
	158	OP_EFAULT
	159	OP_EIMPL
	160	OP_EINVAL
	161	OP_ENOSEEK
	162	OP_ENOTAUDIO
	163	OP_ENOTFORMAT
	164	OP_EOF
	165	OP_EREAD
	166	OP_EVERSION
	167	OP_FALSE
	168	OP_GET_SERVER_INFO_REQUEST
	169	OP_HEADER_GAIN
	170	OP_HOLE
	171	OP_HTTP_PROXY_HOST_REQUEST
	172	OP_HTTP_PROXY_PASS_REQUEST
	173	OP_HTTP_PROXY_PORT_REQUEST
	174	OP_HTTP_PROXY_USER_REQUEST
	175	OP_PIC_FORMAT_GIF
	176	OP_PIC_FORMAT_JPEG
	177	OP_PIC_FORMAT_PNG
	178	OP_PIC_FORMAT_UNKNOWN
	179	OP_PIC_FORMAT_URL
	180	OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
	181	OP_TRACK_GAIN
	182
	183
	184	=head1 SEE ALSO
	185
	186	L<Audio::Opusfile::Tags>,
	187	L<http://opus-codec.org/>,
	188	L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
	189
	190	=head1 AUTHOR
	191
	192	Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
	193
	194	=head1 COPYRIGHT AND LICENSE
	195
	196	Copyright (C) 2016 by Marius Gavrilescu
	197
	198	This library is free software; you can redistribute it and/or modify
	199	it under the same terms as Perl itself, either Perl version 5.24.0 or,
	200	at your option, any later version of Perl 5 you may have available.
	201
	202
203	=cut