com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyRelativeVolumeAdjustment

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

-     public class ID3v24FrameBodyRelativeVolumeAdjustment
      extends ID3v24FrameBody

  An ID3v2.4 relative volume adjustment frame body is associated with an ID3v2.4 `RVA2` `frame` which is used to adjust the volume of .mp3 songs to a consistent level. Since some songs are recorded at higher levels than others, this frame could allow a user to set a desired volume and the .mp3 players would adjust the output volume of the .mp3 song to the level specified by the user.

  This new version of the relative volume adjustment frame is much simpler than the version found in the ID3v2.3 specification. The volume adjustments are now fixed 16 bits integers. This frame allows the user to say how much he wants to increase/decrease the volume on each channel when the file is played. The purpose is to be able to align all files to a reference volume, so that you don't have to change the volume constantly. This frame may also be used to balance adjust the audio.

  The relative volume adjustment frame allows the user to specify both relative and peak volume settings for the following speaker channels:

  - other
  - master volume
  - front right channel
  - front left channel
  - back right channel
  - back left channel
  - front center channel
  - back center channel
  - sub woofer channel

  While the ID3v2.4 specification allows the number of bits used to store corresponding peak volumes to vary between 0 and 255, the Beaglebuddy MP3 library only allows 0 and 32 bit values. The monkey's who came up with the ID3v2.x specs did some crazy stuff, and this is one of them.

  The relative volume adjustment frame body contains the following fields:

  Relative Volume Adjustment Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | identification | uniquely identifies the situation and/or device when this eq curve should be applied.
  2. | `volumes` | list of the relative volume adjustments for the different speaker channels.

  There may only be one relative volume adjustment frame.

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

- - ### 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
    `ID3v24FrameBodyRelativeVolumeAdjustment()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyRelativeVolumeAdjustment(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v24FrameBodyRelativeVolumeAdjustment(java.lang.String identification, java.util.List<RelativeVolume> volumes)` This constructor is called when creating a new frame.
    `ID3v24FrameBodyRelativeVolumeAdjustment(java.lang.String identification, RelativeVolume[] volumes)` This constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getIdentification()` get the string which uniquely identifies the situation and/or device where this EQ curve should be applied.
    `RelativeVolume` | `getVolume(RelativeVolume.Channel channel)` gets the relative volume adjustment for the specified speaker channel.
    `java.util.List<RelativeVolume>` | `getVolumes()` gets the volume settings comprising the relative volume adjustment.
    `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` | `setIdentification(java.lang.String identification)` set the string which uniquely identifies the situation and/or device where this EQ curve should be applied.
    `void` | `setVolume(RelativeVolume volume)` sets the relative volume setting for a specific speaker channel.
    `void` | `setVolumes(java.util.List<RelativeVolume> volumes)` sets the volumes comprising the equalization curve.
    `void` | `setVolumes(RelativeVolume[] volumes)` sets the volume settings comprising the relative volume adjustment.
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.4 relative volume adjustment 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, 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

    - #### ID3v24FrameBodyRelativeVolumeAdjustment

          public ID3v24FrameBodyRelativeVolumeAdjustment()

      The default constructor is called when creating a new frame. The default values used are:
      - "standard" relative volume adjustment
      - 0 volume adjustments

    - #### ID3v24FrameBodyRelativeVolumeAdjustment

          public ID3v24FrameBodyRelativeVolumeAdjustment(java.lang.String identification,
                                                 RelativeVolume[] volumes)

      This constructor is called when creating a new frame.
      Parameters:
        `identification` - uniquely identifies the situation and/or device when this relative volume adjustment should be applied.
        `volumes` - relative volume adjustments for each speaker channel.

    - #### ID3v24FrameBodyRelativeVolumeAdjustment

          public ID3v24FrameBodyRelativeVolumeAdjustment(java.lang.String identification,
                                                 java.util.List<RelativeVolume> volumes)

      This constructor is called when creating a new frame.
      Parameters:
        `identification` - uniquely identifies the situation and/or device when this relative volume adjustment should be applied.
        `volumes` - relative volume adjustments for each speaker channel.

    - #### ID3v24FrameBodyRelativeVolumeAdjustment

          public ID3v24FrameBodyRelativeVolumeAdjustment(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 a relative volume adjustment 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

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

    - #### getIdentification

          public java.lang.String getIdentification()

      get the string which uniquely identifies the situation and/or device where this EQ curve should be applied.
      Returns:
        the string which uniquely identifies the situation and/or device where this EQ curve should be applied.
      See Also:
        `setIdentification(String)`

    - #### setIdentification

          public void setIdentification(java.lang.String identification)

      set the string which uniquely identifies the situation and/or device where this EQ curve should be applied.
      Parameters:
        `identification` - string which uniquely identifies the situation and/or device where this EQ curve should be applied.
      See Also:
        `getIdentification()`

    - #### getVolume

          public RelativeVolume getVolume(RelativeVolume.Channel channel)

      gets the relative volume adjustment for the specified speaker channel.
      Parameters:
        `channel` - the speaker channel whose volume setting will be retrieved.
      Returns:
        if a relative volume adjustment has been specified for the given speaker channel, then return it. Otherwise, return null.
      See Also:
        `getVolumes()`, `setVolume(RelativeVolume)`

    - #### setVolume

          public void setVolume(RelativeVolume volume)

      sets the relative volume setting for a specific speaker channel.
      Parameters:
        `volume` - the relative volume setting for a specific speaker channel.
      See Also:
        `getVolume(RelativeVolume.Channel)`, `getVolumes()`

    - #### getVolumes

          public java.util.List<RelativeVolume> getVolumes()

      gets the volume settings comprising the relative volume adjustment.
      Returns:
        the volume settings comprising the relative volume adjustment.
      See Also:
        `setVolume(RelativeVolume)`, `setVolumes(List)`

    - #### setVolumes

          public void setVolumes(RelativeVolume[] volumes)

      sets the volume settings comprising the relative volume adjustment.
      Parameters:
        `volumes` - the volume settings comprising the relative volume adjustment.
      See Also:
        `getVolumes()`

    - #### setVolumes

          public void setVolumes(java.util.List<RelativeVolume> volumes)

      sets the volumes comprising the equalization curve.
      Parameters:
        `volumes` - the volumes comprising the equalization curve.
      See Also:
        `getVolumes()`

    - #### 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 ID3v2.4 relative volume adjustment 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.