Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Ogg::Vorbis::Header(3)User Contributed Perl DocumentatioOgg::Vorbis::Header(3)

NAME
       Ogg::Vorbis::Header - An	object-oriented	interface to Ogg Vorbis
       information and comment fields.

SYNOPSIS
	 use Ogg::Vorbis::Header;
	 my $ogg = Ogg::Vorbis::Header->new("song.ogg");
	 while (my ($k,	$v) = each %{$ogg->info}) {
	   print "$k: $v\n";
	 }
	 foreach my $com ($ogg->comment_tags) {
	   print "$com:	$_\n" foreach $ogg->comment($com);
	 }
	 $ogg->add_comments("good", "no", "ok",	"yes");
	 $ogg->delete_comment("ok");
	 $ogg->write_vorbis;

DESCRIPTION
       This module presents an object-oriented interface to Ogg	Vorbis files
       which allows user to view Vorbis	info and comments and to modify	or add
       comments.

CONSTRUCTORS
   "new	($filename)"
       Partially opens an Ogg Vorbis file to ensure it exists and is actually
       a Vorbis	stream.	 It then closes	the filehandle.	 It does not fill in
       the object's data fields.  These	fields will be automatically filled
       the first time they are accessed	using the object's instance methods.
       Returns "undef" if there	is a problem opening the file or the file is
       not valid Ogg Vorbis.

   "load ([$filename])"
       Opens an	Ogg Vorbis file, reads its information,	and then closes	the
       filehandle.  Returns "undef" if there is	a problem opening the file or
       the file	is not valid Ogg Vorbis.  This is both a constructor and an
       instance	method.	 The filename is required in constructor context, but
       should be left out when you call	this as	an instance method on an
       object.	When called as an instance method, it (re)loads	the info and
       comment data from the file.  This can be	used to	reset the state	of the
       object if write_vorbis hasn't been called.  Note	that the path
       parameter is ignored in instance	context.

INSTANCE METHODS
       These methods may be called on actual Header objects, using the ->
       operator	or indirect objects as you prefer.

   "info ([$key])"
       Returns a reference to a	hash containing	format information about the
       Vorbis file.  Hash fields are: version, channels, rate, bitrate_upper,
       bitrate_nominal,	bitrate_lower, and bitrate_window, length.  The
       bitrate_window value is currently unused	by the vorbis codec.  You can
       modify the referenced hash if you want, but I wouldn't suggest it.

       The optional key	parameter allows you to	extract	a single value from
       the internal hash (passed by value, not reference).  If the key is
       invalid,	"undef"	is returned.

   "comment_tags ()"
       Returns an array	holding	the key	values of each comment field.  You can
       then use	these values to	access specific	fields using "comment".	 This
       may seem	somewhat clunky	at first but it	will speed up most programs.
       In addition, it makes it	easier to support the Ogg Vorbis comment
       standard	which allows multiple fields with the same key.

   "comment ($key)"
       Returns a list of comments given	a key.	 If the	key does not exist,
       returns "undef".

   "add_comments ($key,	$value,	[$key, $value, ...])"
       Adds comments with the given keys and values.  Takes an array of
       alternating keys	and values as parameters.  Keys	and values should be
       valid ascii in the range	0x20 - 0x7D and	the key	should exclude 0x3D
       ('=').  This is a subset	of the Vorbis standard which allows this range
       for the key field and all of utf8 for the value field.  This will be
       fixed in	future a release.

       If an odd-length	array is passed	in the routine will fail and return
       "undef".	 Key and value will be trimmed of characters which do not
       match the format	requirement.

   "edit_comment ($key,	$value,	[$num])"
       Edits a given comment field.  The optional num field is used to
       differentiate between two comments with the same	key.  If no num	is
       supplied, the first value--as reported by "comment"--is modified.  If
       the key or num are invalid, nothing is done and undef is	returned.  If
       all goes	well, the old value is returned.

   "delete_comment ($key, [$num])"
       Deletes the comment given by key.  The optional num value can be	used
       to specify which	comment	to delete, given duplicate keys.  Leaving num
       out will	result in only the first instance being	deleted.  Returns
       "undef" if key or num are invalid.  If all goes well, the value of the
       deleted comment is returned.

   "clear_comments ([@keys])"
       Deletes all of the comments which match keys in the input array or all
       of the comments in the stream if	called with no arguments.  Returns
       "undef" if any key is invalid, although all keys	in the input array up
       until that key will be cleared.	Returns	true otherwise.

   "write_vorbis ()"
       Write object to its backing file.  No comment modifications will	be
       seen in the file	until this operation is	performed.

   "path ()"
       Returns the path/filename of the	file the object	represents.

REQUIRES
       Inline::C, libogg, libvorbis, libogg-dev, libvorbis-dev.

AUTHOR
       Dan Pemstein <dan@lcws.org>

COPYRIGHT
       Copyright (c) 2003, Dan Pemstein.  All Rights Reserved.

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either	version	2 of the License, or (at your
       option) any later version.  A copy of this license is included with
       this module (LICENSE.GPL).

       A library for editing Ogg Vorbis	comments is distributed	with this
       library as unmodified source code (inc/vcedit.h,	inc/vcedit.c,
       inc/i18n.h).  This library is Copyright (c) Michael Smith
       <msmith@labyrinth.net.au>.  It is licensed under	the GNU	Library
       General Public License (LGPL).  A copy of this license is included with
       this module (inc/LICENSE.LGPL).

SEE ALSO
       Ogg::Vorbis::Decoder, Inline::C,	Audio::Ao.

perl v5.32.0			  2018-03-19		Ogg::Vorbis::Header(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | INSTANCE METHODS | REQUIRES | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Ogg::Vorbis::Header&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help