NAME
    libID3 - ID3 Parsing Library

SYNOPSIS
    Library for parsing ID3 tags from files or sections of memory.

DESCRIPTION
    MP3 files contain information such as Artist, Title, and other
    attributes. This library can extract those tags. For more information
    see http://id3.org.

Where do I get it from?
    You can get it from http://software.tangent.org/download/ via the web.

What sort of license does it have?
    You are pretty much free to use it as you please. Check out the License
    file with the distribution for more details. (Its very BSD like)

How can I make suggestions for it?
    Send email to brian@tangent.org

How do I install it?
     Read the INSTALL file that comes along with the module. 

So what are the directives?
    ID3 * create_ID3(ID3 *);
        This will create an ID3 structure to be used with other methods.

    int destroy_ID3(ID3 *blob);
        Cleans up the memory allocation of an ID3 structure.

    int parse_file_ID3(ID3 *info, unsigned char *filename);
        Pass in a filename with a created ID3 structure. This function will
        then fill the ID3 structure for you.

    int parse_blob_ID3(ID3 *info, unsigned char *blob, size_t blob_length);
        Pass in a blobk with a created ID3 structure. This function will
        then fill the ID3 structure for you.

    void set_memory_ID3(ID3 *info, const char *ptr, size_t size);
        Provide your own memory buffer for the ID3 tag.

    void set_flags_ID3(ID3 *info, id3flags mask);
        Set which tags you want to have parsed. See the tags section later
        in this document to see which tags you can use.

    int ID3_to_file(unsigned char *filename, unsigned char *newfile);
        Pass in a filename to a file with an ID3 tag, and a new filename.
        The file created will have just the ID3 information in it.

ID3Flags
    You can use the following flags to control what is parsed. ALL_TAG is
    used by default.

    TITLE_TAG
        Title of the track

    ARTIST_TAG
        Performing Artist

    ALBUM_TAG
        Album Title

    YEAR_TAG
        Year the track was published

    COMMENT_TAG
        Comment for the track.

    TRACK_TAG
        Track on the album

    GENRE_TAG
        Music genre.

    ENCODER_TAG
        Encoder used for the track.

    VERSION_TAG
        Track's version

    VERSION1_TAG
        Handy TAG for just pulling all of the version one tags
        (TITLE_TAG|ARTIST_TAG|ALBUM_TAG|YEAR_TAG|COMMENT_TAG|TRACK_TAG|GENRE
        _TAG)

    ALL_TAG
        Default mask used, fills all tags.

Structure of ID3.
    What follows is the public members of the ID3 tag.

    struct ID3 {

            char version[VERSION_SIZE]; //It will never be this large!
        
            char *title;
        
            size_t title_size;
        
            char *artist;
        
            size_t artist_size;
        
            char *album;
        
            size_t album_size;
        
            char *year;
        
            size_t year_size;
        
            char *comment;
        
            size_t comment_size;
        
            char *track;
        
            size_t track_size;
        
            char *genre;
        
            size_t genre_size;
        
            char *encoder;
        
            size_t encoder_size;
        
            char *buffer;
        
            void (*processor)(ID3 *info, const char *name, const char *ptr, size_t length);
        
            void *passable;        // Void pointer you can use in your processor() callback function
        
            size_t tag_length;     // Length of the actual tag
        
            id3flags mask;
        
            id3flags mask_found;
    };

Call back
    By default an internal function is used to handle data from the tag (it
    places the data in the ID3 structure). You can though supply your own
    function to do this work. See test.c for an example of this. This
    prototype for this is:

    void (*processor)(ID3 *info, const char *name, const char *ptr, size_t
    length);

Additional Tags
    So you want to extract tags that are not found in the ID3 structure? Use
    the callback function feature described above.

RETURN VALUES
    All create and parse messages return values other then zero as an error.
    These are not currently defined.

SEE ALSO
    test.c in the distribution, tagpuller(1)

AUTHOR
    Brian Aker, <brian@tangent.org>

COPYRIGHT AND LICENSE
    Copyright 2004 by Brian Aker

    Please see the license file for information (if you need a different
    license please contact the author).