view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        Artist      => 'Various',
        DiscTitle   => 'Cartoon Classics',
        Offsets     => $disc_info->{offsets},   # array reference
        TrackTitles => $disc_info->{ttitles},   # array reference
        From        => 'login@host.domain.etc', # will try to determine
      );

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.

PUBLIC METHODS
    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.

        Host and 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.

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

        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 Utf8 is off, and to
        6 if it is on.

        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.

        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 "test-submit@freedb.org".

        Client_Name and 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.

        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 *From* address.

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

    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