com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyAudioSeekPointIndex

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility
    - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody
      - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyAudioSeekPointIndex

-     public class ID3v24FrameBodyAudioSeekPointIndex
      extends ID3v24FrameBody

  An audio seek pointer index frame body is associated with an ID3v2.4 `ASPI` `frame` which is used to list the people who were involved in the song. The audio seek pointer index frame body contains the following fields:

  Audio Seek Pointer Index
  | Field | Description
  --- | --- | ---
  1. | indexed data start | the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file. This is typically the start of the audio portion of the .mp3 file.
  2. | indexed data length | length (in bytes) of the .mp3 audio data being indexed. This is typically the size (in bytes) of the .mp3 file - the size of ID3v2.4 tag.
  3. | num index points | the number of index points. This specifies how many points within the .mp3 audio section you want create indexes for.
  4. | bits per index point | the number of bits used to store an index point (either 8 bits or 16 bits). Why this wasn't just defined as 16 bits you'll have to ask the crazy drunk monkeys who created the ID3v2.4 spec.
  5. | list of fraction at indexes | for each index point, the fraction at index is the numerator of the fraction representing a relative position in the data. The denominator is 2 ^ bits per index point. Since the bits per index point is either 8 or 16, the denominator is either 2 ^ 8 = 256 or 2 ^ 16 = 65536. The fraction at index i is given by: f[i] = offset[i] / * 2 ^ rounded down to the nearest integer where: offset[i] = the offset (in bytes) of the frame whose start is soonest after the point for which the time offset = (i / * ). The duration is obtained from the TLEN frame.

  There may only be one audio seek pointer index frame in an ID3v2.4 `tag`.

  See Also:
    `ID3v24Frame`, ID3 tag version 2.4.0 standard, wikipedia history of ID3 tags

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint` valid ID3v2.4 bits per index point values

  - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24FrameBodyAudioSeekPointIndex()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyAudioSeekPointIndex(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v24FrameBodyAudioSeekPointIndex(int indexedDataStart, int indexedDataLength, ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint bitsPerIndexPoint, java.util.List<java.lang.Short> fractionAtIndexes)` This constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint` | `getBitsPerIndexPoint()` gets the number of bits used to store an index point (either 8 bits or 16 bits).
    `java.util.List<java.lang.Short>` | `getFractionAtIndexes()` gets the list of fraction indexes for the indexed points.
    `int` | `getIndexedDataLength()` gets the length (in bytes) of the .mp3 audio data being indexed.
    `int` | `getIndexedDataStart()` gets the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file.
    `short` | `getNumIndexPoints()` gets the number of index points.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setBitsPerIndexPoint(ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint bitsPerIndexPoint)`
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setFractionAtIndexes(java.util.List<java.lang.Short> fractionAtIndexes)` A fraction index represents the relative position within data, and is a fraction given by the following formula: fraction index = offset / * 2 ^ where: time offset = (index point / * ). duration is the length (in ms) of the mp3 file and is obtained from the TLEN frame. offset is the offset (in bytes) of the mp3 frame (not to be confused with frames in an ID3v2.x tag) whose start occurs soonest in the .mp3 file after the time offset. Here is an example to illustrate these concepts:
             You have an .mp3 file which is 1 minute and 20 seconds long, has a disk size of 200,000 bytes, and whose first 10,000 bytes are used for the ID3v2.4 tag.
    `void` | `setIndexedDataLength(int indexedDataLength)` sets the length (in bytes) of the .mp3 audio data being indexed.
    `void` | `setIndexedDataStart(int indexedDataStart)` sets the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file.
    `java.lang.String` | `toString()` gets a string representation of the audio seek pointer index frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `getFrameType, getNextNullTerminator, getSize, isDirty, save, save`

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

    - ### Methods inherited from class com.beaglebuddy.util.Utility

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, getUTF16String, getUTF8String, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ID3v24FrameBodyAudioSeekPointIndex

          public ID3v24FrameBodyAudioSeekPointIndex()

      The default constructor is called when creating a new frame. The default values used are:
      - indexed data start of 0
      - indexed data length of 0
      - 16 bits per index point
      - 0 index points

    - #### ID3v24FrameBodyAudioSeekPointIndex

          public ID3v24FrameBodyAudioSeekPointIndex(int indexedDataStart,
                                            int indexedDataLength,
                                            ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint bitsPerIndexPoint,
                                            java.util.List<java.lang.Short> fractionAtIndexes)

      This constructor is called when creating a new frame.
      Parameters:
        `indexedDataStart` - byte offset from the beginning of the .mp3 file.
        `indexedDataLength` - length (in bytes) of the audio data being indexed.
        `bitsPerIndexPoint` - the number of bits used to store an index point (either 8 bits or 16 bits).
        `fractionAtIndexes` - list of fraction indexes for the indexed points. see `setFractionAtIndexes(List)` for a fuller explanation.

    - #### ID3v24FrameBodyAudioSeekPointIndex

          public ID3v24FrameBodyAudioSeekPointIndex(java.io.InputStream inputStream,
                                            int frameBodySize)
                                             throws java.io.IOException

      This constructor is called when reading in an existing frame from an .mp3 file. This is then followed by a call to the parse() method.
      Parameters:
        `inputStream` - input stream pointing to an audio seek pointer index frame body in the .mp3 file.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading the frame body.

  - ### Method Detail

    - #### getIndexedDataStart

          public int getIndexedDataStart()

      gets the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file. This is typically the start of the audio portion of the .mp3 file.
      Returns:
        the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file.
      See Also:
        `setIndexedDataStart(int)`

    - #### setIndexedDataStart

          public void setIndexedDataStart(int indexedDataStart)

      sets the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file. This is typically the start of the audio portion of the .mp3 file.
      Parameters:
        `indexedDataStart` - the byte offset of the indexed .mp3 audio data from the beginning of the .mp3 file.
      See Also:
        `getIndexedDataStart()`

    - #### getIndexedDataLength

          public int getIndexedDataLength()

      gets the length (in bytes) of the .mp3 audio data being indexed.
      Returns:
        the length (in bytes) of the .mp3 audio data being indexed.
      See Also:
        `setIndexedDataLength(int)`

    - #### setIndexedDataLength

          public void setIndexedDataLength(int indexedDataLength)

      sets the length (in bytes) of the .mp3 audio data being indexed. This is typically the entire audio portion of the .mp3 file, and hence is calculated by subtracting the size of the ID3v2.4 tag from the file size of the .mp3 file. For example, if you have an .mp3 file which has a size of 200,00 bytes, and whose ID3v2.4 tag header is 35,000 bytes, then the index data length = 200,000 - 35,000 = 165,000 bytes
      Parameters:
        `indexedDataLength` - the length (in bytes) of the .mp3 audio data being indexed.
      See Also:
        `getIndexedDataLength()`

    - #### getNumIndexPoints

          public short getNumIndexPoints()

      gets the number of index points.
      Returns:
        the number of index points.
      See Also:
        `getFractionAtIndexes()`

    - #### getBitsPerIndexPoint

          public ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint getBitsPerIndexPoint()

      gets the number of bits used to store an index point (either 8 bits or 16 bits).
      Returns:
        the number of bits used to store an index point (either 8 bits or 16 bits).
      See Also:
        `setBitsPerIndexPoint(BitsPerIndexPoint)`

    - #### setBitsPerIndexPoint

          public void setBitsPerIndexPoint(ID3v24FrameBodyAudioSeekPointIndex.BitsPerIndexPoint bitsPerIndexPoint)

      Parameters:
        `bitsPerIndexPoint` - the bitsPerIndexPoint to set

    - #### getFractionAtIndexes

          public java.util.List<java.lang.Short> getFractionAtIndexes()

      gets the list of fraction indexes for the indexed points.
      Returns:
        the list of fraction indexes for the indexed points.
      See Also:
        `setFractionAtIndexes(List)`

    - #### setFractionAtIndexes

          public void setFractionAtIndexes(java.util.List<java.lang.Short> fractionAtIndexes)

      A fraction index represents the relative position within data, and is a fraction given by the following formula:
      fraction index = offset / * 2 ^
      where:
      - time offset = (index point / * ).
      - duration is the length (in ms) of the mp3 file and is obtained from the TLEN frame.
      - offset is the offset (in bytes) of the mp3 frame (not to be confused with frames in an ID3v2.x tag) whose start occurs soonest in the .mp3 file after the time offset.
      Here is an example to illustrate these concepts:

               You have an .mp3 file which is 1 minute and 20 seconds long, has a disk size of 200,000 bytes, and whose first 10,000 bytes are used for the ID3v2.4 tag.
               You are going to create 15 index points for the audio portion of the .mp3 file.
               You want to calculate the fraction at index 6.
               Using these values, you then have:
               1. indexed data start     10,000 bytes
               2. indexed data end       200,000 bytes
               3. indexed data length    190,000 bytes = 200,000 - 10,000
               4. duration               1 minute and 20 seconds = 80 seconds = 80,000 ms
               5. num index points       15
               6. bits per index point   16
               7. time offset[6]         6 / 15 * 80,000ms = 32,000ms
               8. offset[6]              is the offset (in bytes) of the mp3 frame (not to be confused with frames in an ID3v2.x tag) whose start occurs soonest after the time offset.
                                         this value will be calculated by the .mp3 player software.
               8. fraction[6]            offset[6] / indexed data length * 2 ^ bits per index point
                                         offset[6] / 190,000 * 65536
                                         offset[6] * 0.34492631578947368421052631578947
               The fraction calculated in step 8 is rounded down to the nearest integer.

      Don't worry if you don't understand all of this. The monkeys who made the ID3v2.4 spec did an exceptionally bad job with this frame, and their documentation has errors in it.
      Parameters:
        `fractionAtIndexes` - the fractionAtIndexes to set

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

      parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
      Overrides:
        `parse` in class `ID3v24FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### setBuffer

          public void setBuffer()

      If the frame body's values have been modified, then resize the raw binary buffer and store the new values there. When finished, the dirty flag is reset to indicate that the buffer is up to date, and the frame is now ready to be saved to the .mp3 file.
      Overrides:
        `setBuffer` in class `ID3v24FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the audio seek pointer index frame body showing all of the frame's fields and their values.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.