view release on metacpan or  search on metacpan

lib/CDDB.pm  view on Meta::CPAN

sub text {
	my $self = shift;
	$self->{response_text};
}

#------------------------------------------------------------------------------
# Helper to print stuff for debugging.

sub debug_print {
	my $self = shift;

	# Don't bother if not debugging.
	return unless $self->{debug};

	my $level = shift;
	my $text = join('', @_);
	print STDERR $text, "\n";
}

#------------------------------------------------------------------------------
# Read data until it's terminated by a single dot on its own line.
# Two dots at the start of a line are replaced by one.  Returns an
# ARRAY reference containing the lines received, or undef on error.

sub read_until_dot {
	my $self = shift;
	my @lines;

	while ('true') {
		my $line = $self->getline() or return;
		last if ($line =~ /^\.$/);
		$line =~ s/^\.\././;
		push @lines, $line;
	}

	\@lines;
}

#------------------------------------------------------------------------------
# Create an object to represent one or more cddbp sessions.

sub new {
	my $type = shift;
	my %param = @_;

	# Attempt to suss our hostname.
	my $hostname = &hostname();

	# Attempt to suss our login ID.
	my $login = $param{Login} || $ENV{LOGNAME} || $ENV{USER};
	if (not defined $login) {
		if (USING_WINDOWS) {
			carp(
				"Can't get login ID.  Use Login parameter or " .
				"set LOGNAME or USER environment variable.  Using default login " .
				"ID 'win32usr'"
			);
			$login = 'win32usr';
		}
		else {
			$login = getpwuid($>)
				or croak(
					"Can't get login ID.  " .
					"Set LOGNAME or USER environment variable and try again: $!"
				);
		}
	}

	# Debugging flag.
	my $debug = $param{Debug};
	$debug = 0 unless defined $debug;

	# Choose a particular cddbp host.
	my $host = $param{Host};
	$host = '' unless defined $host;

	# Choose a particular cddbp port.
	my $port = $param{Port};
	$port = 8880 unless $port;

	# Choose a particular cddbp submission address.
	my $submit_to = $param{Submit_Address};
	$submit_to = 'freedb-submit@freedb.org' unless defined $submit_to;

	# Change the cddbp client name.
	my $client_name = $param{Client_Name};
	$client_name = 'CDDB.pm' unless defined $client_name;

	# Change the cddbp client version.
	my $client_version = $param{Client_Version};
	$client_version = $VERSION unless defined $client_version;

	# Whether to use utf-8 for submission
	my $utf8 = $param{Utf8};
	$utf8 = 1 unless defined $utf8;
	if ($utf8) {
		eval {
			require Encode;
			import Encode;
		};
		if ( $@ ) {
			carp 'Unable to load the Encode module, falling back to ascii';
			$utf8 = 0;
		}
	}

	eval 'sub encode { $_[1] };sub decode { $_[1] }' unless $utf8;

	# Change the cddbp protocol level.
	my $cddb_protocol = $param{Protocol_Version};
	$cddb_protocol = ($utf8 ? 6 : 1) unless defined $cddb_protocol;
	carp <<EOF if $utf8 and $cddb_protocol < 6;
You have requested protocol level $cddb_protocol. However,
utf-8 support is only available starting from level 6
EOF

	# Mac Freaks Got Spaces!  Augh!
	$login =~ s/\s+/_/g;

	my $self = bless {
		hostname      => $hostname,

lib/CDDB.pm  view on Meta::CPAN

  );

=head1 DESCRIPTION

CDDB protocol (cddbp) servers provide compact disc information for
programs that need it.  This allows such programs to display disc and
track titles automatically, and it provides extended information like
liner notes and lyrics.

This module provides a high-level Perl interface to cddbp servers.
With it, a Perl program can identify and possibly gather details about
a CD based on its "table of contents" (the disc's track times and
offsets).

Disc details have been useful for generating CD catalogs, naming mp3
files, printing CD liners, or even just playing discs in an automated
jukebox.

Despite the module's name, it connects to FreeDB servers by default.
This began at version 1.04, when cddb.com changed its licensing model
to support end-user applications, not third-party libraries.
Connections to cddb.com may still work, and patches are welcome to
maintain that functionality, but it's no longer officially supported.

=head1 PUBLIC METHODS

=over 4

=item new PARAMETERS

Creates a high-level interface to a cddbp server, returning a handle
to it.  The handle is not a filehandle.  It is an object.  The new()
constructor provides defaults for just about everything, but
everything is overrideable if the defaults aren't appropriate.

The interface will not actually connect to a cddbp server until it's
used, and a single cddbp interface may actually make several
connections (to possibly several servers) over the course of its use.

The new() constructor accepts several parameters, all of which have
reasonable defaults.

B<Host> and B<Port> describe the cddbp server to connect to.  These
default to 'freedb.freedb.org' and 8880, which is a multiplexor for
all the other freedb servers.

B<Utf8> is a boolean flag. If true, utf-8 will be used when submitting
CD info, and for interpreting the data reveived. This requires the
L<Encode> module (and probably perl version at least 5.8.0). The
default is true if the L<Encode> module can be loaded. Otherwise, it
will be false, meaning we fall back to ASCII.

B<Protocol_Version> sets the cddbp version to use.  CDDB.pm will not
connect to servers that don't support the version specified here.  The
requested protocol version defaults to 1 if B<Utf8> is off, and to 6
if it is on.

B<Login> is the login ID you want to advertise to the cddbp server.
It defaults to the login ID your computer assigns you, if that can be
determined.  The default login ID is determined by the presence of a
LOGNAME or USER environment variable, or by the getpwuid() function.
On Windows systems, it defaults to "win32usr" if no default method can
be found and no Login parameter is set.

B<Submit_Address> is the e-mail address where new disc submissions go.
This defaults to 'freedb-submit@freedb.org'. Note, that testing
submissions should be done via C<test-submit@freedb.org>.

B<Client_Name> and B<Client_Version> describe the client software used
to connect to the cddbp server.  They default to 'CDDB.pm' and
CDDB.pm's version number.  If developers change this, please consult
freedb's web site for a list of client names already in use.

B<Debug> enables verbose operational information on STDERR when set to
true.  It's normally not needed, but it can help explain why a program
is failing.  If someone finds a reproduceable bug, the Debug output
and a test program would be a big help towards having it fixed.  In
case of submission, if this flag is on, a copy of the submission
e-mail will be sent to the I<From> address.

=item get_genres

Takes no parameters.  Returns a list of genres known by the cddbp
server, or undef if there is a problem retrieving them.

=item calculate_id TOC

The cddb protocol defines an ID as a hash of track lengths and the
number of tracks, with an added checksum. The most basic information
required to calculate this is the CD table of contents (the CD-i track
offsets, in "MSF" [Minutes, Seconds, Frames] format).

Note however that there is no standard way to acquire this information
from a CD-ROM device.  Therefore this module does not try to read the
TOC itself.  Instead, developers must combine CDDB.pm with a CD
library which works with their system.  The AudioCD suite of modules
is recommended: it has system specific code for MacOS, Linux and
FreeBSD.  CDDB.pm's author has used external programs like dagrab to
fetch the offsets.  Actual CDs aren't always necessary: the author has
heard of people generating TOC information from mp3 file lengths.

That said, see parse_cdinfo() for a routine to parse "cdinfo" output
into a table of contents list suitable for calculate_id().

calculate_id() accepts TOC information as a list of strings.  Each
string contains four fields, separated by whitespace:

offset 0: the track number

Track numbers start with 1 and run sequentially through the number of
tracks on a disc.  Note: data tracks count on hybrid audio/data CDs.

CDDB.pm understands two special track numbers.  Track 999 holds the
lead-out information, which is required by the cddb protocol.  Track
1000 holds information about errors which have occurred while
physically reading the disc.

offset 1: the track start time, minutes field

Tracks are often addressed on audio CDs using "MSF" offsets.  This
stands for Minutes, Seconds, and Frames (fractions of a second).  The