com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodyEqualization

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility
    - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody
      - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyEqualization

-     public class ID3v23FrameBodyEqualization
      extends ID3v23FrameBody

  An equalization frame body is associated with an ID3v2.3 `EQUA` `frame` which is used to specify points on an equalization (EQ) curve. You may specify as many points as you want, but typically you specify 16 or 32, much like the 32 band equalizers you can buy for your home stereo. The monkeys who came up with the ID3v2.3 specification did quite a poor job on this one. Instead of making a nice simple EQ based on the industry standard 32 band graphic equalizers, they tried to solve a problem that didn't exist and made this as flexible as all humanly possible, which in turn made it unnecessarily complex. The equalization frame body contains the following fields:

  Equalization Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | numAdjustmentBits | number of bits to use when specifying the levels on the EQ curve. This determines the scale used for the offsets of the points, ie, levels, from the midpoint on the EQ curve.
  2. | `levels` | list of the points on the EQ curve

  There may be only one equalization frame in an ID3v2.3 `tag`.

  See Also:
    `ID3v23Frame`, ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBodyEqualization()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodyEqualization(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v23FrameBodyEqualization(int numAdjustmentBits, Level[] levels)` This constructor is called when creating a new frame.
    `ID3v23FrameBodyEqualization(int numAdjustmentBits, java.util.List<Level> levels)` This constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.List<Level>` | `getLevels()` gets the levels comprising the equalization curve.
    `int` | `getNumAdjustmentBits()` gets the number of bits used for the representation of an adjustment in an equalization level.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setLevels(Level[] levels)` sets the levels comprising the equalization curve.
    `void` | `setLevels(java.util.List<Level> levels)` sets the levels comprising the equalization curve.
    `void` | `setNumAdjustmentBits(int numAdjustmentBits)` sets the number of bits used for the representation of an adjustment in an equalization level.
    `java.lang.String` | `toString()` gets a string representation of the equalization frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

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

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

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

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

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

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

- - ### Constructor Detail

    - #### ID3v23FrameBodyEqualization

          public ID3v23FrameBodyEqualization()

      The default constructor is called when creating a new frame. The default values used are:
      - 16 bit adjustments
      - no levels, ie, a flat EQ curve

    - #### ID3v23FrameBodyEqualization

          public ID3v23FrameBodyEqualization(int numAdjustmentBits,
                                     Level[] levels)

      This constructor is called when creating a new frame.
      Parameters:
        `numAdjustmentBits` - number of bits used for the representation of the adjustment in an equalization level.
        `levels` - levels comprising the equalization curve.

    - #### ID3v23FrameBodyEqualization

          public ID3v23FrameBodyEqualization(int numAdjustmentBits,
                                     java.util.List<Level> levels)

      This constructor is called when creating a new frame.
      Parameters:
        `numAdjustmentBits` - number of bits used for the representation of the adjustment in an equalization level.
        `levels` - levels comprising the equalization curve.

    - #### ID3v23FrameBodyEqualization

          public ID3v23FrameBodyEqualization(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 equalization 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

    - #### getNumAdjustmentBits

          public int getNumAdjustmentBits()

      gets the number of bits used for the representation of an adjustment in an equalization level.
      Returns:
        the number of bits used for the representation of an adjustment in an equalization level.
      See Also:
        `setNumAdjustmentBits(int)`

    - #### setNumAdjustmentBits

          public void setNumAdjustmentBits(int numAdjustmentBits)
                                    throws java.lang.IllegalArgumentException

      sets the number of bits used for the representation of an adjustment in an equalization level. This determines the scale used for the offsets of the points, ie, levels, from the midpoint on the EQ curve.
      Parameters:
        `numAdjustmentBits` - the number of bits used for the representation of an adjustment in an equalization level.
      Throws:
        `java.lang.IllegalArgumentException` - if the number of adjustment bits is less than or equal to 0.
      See Also:
        `getNumAdjustmentBits()`

    - #### getLevels

          public java.util.List<Level> getLevels()

      gets the levels comprising the equalization curve.
      Returns:
        the levels comprising the equalization curve.
      See Also:
        `setLevels(List)`

    - #### setLevels

          public void setLevels(Level[] levels)

      sets the levels comprising the equalization curve.
      Parameters:
        `levels` - the levels comprising the equalization curve.
      See Also:
        `getLevels()`

    - #### setLevels

          public void setLevels(java.util.List<Level> levels)

      sets the levels comprising the equalization curve.
      Parameters:
        `levels` - the levels comprising the equalization curve.
      See Also:
        `getLevels()`

    - #### 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 `ID3v23FrameBody`
      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 `ID3v23FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the equalization 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.