org.jaudiotagger.tag
Interface Tag

All Known Implementing Classes:
AbstractID3v2Tag, AbstractTag, FlacTag, GenericTag, ID3v11Tag, ID3v1Tag, ID3v22Tag, ID3v23Tag, ID3v24Tag, Mp4Tag, VorbisCommentTag

public interface Tag

This interface represents the basic data structure for the default audiolibrary functionality.

Some audio file tagging systems allow to specify multiple values for one type of information. The artist for example. Some songs may be a cooperation of two or more artists. Sometimes a tagging user wants to specify them in the tag without making one long text string.
For that kind of fields, the commonly used fields have adequate methods for adding values. But it is possible the underlying implementation does not support that kind of storing multiple values.

Code Examples:

 
 AudioFile file = AudioFileIO.read(new File("C:\\test.mp3"));
 
 Tag tag = file.getTag();
 
 

Author:
Raphaël Slinckx

Method Summary
 void add(TagField field)
          Adds a tagfield to the structure.
 void addAlbum(java.lang.String album)
          Adds an album to the tag.
 void addArtist(java.lang.String artist)
          Adds an artist to the tag.
 void addComment(java.lang.String comment)
          Adds a comment to the tag.
 void addGenre(java.lang.String genre)
          Adds a genre to the tag.
 void addTitle(java.lang.String title)
          Adds a title to the tag.
 void addTrack(java.lang.String track)
          Adds a track to the tag.
 void addYear(java.lang.String year)
          Adds a year to the Tag.
 TagField createTagField(TagFieldKey genericKey, java.lang.String value)
          Create a new TagField based on generic key
 void deleteTagField(TagFieldKey tagFieldKey)
          Delete any instance of tag fields with this key
 java.util.List<TagField> get(java.lang.String id)
          Returns a list of TagField objects whose "id" is the specified one.
 java.util.List<TagField> get(TagFieldKey id)
          Returns a list of TagField objects whose "id" is the specified one.
 java.util.List<TagField> getAlbum()
           
 java.util.List<TagField> getArtist()
           
 java.util.List<TagField> getComment()
           
 int getFieldCount()
          Return the number of fields
 java.util.Iterator getFields()
          Iterator over all the fields within the tag, handle multiple fields with the same id
 java.lang.String getFirst(java.lang.String id)
          Retrieve the first value that exists for this key
 java.lang.String getFirst(TagFieldKey id)
          Retrieve String value of first tagfield that exists for this key
 java.lang.String getFirstAlbum()
           
 java.lang.String getFirstArtist()
           
 java.lang.String getFirstComment()
           
 TagField getFirstField(java.lang.String id)
          Retrieve the first tagfield that exists for this key
 java.lang.String getFirstGenre()
           
 java.lang.String getFirstTitle()
           
 java.lang.String getFirstTrack()
           
 java.lang.String getFirstYear()
           
 java.util.List<TagField> getGenre()
           
 java.util.List<TagField> getTitle()
           
 java.util.List<TagField> getTrack()
           
 java.util.List<TagField> getYear()
           
 boolean hasCommonFields()
          Returns true, if at least one of the contained fields is a common field (TagField.isCommon()).
 boolean hasField(java.lang.String id)
          Determines whether the tag has at least one field with the specified "id".
 boolean isEmpty()
          Determines whether the tag has no fields specified.
 void set(TagField field)
           
 void setAlbum(java.lang.String s)
           
 void setArtist(java.lang.String s)
           
 void setComment(java.lang.String s)
           
 boolean setEncoding(java.lang.String enc)
           
 void setGenre(java.lang.String s)
           
 void setTitle(java.lang.String s)
           
 void setTrack(java.lang.String s)
           
 void setYear(java.lang.String s)
           
 java.lang.String toString()
           
 

Method Detail

add

void add(TagField field)
         throws FieldDataInvalidException
Adds a tagfield to the structure.

It is not recommended to use this method for normal use of the audiolibrary. The developer will circumvent the underlying implementation. For example, if one adds a field with the field id "TALB" for an mp3 file, and the given TagField implementation does not return a text field compliant data with TagField.getRawContent() other software and the audio library won't read the file correctly, if they do read it at all.
So for short:

  • The field is stored withoud validation
  • No conversion of data is perfomed
  • Parameters:
    field - The field to add.
    Throws:
    FieldDataInvalidException

    addAlbum

    void addAlbum(java.lang.String album)
                  throws FieldDataInvalidException
    Adds an album to the tag.

    Parameters:
    album - Album description
    Throws:
    FieldDataInvalidException

    addArtist

    void addArtist(java.lang.String artist)
                   throws FieldDataInvalidException
    Adds an artist to the tag.

    Parameters:
    artist - Artist's name
    Throws:
    FieldDataInvalidException

    addComment

    void addComment(java.lang.String comment)
                    throws FieldDataInvalidException
    Adds a comment to the tag.

    Parameters:
    comment - Comment.
    Throws:
    FieldDataInvalidException

    addGenre

    void addGenre(java.lang.String genre)
                  throws FieldDataInvalidException
    Adds a genre to the tag.

    Parameters:
    genre - Genre
    Throws:
    FieldDataInvalidException

    addTitle

    void addTitle(java.lang.String title)
                  throws FieldDataInvalidException
    Adds a title to the tag.

    Parameters:
    title - Title
    Throws:
    FieldDataInvalidException

    addTrack

    void addTrack(java.lang.String track)
                  throws FieldDataInvalidException
    Adds a track to the tag.

    Parameters:
    track - Track
    Throws:
    FieldDataInvalidException

    addYear

    void addYear(java.lang.String year)
                 throws FieldDataInvalidException
    Adds a year to the Tag.

    Parameters:
    year - Year
    Throws:
    FieldDataInvalidException

    get

    java.util.List<TagField> get(java.lang.String id)
    Returns a list of TagField objects whose "id" is the specified one.

    Parameters:
    id - The field id.
    Returns:
    A list of TagField objects with the given "id".

    getAlbum

    java.util.List<TagField> getAlbum()
    Returns:

    getArtist

    java.util.List<TagField> getArtist()
    Returns:

    getComment

    java.util.List<TagField> getComment()
    Returns:

    getGenre

    java.util.List<TagField> getGenre()
    Returns:

    getTitle

    java.util.List<TagField> getTitle()
    Returns:

    getTrack

    java.util.List<TagField> getTrack()
    Returns:

    getYear

    java.util.List<TagField> getYear()
    Returns:

    getFirstAlbum

    java.lang.String getFirstAlbum()
    Returns:

    getFirstArtist

    java.lang.String getFirstArtist()
    Returns:

    getFirstComment

    java.lang.String getFirstComment()
    Returns:

    getFirstGenre

    java.lang.String getFirstGenre()
    Returns:

    getFirstTitle

    java.lang.String getFirstTitle()
    Returns:

    getFirstTrack

    java.lang.String getFirstTrack()
    Returns:

    getFirstYear

    java.lang.String getFirstYear()
    Returns:

    hasCommonFields

    boolean hasCommonFields()
    Returns true, if at least one of the contained fields is a common field (TagField.isCommon()).

    Returns:
    true if a common field is present.

    hasField

    boolean hasField(java.lang.String id)
    Determines whether the tag has at least one field with the specified "id".

    Parameters:
    id - The field id to look for.
    Returns:
    true if tag contains a TagField with the given id.

    isEmpty

    boolean isEmpty()
    Determines whether the tag has no fields specified.

    Returns:
    true if tag contains no field.

    set

    void set(TagField field)
             throws FieldDataInvalidException
    Parameters:
    field -
    Throws:
    FieldDataInvalidException

    setAlbum

    void setAlbum(java.lang.String s)
                  throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setArtist

    void setArtist(java.lang.String s)
                   throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setComment

    void setComment(java.lang.String s)
                    throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setGenre

    void setGenre(java.lang.String s)
                  throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setTitle

    void setTitle(java.lang.String s)
                  throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setTrack

    void setTrack(java.lang.String s)
                  throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    setYear

    void setYear(java.lang.String s)
                 throws FieldDataInvalidException
    Parameters:
    s -
    Throws:
    FieldDataInvalidException

    createTagField

    TagField createTagField(TagFieldKey genericKey,
                            java.lang.String value)
                            throws KeyNotFoundException,
                                   FieldDataInvalidException
    Create a new TagField based on generic key

    Only textual data supported at the moment. The genericKey will be mapped to the correct implementation key and return a TagField.

    Parameters:
    genericKey - is the generic key
    value - to store
    Returns:
    Throws:
    KeyNotFoundException
    FieldDataInvalidException

    getFirst

    java.lang.String getFirst(java.lang.String id)
    Retrieve the first value that exists for this key

    Parameters:
    id -
    Returns:

    getFirst

    java.lang.String getFirst(TagFieldKey id)
                              throws KeyNotFoundException
    Retrieve String value of first tagfield that exists for this key

    Parameters:
    id -
    Returns:
    String value or empty string
    Throws:
    KeyNotFoundException

    getFirstField

    TagField getFirstField(java.lang.String id)
    Retrieve the first tagfield that exists for this key

    Can be used to retrieve fields with any identifier, useful if the identifier is not within the jaudiotagger enum

    Parameters:
    id - audio specific key
    Returns:
    tag field or null if doesnt exist

    toString

    java.lang.String toString()
    Overrides:
    toString in class java.lang.Object

    deleteTagField

    void deleteTagField(TagFieldKey tagFieldKey)
                        throws KeyNotFoundException
    Delete any instance of tag fields with this key

    Parameters:
    tagFieldKey -
    Throws:
    KeyNotFoundException

    getFields

    java.util.Iterator getFields()
    Iterator over all the fields within the tag, handle multiple fields with the same id

    Returns:
    iterator over whole list

    getFieldCount

    int getFieldCount()
    Return the number of fields

    Fields with the same identifiers are counted seperately i.e two title fields would contribute two to the count

    Returns:
    total number of fields

    setEncoding

    boolean setEncoding(java.lang.String enc)
                        throws FieldDataInvalidException
    Throws:
    FieldDataInvalidException

    get

    java.util.List<TagField> get(TagFieldKey id)
                                 throws KeyNotFoundException
    Returns a list of TagField objects whose "id" is the specified one.

    Parameters:
    id - The field id.
    Returns:
    A list of TagField objects with the given "id".
    Throws:
    KeyNotFoundException