# Class: Mp3

## jala.Mp3(file)

This is a class representing an MP3 file providing methods to access its metadata.

## Constructor

#### new Mp3(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:

Name | Type | Description
--- | --- | ---
`file` | String | File | The mp3 file to be parsed, either as path string or as any kind of file object

Source:
  - jala/code/Mp3.js, line 59

### Classes

Id3v1
Id3v2

### Members

#### album :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 248

#### artist :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 251

#### comment :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 254

#### genre :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 257

#### title :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 260

#### trackNumber :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 263

#### year :String

##### Type:

- String

Source:
  - jala/code/Mp3.js, line 266

#### (static, readonly) GENRES :Array

Array defining valid genres in ID3v1

##### Type:

- Array

Source:
  - jala/code/Mp3.js, line 290

#### (static, readonly) MODES :Array

Array defining mp3 modes.

##### Type:

- Array

Source:
  - jala/code/Mp3.js, line 318

#### (static, readonly) PICTURE_TYPES :Array

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.

##### Type:

- Array

Source:
  - jala/code/Mp3.js, line 338

#### (static, readonly) TEXT_ENCODINGS :Array

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.

##### Type:

- Array

Source:
  - jala/code/Mp3.js, line 328

### Methods

#### createTag(tagClass, 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:

Name | Type | Description
--- | --- | ---
`tagClass` | Object |
`tagObject` | Object | optional tag whose standard properties are copied to the new tag.

Source:
  - jala/code/Mp3.js, line 127

#### createV1Tag(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:

Name | Type | Description
--- | --- | ---
`tagObject` | Object | optional tag whose standard properties are copied to the new tag.

Source:
  - jala/code/Mp3.js, line 573

#### createV2Tag(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:

Name | Type | Description
--- | --- | ---
`tagObject` | Object | optional tag whose standard properties are copied to the new tag.

Source:
  - jala/code/Mp3.js, line 588

#### getBitRate()

Returns the bit rate the file was encoded with.

Source:
  - jala/code/Mp3.js, line 474

#### getChannelMode()

Returns the channel mode the file was encoded with.

Source:
  - jala/code/Mp3.js, line 484

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

Source:
  - jala/code/Mp3.js, line 429
See:
  - #parseDuration

##### Returns:

length in seconds

#### getFile()

Returns a helma.File reference to the wrapped file.

Source:
  - jala/code/Mp3.js, line 90

#### getFrequency()

Returns the frequency the file was encoded with.

Source:
  - jala/code/Mp3.js, line 494

#### getJavaObject()

Returns the underlying java object

Source:
  - jala/code/Mp3.js, line 98

#### getMetadata()

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

Source:
  - jala/code/Mp3.js, line 653

##### Returns:

An object containing the values of all fields

#### getSize()

Returns the file size in bytes.

Source:
  - jala/code/Mp3.js, line 465

#### getTag()

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

Source:
  - jala/code/Mp3.js, line 146

#### getV1Tag()

Source:
  - jala/code/Mp3.js, line 596

#### getV2Tag()

Source:
  - jala/code/Mp3.js, line 604

#### hasTag()

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

Source:
  - jala/code/Mp3.js, line 154

#### hasV1Tag()

Returns true if the file contains a ID3v1 tag.

Source:
  - jala/code/Mp3.js, line 613

#### hasV2Tag()

Returns true if the file contains a ID3v2 tag.

Source:
  - jala/code/Mp3.js, line 622

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

Source:
  - jala/code/Mp3.js, line 506

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

Source:
  - jala/code/Mp3.js, line 447
See:
  - #getDuration

##### Returns:

length in seconds

#### removeTag()

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

Source:
  - jala/code/Mp3.js, line 166

#### removeV1Tag()

Removes the ID3v1 tag from the file.

Source:
  - jala/code/Mp3.js, line 630

#### removeV2Tag()

Removes the ID3v2 tag from the file.

Source:
  - jala/code/Mp3.js, line 638

#### save(outFile)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`outFile` | String | helma.File | (optional) save the modified file to a different file

Source:
  - jala/code/Mp3.js, line 189

##### Returns:

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

#### setMetadata(metadata)

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`metadata` | Object | An object containing the fields to set and their values.

Source:
  - jala/code/Mp3.js, line 691