Proposal jala.audio package

objectives

• provide read/write access to metadata in audio files
• make the underlying tag structure transparent but still provide convenient access to the enclosed information
• be abstract enough so that the core can be used for other tags (and tag variants, if required)
• for the start, provide implementation for editing id3v1 and id3v2 tags in mp3 files

structure

For that there is no other audio or tag format on the Jala horizon at the moment, we steer clear of the difficulties a proper class hierarchy with an abstract base class would bring along. Future formats shall be implemented in their own class in jala.audio.* and shall support the set of methods provided here (as far as audio and tag formats allow them).

• jala.audio.* (these methods shall be supported by all audio wrappers beneath jala.audio)
  • constructor(<filenameOrFileObject>) Constructs a new audio wrapper and parses the header data.
  • getDuration() The audio length of the file in seconds at best estimate from the file info (method returns immediately).
  • getFile() Returns a helma.File reference.
  • getJavaObject() Returns the underlying java object, depending on the library in use.
  • getSize() Returns the file size in bytes.
  • createTag(<tagClass>, <copyFromObject>) Creates a new tag object, attaches it to the file and returns it. Type is specified using the class name in jala.audio.tag.*. If a second argument is provided, its values are copied into the new tag.
  • getTag(<tagClass>) Returns a tag object, type is specified using the class name in jala.audio.tag.*.
  • hasTag(<tagClass>) Tells if a file contains a certain tag, type is specified using the class name in jala.audio.tag.*
  • removeTag(<tagClass>) Removes a tag from the file, type is specified using the class name in jala.audio.tag.*
  • save(<optional filename>) Writes changed metadata back to the source file or to a new file.

• jala.audio.Mp3 (methods specific to MP3 files)
  • getBitRate()
  • getChannelMode()
  • getFrequency()
  • createV1Tag()
  • createV2Tag()
  • getV1Tag()
  • getV2Tag()
  • hasV1Tag()
  • hasV2Tag()
  • removeV1Tag()
  • removeV2Tag()
  • isVariableBitRate()
  • parseDuration() Parses the audio file to extract the precise duration of the audio (this may take some seconds).
  • for easy read access:artist, album, title, year, genre, comment, trackNumber are readonly properties of the file wrapper.

• jala.audio.Mp3.GENRES constant, array defining valid genres.
• jala.audio.Mp3.MODES constant, array defining mp3 stereo modes.
• jala.audio.Mp3.GENRES constant, array defining valid genres.
• jala.audio.Mp3.TEXT_ENCODINGS constant, array defining valid text encodings.
• jala.audio.Mp3.PICTURE_TYPES constant, array defining valid picture types.

• jala.audio.tag.* (private constructors; these methods shall be supported by all tag wrappers retrieved though getTag)
  • getAudio() returns the audio object this tag is assigned to.
  • getJavaObject() returns the java representation of the tag, class depends on the actual library used.
  • copyFrom(tag) copies tag information from another tag.
  • getAlbum() as used in id3v1.1
  • getArtist() as used in id3v1.1
  • getComment() as used in id3v1.1
  • getTitle() as used in id3v1.1
  • getTrackNumber() as used in id3v1.1
  • getGenre() as used in id3v1.1
  • getYear() as used in id3v1.1
  • getTextContent(<identifier>) retrieves an arbitrary field of the underlying tag.
  • setAlbum(<value>) as used in id3v1.1
  • setArtist(<value>) as used in id3v1.1
  • setComment(<value>) as used in id3v1.1
  • setTitle(<value>) as used in id3v1.1
  • setTrackNumber(<value>) as used in id3v1.1
  • setGenre(<value>) as used in id3v1.1
  • setYear(<value>) as used in id3v1.1
  • setTextContent(<identifier>, value) sets an arbitrary field of the underlying tag.

• jala.audio.tag.Id3v1 (implements the above methods only)

• jala.audio.tag.Id3v2 (implements the above methods plus id3v2-specific ones; the choice of further wrapped fields mimics the tag editors of winamp and itunes)
  • getTextEncoding() Returns the text encoding used for new frames.
  • setTextEncoding() Sets the text encoding that will be used for new frames added hereafter.
  • convertToSubtype(<type>) Converts the tag to the id3v2 tag of the given sub-version number (2, 3 or 4).
  • getAuthor()
  • getCopyright()
  • getImage(<pictureType>) returns image as helma.util.MimePart?.
  • getSubtype() returns the version number of id3v2 tags used (values 2 to 4 for id3v2.2 to id3v2.4)
  • getUrl()
  • setAuthor()
  • setCopyright()
  • setImage(<pictureType>, <mimeType>, <binArray>, <description>) adds an image to the file.
  • setTextEncoding(<encType>) sets the text encoding used when setting values.
  • setUrl()

Examples

Straightforward read access can be done using the properties of an Audio object. This reads data from a id3v2 tag. If the file doesn't contain such a tag, id3v1 is used:

 var mp3 = new jala.audio.Mp3("c:/audio/test.mp3");
 res.debug(mp3.title + " by " + mp3.artist);

For more precise read access, the tag object has to be retrieved first:

 var mp3 = new jala.audio.Mp3("c:/audio/test.mp3");
 var id3v1 = mp3.getV1Tag();
 res.debug(id3v1.getTitle() + " by " + id3v1.getArtist());

Writing metadata has to be done through the tag object:

 var mp3 = new jala.audio.Mp3("c:/audio/test.mp3");
 var id3v1 = mp3.getV1Tag();
 id3v1.setTitle("Myfanwy");
 id3v1.setArtist("Earl of Arundel");
 
 // to write content to both tag versions, copy it:
 var id3v2 = mp3.createTag(jala.audio.tag.Id3v2, id3v1);

 mp3.save();

Issues

• COMM (comment) and APIC (picture information) are the only non-text id3v2-frame jala is be able to handle at the moment. All other non-text frame types aren't supported for the moment (podcast-chapters, commercial tags, further file information).