.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CDDB 3pm" .TH CDDB 3pm "2013-08-15" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CDDB.pm \- a high\-level interface to cddb protocol servers (freedb and CDDB) .SH "VERSION" .IX Header "VERSION" version 1.222 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CDDB; \& \& ### Connect to the cddbp server. \& my $cddbp = new CDDB( \& Host => \*(Aqfreedb.freedb.org\*(Aq, # default \& Port => 8880, # default \& Login => $login_id, # defaults to %ENV\*(Aqs \& ) or die $!; \& \& ### Retrieve known genres. \& my @genres = $cddbp\->get_genres(); \& \& ### Calculate cddbp ID based on MSF info. \& my @toc = ( \& \*(Aq1 0 2 37\*(Aq, # track, CD\-i MSF (space\-delimited) \& \*(Aq999 1 38 17\*(Aq, # lead\-out track MSF \& \*(Aq1000 0 0 Error!\*(Aq, # error track (don\*(Aqt include if ok) \& ); \& my ( \& $cddbp_id, # used for further cddbp queries \& $track_numbers, # padded with 0\*(Aqs (for convenience) \& $track_lengths, # length of each track, in MM:SS format \& $track_offsets, # absolute offsets (used for further cddbp queries) \& $total_seconds # total play time, in seconds (for cddbp queries) \& ) = $cddbp\->calculate_id(@toc); \& \& ### Query discs based on cddbp ID and other information. \& my @discs = $cddbp\->get_discs($cddbp_id, $track_offsets, $total_seconds); \& foreach my $disc (@discs) { \& my ($genre, $cddbp_id, $title) = @$disc; \& } \& \& ### Query disc details (usually done with get_discs() information). \& my $disc_info = $cddbp\->get_disc_details($genre, $cddbp_id); \& my $disc_time = $disc_info\->{\*(Aqdisc length\*(Aq}; \& my $disc_id = $disc_info\->{discid}; \& my $disc_title = $disc_info\->{dtitle}; \& my @track_offsets = @{$disc_info\->{offsets}}; \& my @track_seconds = @{$disc_info\->{seconds}}; \& my @track_titles = @{$disc_info\->{ttitles}}; \& # other information may be returned... explore! \& \& ### Submit a disc via e\-mail. (Requires MailTools) \& \& die "can\*(Aqt submit a disc (no mail modules; see README)" \& unless $cddbp\->can_submit_disc(); \& \& # These are useful for prompting the user to fix defaults: \& print "I will send mail through: ", $cddbp\->get_mail_host(), "\en"; \& print "I assume your e\-mail address is: ", $cddbp\->get_mail_address(), "\en"; \& \& # Actually submit a disc record. \& $cddbp\->submit_disc( \& Genre => \*(Aqclassical\*(Aq, \& Id => \*(Aqb811a20c\*(Aq, \& Artist => \*(AqVarious\*(Aq, \& DiscTitle => \*(AqCartoon Classics\*(Aq, \& Offsets => $disc_info\->{offsets}, # array reference \& TrackTitles => $disc_info\->{ttitles}, # array reference \& From => \*(Aqlogin@host.domain.etc\*(Aq, # will try to determine \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1CDDB\s0 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. .PP This module provides a high-level Perl interface to cddbp servers. With it, a Perl program can identify and possibly gather details about a \s-1CD\s0 based on its \*(L"table of contents\*(R" (the disc's track times and offsets). .PP Disc details have been useful for generating \s-1CD\s0 catalogs, naming mp3 files, printing \s-1CD\s0 liners, or even just playing discs in an automated jukebox. .PP 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. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .IP "new \s-1PARAMETERS\s0" 4 .IX 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 \fInew()\fR constructor provides defaults for just about everything, but everything is overrideable if the defaults aren't appropriate. .Sp 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. .Sp The \fInew()\fR constructor accepts several parameters, all of which have reasonable defaults. .Sp \&\fBHost\fR and \fBPort\fR 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. .Sp \&\fBUtf8\fR is a boolean flag. If true, utf\-8 will be used when submitting \&\s-1CD\s0 info, and for interpreting the data reveived. This requires the Encode module (and probably perl version at least 5.8.0). The default is true if the Encode module can be loaded. Otherwise, it will be false, meaning we fall back to \s-1ASCII.\s0 .Sp \&\fBProtocol_Version\fR sets the cddbp version to use. \s-1CDDB\s0.pm will not connect to servers that don't support the version specified here. The requested protocol version defaults to 1 if \fBUtf8\fR is off, and to 6 if it is on. .Sp \&\fBLogin\fR is the login \s-1ID\s0 you want to advertise to the cddbp server. It defaults to the login \s-1ID\s0 your computer assigns you, if that can be determined. The default login \s-1ID\s0 is determined by the presence of a \&\s-1LOGNAME\s0 or \s-1USER\s0 environment variable, or by the \fIgetpwuid()\fR function. On Windows systems, it defaults to \*(L"win32usr\*(R" if no default method can be found and no Login parameter is set. .Sp \&\fBSubmit_Address\fR 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 \f(CW\*(C`test\-submit@freedb.org\*(C'\fR. .Sp \&\fBClient_Name\fR and \fBClient_Version\fR describe the client software used to connect to the cddbp server. They default to '\s-1CDDB\s0.pm' and \&\s-1CDDB\s0.pm's version number. If developers change this, please consult freedb's web site for a list of client names already in use. .Sp \&\fBDebug\fR enables verbose operational information on \s-1STDERR\s0 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 \fIFrom\fR address. .IP "get_genres" 4 .IX 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. .IP "calculate_id \s-1TOC\s0" 4 .IX Item "calculate_id TOC" The cddb protocol defines an \s-1ID\s0 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 \s-1CD\s0 table of contents (the CD-i track offsets, in \*(L"\s-1MSF\*(R"\s0 [Minutes, Seconds, Frames] format). .Sp 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 \&\s-1TOC\s0 itself. Instead, developers must combine \s-1CDDB\s0.pm with a \s-1CD\s0 library which works with their system. The AudioCD suite of modules is recommended: it has system specific code for MacOS, Linux and FreeBSD. \s-1CDDB\s0.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 \s-1TOC\s0 information from mp3 file lengths. .Sp That said, see \fIparse_cdinfo()\fR for a routine to parse \*(L"cdinfo\*(R" output into a table of contents list suitable for \fIcalculate_id()\fR. .Sp \&\fIcalculate_id()\fR accepts \s-1TOC\s0 information as a list of strings. Each string contains four fields, separated by whitespace: .Sp offset 0: the track number .Sp 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. .Sp \&\s-1CDDB\s0.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. .Sp offset 1: the track start time, minutes field .Sp Tracks are often addressed on audio CDs using \*(L"\s-1MSF\*(R"\s0 offsets. This stands for Minutes, Seconds, and Frames (fractions of a second). The combination pinpoints the exact disc frame where a song starts. .Sp Field 1 contains the M part of \s-1MSF. \s0 It is ignored for error tracks, but it still must contain a number. Zero is suggested. .Sp offset 2: the track start time, seconds field .Sp This field contains the S part of \s-1MSF. \s0 It is ignored for error tracks, but it still must contain a number. Zero is suggested. .Sp offset 3: the track start time, frames field .Sp This field contains the F part of \s-1MSF. \s0 For error tracks, it contains a description of the error. .Sp Example track file. Note: the comments should not appear in the file. .Sp .Vb 5 \& 1 0 2 37 # track 1 starts at 00:02 and 37 frames \& 2 1 38 17 # track 2 starts at 01:38 and 17 frames \& 3 11 57 30 # track 3 starts at 11:57 and 30 frames \& ... \& 999 75 16 5 # leadout starts at 75:16 and 5 frames .Ve .Sp Track 1000 should not be present if everything is okay: .Sp .Vb 1 \& 1000 0 0 Error reading TOC: no disc in drive .Ve .Sp In scalar context, \fIcalculate_id()\fR returns just the cddbp \s-1ID. \s0 In a list context, it returns an array containing the following values: .Sp .Vb 7 \& ( \& $cddbp_id, \& $track_numbers, \& $track_lengths, \& $track_offsets, \& $total_seconds \& ) = $cddbp\->calculate_id(@toc); \& \& print( \& "cddbp ID = $cddbp_id\en", # b811a20c \& "track numbers = @$track_numbers\en", # 001 002 003 ... \& "track lengths = @$track_lengths\en", # 01:36 10:19 04:29 ... \& "track offsets = @$track_offsets\en", # 187 7367 53805 ... \& "total seconds = $total_seconds\en", # 4514 \& ); .Ve .Sp \&\s-1CDDBP_ID\s0 .Sp The 0th returned value is the hashed cddbp \s-1ID,\s0 required for any queries or submissions involving this disc. .Sp \&\s-1TRACK_NUMBERS\s0 .Sp The 1st returned value is a reference to a list of track numbers, one for each track (excluding the lead-out), padded to three characters with leading zeroes. These values are provided for convenience, but they are not required by cddbp servers. .Sp \&\s-1TRACK_LENGTHS\s0 .Sp The 2nd returned value is a reference to a list of track lengths, one for each track (excluding the lead-out), in \s-1HH:MM\s0 format. These values are returned as a convenience. They are not required by cddbp servers. .Sp \&\s-1TRACK_OFFSETS\s0 .Sp The 3rd returned value is a reference to a list of absolute track offsets, in frames. They are calculated from the \s-1MSF\s0 values, and they are required by \fIget_discs()\fR and \fIsubmit_disc()\fR. .Sp \&\s-1TOTAL_SECONDS\s0 .Sp The 4th and final value is the total playing time for the \s-1CD,\s0 in seconds. The \fIget_discs()\fR function needs it. .IP "get_discs \s-1CDDBP_ID, TRACK_OFFSETS, TOTAL_SECONDS\s0" 4 .IX Item "get_discs CDDBP_ID, TRACK_OFFSETS, TOTAL_SECONDS" \&\fIget_discs()\fR asks the cddbp server for a summary of all the CDs matching a given cddbp \s-1ID,\s0 track offsets, and total playing time. These values can be retrieved from \fIcalculade_id()\fR. .Sp .Vb 4 \& my @id_info = $cddbp\->calculate_id(@toc); \& my $cddbp_id = $id_info\->[0]; \& my $track_offsets = $id_info\->[3]; \& my $total_seconds = $id_info\->[4]; .Ve .Sp \&\fIget_discs()\fR returns an array of matching discs, each of which is represented by an array reference. It returns an empty array if the query succeeded but did not match, and it returns undef on error. .Sp .Vb 9 \& my @discs = $cddbp\->get_discs( $cddbp_id, $track_offsets, $total_seconds ); \& foreach my $disc (@discs) { \& my ($disc_genre, $disc_id, $disc_title) = @$disc; \& print( \& "disc id = $disc_id\en", \& "disc genre = $disc_genre\en", \& "disc title = $disc_title\en", \& ); \& } .Ve .Sp \&\s-1DISC_GENRE\s0 is the genre this disc falls into, as determined by whoever submitted or last edited the disc. The genre is required when requesting a disc's details. See \fIget_genres()\fR for how to retrieve a list of cddbp genres. .Sp \&\s-1CDDBP_ID\s0 is the cddbp \s-1ID\s0 of this disc. Cddbp servers perform fuzzy matches, returning near misses as well as direct hits on a cddbp \s-1ID,\s0 so knowing the exact \s-1ID\s0 for a disc is important when submitting changes or requesting a particular near\-miss' details. .Sp \&\s-1DISC_TITLE\s0 is the disc's title, which may help a human to pick the correct disc out of several close mathches. .IP "get_discs_by_toc \s-1TOC\s0" 4 .IX Item "get_discs_by_toc TOC" This function acts as a macro, combining \fIcalculate_id()\fR and \&\fIget_discs()\fR calls into one function. It takes the same parameters as \&\fIcalculate_id()\fR, and it returns the same information as \fIget_discs()\fR. .IP "get_discs_by_query \s-1QUERY_STRING\s0" 4 .IX Item "get_discs_by_query QUERY_STRING" Fetch discs by a pre-built cddbp query string. Some disc querying programs report this string, and \fIget_discs_by_query()\fR is a convenient way to use that. .Sp Cddb protocol query strings look like: .Sp .Vb 1 \& cddb query $cddbp_id $track_count @offsets $total_seconds .Ve .IP "get_disc_details \s-1DISC_GENRE, CDDBP_ID\s0" 4 .IX Item "get_disc_details DISC_GENRE, CDDBP_ID" This function fetches a disc's detailed information from a cddbp server. It takes two parameters: the \s-1DISC_GENRE\s0 and the \s-1CDDP_ID.\s0 These parameters usually come from a call to \fIget_discs()\fR. .Sp The disc's details are returned in a reference to a fairly complex hash. It includes information normally stored in comments. The most common entries in this hash include: .Sp .Vb 1 \& $disc_details = get_disc_details( $disc_genre, $cddbp_id ); .Ve .Sp \&\f(CW$disc_details\fR\->{\*(L"disc length\*(R"} .Sp The disc length is commonly stored in the form \*(L"### seconds\*(R", where ### is the disc's total playing time in seconds. It may hold other time formats. .Sp \&\f(CW$disc_details\fR\->{discid} .Sp This is a rehash (get it?) of the cddbp \s-1ID. \s0 It should match the \&\s-1CDDBP_ID\s0 given to \fIget_disc_details()\fR. .Sp \&\f(CW$disc_details\fR\->{dtitle} .Sp This is the disc's title. I do not know whether it will match the one returned by \fIget_discs()\fR. .Sp \&\f(CW$disc_details\fR\->{offsets} .Sp This is a reference to a list of absolute disc track offsets, similar to the \s-1TRACK_OFFSETS\s0 returned by \fIcalculate_id()\fR. .Sp \&\f(CW$disc_details\fR\->{seconds} .Sp This is a reference to a list of track length, in seconds. .Sp \&\f(CW$disc_details\fR\->{ttitles} .Sp This is a reference to a list of track titles. These are the droids you are looking for. .Sp \&\f(CW$disc_details\fR\->{\*(L"processed by\*(R"} .Sp This is a comment field identifying the name and version of the cddbp server which accepted and entered the disc record into the database. .Sp \&\f(CW$disc_details\fR\->{revision} .Sp This is the disc record's version number, used as a sanity check (semaphore?) to prevent simultaneous revisions. Revisions start at 0 for new submissions and are incremented for every correction. It is the responsibility of the submitter (be it a person or a program using \&\s-1CDDB\s0.pm) to provide a correct revision number. .Sp \&\f(CW$disc_details\fR\->{\*(L"submitted via\*(R"} .Sp This is the name and version of the software that submitted this cddbp record. The main intention is to identify records that are submitted by broken software so they can be purged or corrected. .Sp \&\f(CW$disc_details\fR\->{xmcd_record} .Sp The xmcd_record field contains a copy of the entire unprocessed cddbp response that generated all the other fields. .Sp \&\f(CW$disc_details\fR\->{genre} .Sp This is merely a copy of \s-1DISC_GENRE,\s0 since it's otherwise not possible to determine it from the hash. .IP "parse_xmcd_file \s-1XMCD_FILE_CONTENTS,\s0 [\s-1GENRE\s0]" 4 .IX Item "parse_xmcd_file XMCD_FILE_CONTENTS, [GENRE]" Parses an array ref of lines read from an \s-1XMCD\s0 file into the disc_details hash described above. If the \s-1GENRE\s0 parameter is set it will be included in disc_details. .IP "can_submit_disc" 4 .IX Item "can_submit_disc" Returns true or false, depending on whether \s-1CDDB\s0.pm has enough dependent modules to submit discs. If it returns false, you are missing Mail::Internet, Mail::Header, or MIME::QuotedPrint. .IP "get_mail_address" 4 .IX Item "get_mail_address" Returns what \s-1CDDB\s0.pm thinks your e\-mail address is, or what it was last set to. It was added to fetch the default e\-mail address so users can see it and have an opportunity to correct it. .Sp .Vb 7 \& my $mail_from = $cddb\->get_mail_address(); \& print "New e\-mail address (or blank to keep <$mail_from>): "; \& my $new_mail_from = ; \& $new_mail_from =~ s/^\es+//; \& $new_mail_from =~ s/\es+$//; \& $new_mail_from =~ s/\es+/ /g; \& $mail_from = $new_mail_from if length $new_mail_from; \& \& $cddbp\->submit_disc( \& ..., \& From => $mail_from, \& ); .Ve .IP "get_mail_host" 4 .IX Item "get_mail_host" Returns what \s-1CDDB\s0.pm thinks your \s-1SMTP\s0 host is, or what it was last set to. It was added to fetch the default e\-mail transfer host so users can see it and have an opportunity to correct it. .Sp .Vb 7 \& my $mail_host = $cddb\->get_mail_host(); \& print "New e\-mail host (or blank to keep <$mail_host>): "; \& my $new_mail_host = ; \& $new_mail_host =~ s/^\es+//; \& $new_mail_host =~ s/\es+$//; \& $new_mail_host =~ s/\es+/ /g; \& $mail_host = $new_mail_host if length $new_mail_host; \& \& $cddbp\->submit_disc( \& ..., \& Host => $mail_host, \& ); .Ve .IP "parse_cdinfo \s-1CDINFO_FILE\s0" 4 .IX Item "parse_cdinfo CDINFO_FILE" Generates a table of contents suitable for \fIcalculate_id()\fR based on the output of a program called \*(L"cdinfo\*(R". \s-1CDINFO_FILE\s0 may either be a text file, or it may be the cdinfo program itself. .Sp .Vb 2 \& my @toc = parse_cdinfo("cdinfo.txt"); # read cdinfo.txt \& my @toc = parse_cdinfo("cdinfo|"); # run cdinfo directly .Ve .Sp The table of contents can be passed directly to \fIcalculate_id()\fR. .IP "submit_disc \s-1DISC_DETAILS\s0" 4 .IX Item "submit_disc DISC_DETAILS" \&\fIsubmit_disc()\fR submits a disc record to a cddbp server. Currently it only uses e\-mail, although it will try different ways to send that. It returns true or false depending on whether it was able to send the submission e\-mail. .Sp The rest of \s-1CDDB\s0.pm will work without the ability to submit discs. While cddbp submissions are relatively rare, most \s-1CD\s0 collections will have one or two discs not present in the system. Please submit new discs to the system: the amazing number of existing discs got there because others submitted them before you needed them. .Sp \&\fIsubmit_disc()\fR takes six required parameters and two optional ones. The parameters are named, like hash elements, and can appear in any order. .Sp Genre => \s-1DISC_GENRE\s0 .Sp This is the disc's genre. It must be one of the genres that the server knows. See \fIget_genres()\fR. .Sp Id => \s-1CDDBP_ID\s0 .Sp This is the cddbp \s-1ID\s0 that identifies the disc. It should come from \&\fIcalculate_id()\fR if this is a new submission, or from \fIget_disc_details()\fR if this is a revision. .Sp Artist => \s-1DISC_ARTIST\s0 .Sp This is the disc's artist, a freeform text field describing the party responsible for the album. It will need to be entered from the disc's notes for new submissions, or it can come from \fIget_disc_details()\fR on subsequent revisions. .Sp DiscTitle => \s-1DISC_TITLE\s0 .Sp This is the disc's title, a freeform text field describing the album. It must be entered from the disc's notes for new submissions. It can come from \fIget_disc_details()\fR on subsequent revisions. .Sp Offsets => \s-1TRACK_OFFSETS\s0 .Sp This is a reference to an array of absolute track offsets, as provided by \fIcalculate_id()\fR. .Sp TrackTitles => \s-1TRACK_TITLES\s0 .Sp This is a reference to an array of track titles, either entered by a human or provided by \fIget_disc_details()\fR. .Sp From => \s-1EMAIL_ADDRESS\s0 .Sp This is the disc submitter's e\-mail address. It's not required, and \&\s-1CDDB\s0.pm will try to figure one out on its own if an address is omitted. It may be more reliable to provide your own, however. .Sp The default return address may not be a deliverable one, especially if \&\s-1CDDB\s0.pm is being used on a dial-up machine that isn't running its own \&\s-1MTA. \s0 If the current machine has its own \s-1MTA,\s0 problems still may occur if the machine's Internet address changes. .Sp Host => \s-1SMTP_HOST\s0 .Sp This is the \s-1SMTP\s0 host to contact when sending mail. It's not required, and \s-1CDDB\s0.pm will try to figure one out on its own. It will look at the \s-1SMTPHOSTS\s0 environment variable is not defined, it will try \&'mail' and 'localhost' before finally failing. .Sp Revision => \s-1REVISION\s0 .Sp The revision number. Should be 1 for new submissions, and one higher than the previous one for updates. The previous revision number is available as the \f(CW\*(C`revision\*(C'\fR field in the hash returned by \&\fIget_disc_details()\fR. .SH "PRIVATE METHODS" .IX Header "PRIVATE METHODS" Documented as being not documented. .SH "EXAMPLES" .IX Header "EXAMPLES" Please see the cddb.t program in the t (tests) directory. It exercises every aspect of \s-1CDDB\s0.pm, including submissions. .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" \&\s-1CDDB\s0.pm uses standard Perl modules. It has been tested at one point or another on \s-1OS/2,\s0 MacOS and FreeBSD systems, as well as the systems listed at: .PP .Vb 1 \& http://testers.cpan.org/search?request=dist&dist=CDDB .Ve .PP If you want to submit disc information to the \s-1CDDB,\s0 you will need to install two other modules: .PP .Vb 2 \& Mail::Internet will allow CDDB.pm to send email submissions, and it \& automagically includes Mail::Header. \& \& MIME::QuotedPrint will allow CDDB.pm to send non\-ASCII text \& unscathed. Currently only ISO\-8859\-1 and ASCII are supported. .Ve .PP All other features will work without these modules. .SH "KNOWN TEST FAILURES" .IX Header "KNOWN TEST FAILURES" The last test in the \*(L"make test\*(R" suite will try to send a sample submission to the \s-1CDDB\s0 if MailTools is present. It expects to find an \&\s-1SMTP\s0 host in the \s-1SMTPHOST\s0 environment variable. It will fall back to \&\*(L"mail\*(R" if \s-1SMTPHOST\s0 doesn't exist. If neither works, the test will be skipped. To see why it's skipped: .PP .Vb 1 \& make test TEST_VERBOSE=1 .Ve .PP Some of the tests (most notably numbers 25, 27 and 29) compare data returned by a cddbp server against a stored copy of a previous query. These tests fail occasionally since the database is constantly in flux. Starting with version 1.00, the test program uses fuzzy comparisons that should fail less. Version 1.04 saw even fuzzier comparisons. Please report any problems so they can be fixed. .SH "LINKS" .IX Header "LINKS" .SS "\s-1BUG TRACKER\s0" .IX Subsection "BUG TRACKER" https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=CDDB .SS "\s-1REPOSITORY\s0" .IX Subsection "REPOSITORY" http://github.com/rcaputo/cddb\-perl http://gitorious.org/cddb\-freedb\-perl .SS "\s-1OTHER RESOURCES\s0" .IX Subsection "OTHER RESOURCES" http://search.cpan.org/dist/CDDB/ .SH "CONTACT AND COPYRIGHT" .IX Header "CONTACT AND COPYRIGHT" Copyright 1998\-2013 Rocco Caputo. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.