[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.004';

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::Head;
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 - partial 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. It exports nearly all
of the functions for obtaining metadata of an Opus file or buffer in
that library. Future versions will additionally provide functions for
decoding Opus data into PCM.

The API might 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 Audio::Opusfile->B<new_from_memory>(I<$buffer>)

Creates a new Audio::Opusfile object from a buffer containing Ogg Opus
data.

Dies if the given buffer does not contain valid data.

=item Audio::Opusfile::test(I<$buffer>)

Returns true if the given buffer looks like the beginning of a valid
Ogg Opus file, false otherwise.

Dies if the given buffer does not have sufficient data to tell if it
is an Opus stream or if it looks like a Opus stream but parsing it
failed.

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

=item B<$of>->seekable

Returns whether or not the data source being read is seekable.

=item B<$of>->link_count

Returns the number of links in this chained stream. Always returns 1
for unseekable sources.

=item B<$of>->serialno([I<$link_index>])

Get the serial number of the given link in a (possibly-chained) Ogg
Opus stream. If the given index is greater than the total number of
links, this returns the serial number of the last link.

If the source is not seekable, I<$link_index> is negative, or
I<$link_index> is not given, then this function returns the serial
number of the current link.

=item B<$of>->op_raw_total([I<$link_index>])

Get the total (compressed) size of the stream (with no arguments), or
of an individual link in a (possibly-chained) Ogg Opus stream (with
one nonnegative argument), including all headers and Ogg muxing
overhead.

The stream must be seekable to get the total. A negative value is
returned if the stream is not seekable.

B<Warning:> If the Opus stream (or link) is concurrently multiplexed
with other logical streams (e.g., video), this returns the size of the
entire stream (or link), not just the number of bytes in the first
logical Opus stream. Returning the latter would require scanning the
entire file.

=item B<$of>->op_pcm_total([I<$link_index>])

Get the total PCM length (number of samples at 48 kHz) of the stream
(with no arguments), or of an individual link in a (possibly-chained)
Ogg Opus stream (with one nonnegative argument).

Users looking for op_time_total() should use this function instead.
Because timestamps in Opus are fixed at 48 kHz, there is no need for a
separate function to convert this to seconds.

The stream must be seekable to get the total. A negative value is
returned if the stream is not seekable.

=item B<$of>->op_bitrate([I<$link_index>])

Computes the bitrate of the stream (with no arguments), or of an
individual link in a (possibly-chained) Ogg Opus stream (with one
nonnegative argument).

The stream must be seekable to compute the bitrate. A negative value
is returned if the stream is not seekable.

B<Warning:> If the Opus stream (or link) is concurrently multiplexed with
other logical streams (e.g., video), this uses the size of the entire
stream (or link) to compute the bitrate, not just the number of bytes
in the first logical Opus stream.

=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::Head>,
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
60230f2b	49	our $VERSION = '0.004';
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);
b9bd6a0d	76	require Audio::Opusfile::Head;
a3f1cbda	77	require Audio::Opusfile::Tags;
2f4b5b1b	78	require Audio::Opusfile::PictureTag;
a3f1cbda MG	79
	80	# Preloaded methods go here.
	81
	82	sub new_from_file {
	83	my ($class, $file) = @_;
	84	open_file($file)
	85	}
	86
5fbea9a2 MG	87	sub new_from_memory {
	88	my ($class, $buf) = @_;
	89	open_memory($buf)
	90	}
	91
a3f1cbda MG	92	1;
	93	__END__
	94
	95	=encoding utf-8
	96
	97	=head1 NAME
	98
196e0b27	99	Audio::Opusfile - partial interface to the libopusfile Ogg Opus library
a3f1cbda MG	100
	101	=head1 SYNOPSIS
	102
	103	use Audio::Opusfile;
	104	my $of = Audio::Opusfile->new_from_file('silence.opus');
	105	my $tags = $of->tags;
	106	say $tags->query('TITLE'); # Cellule
	107
	108	=head1 DESCRIPTION
	109
	110	Opus is a totally open, royalty-free, highly versatile audio codec.
	111	Opus is unmatched for interactive speech and music transmission over
	112	the Internet, but is also intended for storage and streaming
	113	applications. It is standardized by the Internet Engineering Task
	114	Force (IETF) as RFC 6716 which incorporated technology from Skype's
	115	SILK codec and Xiph.Org's CELT codec.
	116
	117	libopusfile is a library for decoding and basic manipulation of Ogg
	118	Opus files.
	119
196e0b27 MG	120	Audio::Opusfile is an interface to libopusfile. It exports nearly all
	121	of the functions for obtaining metadata of an Opus file or buffer in
	122	that library. Future versions will additionally provide functions for
	123	decoding Opus data into PCM.
a3f1cbda	124
196e0b27	125	The API might change in future versions.
a3f1cbda MG	126
	127	=head1 METHODS
	128
	129	=over
	130
	131	=item Audio::Opusfile->B<new_from_file>(I<$file>)
	132
	133	Creates a new Audio::Opusfile object from an Ogg Opus file.
	134
	135	Dies if the given file does not exist or is not a valid Ogg Opus file.
	136
33fac129 MG	137	=item Audio::Opusfile->B<new_from_memory>(I<$buffer>)
	138
	139	Creates a new Audio::Opusfile object from a buffer containing Ogg Opus
	140	data.
	141
	142	Dies if the given buffer does not contain valid data.
	143
	144	=item Audio::Opusfile::test(I<$buffer>)
	145
	146	Returns true if the given buffer looks like the beginning of a valid
	147	Ogg Opus file, false otherwise.
	148
	149	Dies if the given buffer does not have sufficient data to tell if it
	150	is an Opus stream or if it looks like a Opus stream but parsing it
	151	failed.
	152
2f4b5b1b MG	153	=item B<$of>->head
	154
	155	Returns an L<Audio::Opusfile::Head> object corresponding to the file.
	156
a3f1cbda MG	157	=item B<$of>->tags
	158
	159	Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
	160
33fac129 MG	161	=item B<$of>->seekable
	162
	163	Returns whether or not the data source being read is seekable.
	164
	165	=item B<$of>->link_count
	166
	167	Returns the number of links in this chained stream. Always returns 1
	168	for unseekable sources.
	169
	170	=item B<$of>->serialno([I<$link_index>])
	171
	172	Get the serial number of the given link in a (possibly-chained) Ogg
	173	Opus stream. If the given index is greater than the total number of
	174	links, this returns the serial number of the last link.
	175
	176	If the source is not seekable, I<$link_index> is negative, or
	177	I<$link_index> is not given, then this function returns the serial
	178	number of the current link.
	179
dc986a40 MG	180	=item B<$of>->op_raw_total([I<$link_index>])
	181
	182	Get the total (compressed) size of the stream (with no arguments), or
	183	of an individual link in a (possibly-chained) Ogg Opus stream (with
	184	one nonnegative argument), including all headers and Ogg muxing
	185	overhead.
	186
	187	The stream must be seekable to get the total. A negative value is
	188	returned if the stream is not seekable.
	189
	190	B<Warning:> If the Opus stream (or link) is concurrently multiplexed
	191	with other logical streams (e.g., video), this returns the size of the
	192	entire stream (or link), not just the number of bytes in the first
	193	logical Opus stream. Returning the latter would require scanning the
	194	entire file.
	195
	196	=item B<$of>->op_pcm_total([I<$link_index>])
	197
	198	Get the total PCM length (number of samples at 48 kHz) of the stream
	199	(with no arguments), or of an individual link in a (possibly-chained)
	200	Ogg Opus stream (with one nonnegative argument).
	201
	202	Users looking for op_time_total() should use this function instead.
	203	Because timestamps in Opus are fixed at 48 kHz, there is no need for a
	204	separate function to convert this to seconds.
	205
	206	The stream must be seekable to get the total. A negative value is
	207	returned if the stream is not seekable.
	208
	209	=item B<$of>->op_bitrate([I<$link_index>])
	210
	211	Computes the bitrate of the stream (with no arguments), or of an
	212	individual link in a (possibly-chained) Ogg Opus stream (with one
	213	nonnegative argument).
	214
	215	The stream must be seekable to compute the bitrate. A negative value
	216	is returned if the stream is not seekable.
	217
	218	B<Warning:> If the Opus stream (or link) is concurrently multiplexed with
	219	other logical streams (e.g., video), this uses the size of the entire
	220	stream (or link) to compute the bitrate, not just the number of bytes
	221	in the first logical Opus stream.
	222
a3f1cbda MG	223	=back
	224
	225	=head1 EXPORT
	226
	227	All constants are exported by default:
	228
	229	OPUS_CHANNEL_COUNT_MAX
	230	OP_ABSOLUTE_GAIN
	231	OP_DEC_FORMAT_FLOAT
	232	OP_DEC_FORMAT_SHORT
	233	OP_DEC_USE_DEFAULT
	234	OP_EBADHEADER
	235	OP_EBADLINK
	236	OP_EBADPACKET
	237	OP_EBADTIMESTAMP
	238	OP_EFAULT
	239	OP_EIMPL
	240	OP_EINVAL
	241	OP_ENOSEEK
	242	OP_ENOTAUDIO
	243	OP_ENOTFORMAT
	244	OP_EOF
	245	OP_EREAD
	246	OP_EVERSION
	247	OP_FALSE
	248	OP_GET_SERVER_INFO_REQUEST
	249	OP_HEADER_GAIN
	250	OP_HOLE
	251	OP_HTTP_PROXY_HOST_REQUEST
	252	OP_HTTP_PROXY_PASS_REQUEST
	253	OP_HTTP_PROXY_PORT_REQUEST
	254	OP_HTTP_PROXY_USER_REQUEST
	255	OP_PIC_FORMAT_GIF
	256	OP_PIC_FORMAT_JPEG
	257	OP_PIC_FORMAT_PNG
	258	OP_PIC_FORMAT_UNKNOWN
	259	OP_PIC_FORMAT_URL
	260	OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
	261	OP_TRACK_GAIN
	262
	263
	264	=head1 SEE ALSO
	265
b9bd6a0d	266	L<Audio::Opusfile::Head>,
a3f1cbda MG	267	L<Audio::Opusfile::Tags>,
	268	L<http://opus-codec.org/>,
	269	L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
	270
	271	=head1 AUTHOR
	272
	273	Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
	274
	275	=head1 COPYRIGHT AND LICENSE
	276
	277	Copyright (C) 2016 by Marius Gavrilescu
	278
	279	This library is free software; you can redistribute it and/or modify
	280	it under the same terms as Perl itself, either Perl version 5.24.0 or,
	281	at your option, any later version of Perl 5 you may have available.
	282
	283
	284	=cut