Jala 1.3

## Class jala.Mp3

    Object
       |
       +--jala.Mp3

class jala.Mp3

This is a class representing an MP3 file providing methods to access its metadata.
Defined in Mp3.js

Nested Class Summary
`<static class>` | `jala.Mp3.Id3v1`
`<static class>` | `jala.Mp3.Id3v2`

Field Summary
`Object` | `album`
`Object` | `artist`
`Object` | `comment`
`Object` | `genre`
`Object` | `title`
`Object` | `trackNumber`
`Object` | `year`
`<static> <final> Array` | `GENRES` Array defining valid genres in ID3v1
`<static> <final> Array` | `MODES` Array defining mp3 modes.
`<static> <final> Array` | `PICTURE_TYPES` Array defining valid picture types.
`<static> <final> Array` | `TEXT_ENCODINGS` Array defining valid text encodings.

Constructor Summary
`jala.Mp3 (<String|File> file)` Constructs a new jala.Mp3 wrapper and parses the header data of the MP3 file.

Method Summary
`Object` | `createTag(<Object> tagClass, <Object> tagObject)` This method creates a new tag object, attaches it to the file (thereby replacing an existing tag of this type) and returns it.
`jala.Mp3.Id3v1` | `createV1Tag(<Object> tagObject)` If the file doesn't contain an ID3v1 tag, this method creates a new ID3v1 tag object, attaches it to the file and returns it.
`jala.Mp3.Id3v2` | `createV2Tag(<Object> tagObject)` If the file doesn't contain an ID3v2 tag, this method creates a new ID3v2 tag object, attaches it to the file and returns it.
`Number` | `getBitRate()` Returns the bit rate the file was encoded with.
`String` | `getChannelMode()` Returns the channel mode the file was encoded with.
`Number` | `getDuration()` The audio length of the file in seconds at best estimate from the file info (method returns immediately).
`helma.File` | `getFile()` Returns a helma.File reference to the wrapped file.
`Number` | `getFrequency()` Returns the frequency the file was encoded with.
`org.farng.mp3.MP3File` | `getJavaObject()` Returns the underlying java object
`Object` | `getMetadata()` Returns a plain JavaScript object containing the values of all fields stored in either the Id3 V1 or V2 tag
`Number` | `getSize()` Returns the file size in bytes.
`Object` | `getTag(tagClass)` Returns a tag object, type is specified using the class name in jala.Mp3.*.
`jala.Mp3.Id3v1` | `getV1Tag()`
`jala.Mp3.Id3v2` | `getV2Tag()`
`Object` | `hasTag(tagClass)` Tells if the file contains a certain tag, type is specified using the class name in jala.Mp3.
`Boolean` | `hasV1Tag()` Returns true if the file contains a ID3v1 tag.
`Boolean` | `hasV2Tag()` Returns true if the file contains a ID3v2 tag.
`Boolean` | `isVariableBitRate()` Returns true if the file is (or seems to be) encoded with variable bit rate.
`Number` | `parseDuration()` Parses the audio file to extract the precise duration of the audio.
`void` | `removeTag(tagClass)` Removes a tag from the file, type is specified using the class name in jala.Mp3.*
`void` | `removeV1Tag()` Removes the ID3v1 tag from the file.
`Object` | `removeV2Tag()` Removes the ID3v2 tag from the file.
`Boolean` | `save(<String|helma.File> outFile)` Writes changed metadata back to the source file or to a new file.
`void` | `setMetadata(<Object> metadata)` Stores the metadata passed as argument in the ID2 v1 and v2 tags of the wrapped MP3 file.

Field Detail

### album

    Object album

### artist

    Object artist

### comment

    Object comment

### genre

    Object genre

### title

    Object title

### trackNumber

    Object trackNumber

### year

    Object year

### GENRES

    <static> <final> Array GENRES

Array defining valid genres in ID3v1

### MODES

    <static> <final> Array MODES

Array defining mp3 modes.

### PICTURE_TYPES

    <static> <final> Array PICTURE_TYPES

Array defining valid picture types. Note: Most image tagged files come with one picture of picture type null! The index position within the array defines the number used in the mp3 file.

### TEXT_ENCODINGS

    <static> <final> Array TEXT_ENCODINGS

Array defining valid text encodings. Note: UTF-8 is valid for v2.4 only. UTF-16 with BOM doesn't work with Winamp etc - use UTF-16BE instead! The index position within the array defines the number used in the mp3 file.

Constructor Detail

### jala.Mp3

    jala.Mp3(<String|File> file)

Constructs a new jala.Mp3 wrapper and parses the header data of the MP3 file. The standard fields for a tag are accessible as properties of the new object.

Parameters:

`file` - The mp3 file to be parsed, either as path string or as any kind of file object

Method Detail

### createTag

    Object createTag(<Object> tagClass, <Object> tagObject)

This method creates a new tag object, attaches it to the file (thereby replacing an existing tag of this type) and returns it. Type is specified using the class name in jala.Mp3.*. If a second argument is provided, its values are copied into the new tag.

Parameters:

`tagClass` -

`tagObject` - optional tag whose standard properties are copied to the new tag.

### createV1Tag

    jala.Mp3.Id3v1 createV1Tag(<Object> tagObject)

If the file doesn't contain an ID3v1 tag, this method creates a new ID3v1 tag object, attaches it to the file and returns it. If a second argument is provided, its values are copied into the new tag.

Parameters:

`tagObject` - optional tag whose standard properties are copied to the new tag.

### createV2Tag

    jala.Mp3.Id3v2 createV2Tag(<Object> tagObject)

If the file doesn't contain an ID3v2 tag, this method creates a new ID3v2 tag object, attaches it to the file and returns it. If a second argument is provided, its values are copied into the new tag.

Parameters:

`tagObject` - optional tag whose standard properties are copied to the new tag.

### getBitRate

    Number getBitRate()

Returns the bit rate the file was encoded with.

### getChannelMode

    String getChannelMode()

Returns the channel mode the file was encoded with.

### getDuration

    Number getDuration()

The audio length of the file in seconds at best estimate from the file info (method returns immediately). This method calculates based on the bitrate. Therefore it has to produce wrong results for files encoded with variable bitrate (vbr). For these files parseDuration() can be used.

Returns:

length in seconds

See:

- parseDuration()

### getFile

    helma.File getFile()

Returns a helma.File reference to the wrapped file.

### getFrequency

    Number getFrequency()

Returns the frequency the file was encoded with.

### getJavaObject

    org.farng.mp3.MP3File getJavaObject()

Returns the underlying java object

### getMetadata

    Object getMetadata()

Returns a plain JavaScript object containing the values of all fields stored in either the Id3 V1 or V2 tag

Returns:

An object containing the values of all fields

### getSize

    Number getSize()

Returns the file size in bytes.

### getTag

    Object getTag(tagClass)

Returns a tag object, type is specified using the class name in jala.Mp3.*.

### getV1Tag

    jala.Mp3.Id3v1 getV1Tag()

### getV2Tag

    jala.Mp3.Id3v2 getV2Tag()

### hasTag

    Object hasTag(tagClass)

Tells if the file contains a certain tag, type is specified using the class name in jala.Mp3.

### hasV1Tag

    Boolean hasV1Tag()

Returns true if the file contains a ID3v1 tag.

### hasV2Tag

    Boolean hasV2Tag()

Returns true if the file contains a ID3v2 tag.

### isVariableBitRate

    Boolean isVariableBitRate()

Returns true if the file is (or seems to be) encoded with variable bit rate. FIXME: The current implementation returned true for all test files.

### parseDuration

    Number parseDuration()

Parses the audio file to extract the precise duration of the audio. The upside is that it works fine for files with variable bitrates. The downside is that this action may take a few seconds depending on the size of the audio file.

Returns:

length in seconds

See:

- getDuration()

### removeTag

    void removeTag(tagClass)

Removes a tag from the file, type is specified using the class name in jala.Mp3.*

### removeV1Tag

    void removeV1Tag()

Removes the ID3v1 tag from the file.

### removeV2Tag

    Object removeV2Tag()

Removes the ID3v2 tag from the file.

### save

    Boolean save(<String|helma.File> outFile)

Writes changed metadata back to the source file or to a new file.

Parameters:

`outFile` - (optional) save the modified file to a different file

Returns:

true on success, false if the file contains tags that cannot be saved (Id3v2_2).

### setMetadata

    void setMetadata(<Object> metadata)

Stores the metadata passed as argument in the ID2 v1 and v2 tags of the wrapped MP3 file.

Parameters:

`metadata` - An object containing the fields to set and their values.

Jala 1.3

Documentation generated by JSDoc on Tue Jan 8 15:45:31 2008