com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodyRelativeVolumeAdjustment

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

-     public class ID3v23FrameBodyRelativeVolumeAdjustment
      extends ID3v23FrameBody

  A relative volume adjustment frame body is associated with an ID3v2.3 `RVAD` `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.

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

  - front right channel
  - front left channel
  - back right channel
  - back left channel
  - center channel
  - bass channel

  Once again, the monkey's who came up with the specification made this far more complex than it ever needed to be. Instead of just using 16 bits to specify a volume, they allowed implementers to choose the number of bits. This forces implementers to do a lot of bit manipulation and makes the code incredibly messy. In ID3v2.4, they fixed this and made the volume adjustments 16 bits. Additionally, according to the ID3 v2.3 specification, the bits used for volume adjustments field is normally 0x10 (16 bits) for MPEG 2 layer I, II and III and MPEG 2.5.. For these reasons, Beaglebuddy Software decided to only support 16 bit volumes.

  The relative volume adjustment frame body contains the following fields:

  Relative Volume Adjustment Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | relative volume adjustment front right channel | amount to adjust the volume of the front right channel.
  2. | relative volume adjustment front left channel | amount to adjust the volume of the front left channel.
  3. | relative volume adjustment back right channel | amount to adjust the volume of the back right channel.
  4. | relative volume adjustment back left channel | amount to adjust the volume of the back left channel.
  5. | relative volume adjustment center channel | amount to adjust the volume of the center channel.
  6. | relative volume adjustment bass channel | amount to adjust the volume of the bass channel.
  7. | peak volume front right channel | the maximum volume allowed for the front right channel.
  8. | peak volume front left channel | the maximum volume allowed for the front left channel.
  9. | peak volume back right channel | the maximum volume allowed for the back right channel.
  10 | peak volume back left channel | the maximum volume allowed for the back left channel.
  11. | peak volume center channel | the maximum volume allowed for the center channel.
  12. | peak volume bass channel | the maximum volume allowed for the bass channel.

  There may only be one relative volume adjustment frame.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ID3v23FrameBodyRelativeVolumeAdjustment.Direction` valid ID3v2.3 volume directions

  - ### 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
    `ID3v23FrameBodyRelativeVolumeAdjustment()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodyRelativeVolumeAdjustment(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v23FrameBodyRelativeVolumeAdjustment(int relativeVolumeAdjustmentFrontRightChannel, int relativeVolumeAdjustmentFrontLeftChannel, int relativeVolumeAdjustmentBackRightChannel, int relativeVolumeAdjustmentBackLeftChannel, int relativeVolumeAdjustmentCenterChannel, int relativeVolumeAdjustmentBassChannel, int peakVolumeFrontRightChannel, int peakVolumeFrontLeftChannel, int peakVolumeBackRightChannel, int peakVolumeBackLeftChannel, int peakVolumeCenterChannel, int peakVolumeBassChannel)` The default constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `convertVolumeAdjustmentsToDecibels(int volume)` converts a unitless volume adjustment to decibels (db).
    `int` | `getBitsUsedForVolumeAdjustments()` gets the number of bits to use for specifying the volume adjustments for each of the 6 supported channel.
    `int` | `getPeakVolumeBackLeftChannel()` gets the peak volume for the back left channel.
    `int` | `getPeakVolumeBackRightChannel()` gets the peak volume for the back right channel.
    `int` | `getPeakVolumeBassChannel()` gets the peak volume for the bass channel.
    `int` | `getPeakVolumeCenterChannel()` gets the peak volume for the center channel.
    `int` | `getPeakVolumeFrontLeftChannel()` gets the peak volume for the front left channel.
    `int` | `getPeakVolumeFrontRightChannel()` gets the peak volume for the front right channel.
    `int` | `getRelativeVolumeAdjustmentBackLeftChannel()` gets the relative volume adjustment for the back left channel.
    `int` | `getRelativeVolumeAdjustmentBackRightChannel()` gets the relative volume adjustment for the back right channel.
    `int` | `getRelativeVolumeAdjustmentBassChannel()` gets the relative volume adjustment for the bass channel.
    `int` | `getRelativeVolumeAdjustmentCenterChannel()` gets the relative volume adjustment for the center channel.
    `int` | `getRelativeVolumeAdjustmentFrontLeftChannel()` gets the relative volume adjustment for the front left channel.
    `int` | `getRelativeVolumeAdjustmentFrontRightChannel()` gets the relative volume adjustment for the front right channel.
    `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` | `setPeakVolumeBackLeftChannel(int volume)` sets the peak volume for the back left channel.
    `void` | `setPeakVolumeBackRightChannel(int volume)` sets the peak volume for the back right channel.
    `void` | `setPeakVolumeBassChannel(int volume)` sets the peak volume for the bass channel.
    `void` | `setPeakVolumeCenterChannel(int volume)` sets the peak volume for the center channel.
    `void` | `setPeakVolumeFrontLeftChannel(int volume)` sets the peak volume for the front left channel.
    `void` | `setPeakVolumeFrontRightChannel(int volume)` sets the peak volume for the front right channel.
    `void` | `setRelativeVolumeAdjustmentBackLeftChannel(int volume)` sets the relative volume adjustment for the back left channel.
    `void` | `setRelativeVolumeAdjustmentBackRightChannel(int volume)` sets the relative volume adjustment for the back right channel.
    `void` | `setRelativeVolumeAdjustmentBassChannel(int volume)` sets the relative volume adjustment for the bass channel.
    `void` | `setRelativeVolumeAdjustmentCenterChannel(int volume)` sets the relative volume adjustment for the center channel.
    `void` | `setRelativeVolumeAdjustmentFrontLeftChannel(int volume)` sets the relative volume adjustment for the front left channel.
    `void` | `setRelativeVolumeAdjustmentFrontRightChannel(int volume)` sets the relative volume adjustment for the front right channel.
    `java.lang.String` | `toString()` gets a string representation of the relative volume adjustment 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

    - #### ID3v23FrameBodyRelativeVolumeAdjustment

          public ID3v23FrameBodyRelativeVolumeAdjustment()

      The default constructor is called when creating a new frame. The default values used are:
      - 0 relative volume adjustment front right channel
      - 0 relative volume adjustment front left channel
      - 0 relative volume adjustment back right channel
      - 0 relative volume adjustment back left channel
      - 0 relative volume adjustment center channel
      - 0 relative volume adjustment bass channel
      - 0 peak volume front right channel
      - 0 peak volume front left channel
      - 0 peak volume back right channel
      - 0 peak volume back left channel
      - 0 peak volume center channel
      - 0 peak volume bass channel

    - #### ID3v23FrameBodyRelativeVolumeAdjustment

          public ID3v23FrameBodyRelativeVolumeAdjustment(int relativeVolumeAdjustmentFrontRightChannel,
                                                 int relativeVolumeAdjustmentFrontLeftChannel,
                                                 int relativeVolumeAdjustmentBackRightChannel,
                                                 int relativeVolumeAdjustmentBackLeftChannel,
                                                 int relativeVolumeAdjustmentCenterChannel,
                                                 int relativeVolumeAdjustmentBassChannel,
                                                 int peakVolumeFrontRightChannel,
                                                 int peakVolumeFrontLeftChannel,
                                                 int peakVolumeBackRightChannel,
                                                 int peakVolumeBackLeftChannel,
                                                 int peakVolumeCenterChannel,
                                                 int peakVolumeBassChannel)

      The default constructor is called when creating a new frame.
      Parameters:
        `relativeVolumeAdjustmentFrontRightChannel` - relative volume adjustment front right channel
        `relativeVolumeAdjustmentFrontLeftChannel` - relative volume adjustment front left channel
        `relativeVolumeAdjustmentBackRightChannel` - relative volume adjustment back right channel
        `relativeVolumeAdjustmentBackLeftChannel` - relative volume adjustment back left channel
        `relativeVolumeAdjustmentCenterChannel` - relative volume adjustment center channel
        `relativeVolumeAdjustmentBassChannel` - relative volume adjustment bass channel
        `peakVolumeFrontRightChannel` - peak volume front right channel
        `peakVolumeFrontLeftChannel` - peak volume front left channel
        `peakVolumeBackRightChannel` - peak volume back right channel
        `peakVolumeBackLeftChannel` - peak volume back left channel
        `peakVolumeCenterChannel` - peak volume center channel
        `peakVolumeBassChannel` - peak volume bass channel

    - #### ID3v23FrameBodyRelativeVolumeAdjustment

          public ID3v23FrameBodyRelativeVolumeAdjustment(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 `ID3v23FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### convertVolumeAdjustmentsToDecibels

          public double convertVolumeAdjustmentsToDecibels(int volume)

      converts a unitless volume adjustment to decibels (db). The ID3 v2.3 specification does not specify what units the volume adjustments are in. This is left up to the developers who implement the spec. iTunes apparently uses the following formula, which Beaglebuddy has also adopted, to convert the volume adjustments to decibels. `volume (db) = 20 * ln(((volume adjustment / 256) + 255 ) / 255) / ln(10)
      Thus, for example, if the relative volume adjustment for the front right channel was -14135, then its volume in db would be:

           volume (db) = 20 * ln((-14135 / 256 + 255 ) / 255) / ln(10)
                       = 20 * ln((-55.215 + 255) / 255) / 2.30
                       = 20 * ln( 199.78515625   / 255) / 2.30
                       = 20 * ln(0.7834712) / 2.30
                       = 20 * -0.244021 / 2.30
                       = -2.11953925

      `
      Parameters:
        `volume` - the unitless volume adjustment that is to be converted to decibels (db).
      Returns:
        the specified adjustment volume in units of decibels (db).
      See Also:
        Normalize Audio

    - #### getBitsUsedForVolumeAdjustments

          public int getBitsUsedForVolumeAdjustments()

      gets the number of bits to use for specifying the volume adjustments for each of the 6 supported channel.
      Returns:
        the number of bits to use for specifying the volume adjustments for each of the 6 supported channel.
      See Also:
        `setBitsUsedForVolumeAdjustments(int)`

    - #### getRelativeVolumeAdjustmentFrontRightChannel

          public int getRelativeVolumeAdjustmentFrontRightChannel()

      gets the relative volume adjustment for the front right channel.
      Returns:
        the relative volume adjustment for the front right channel.
      See Also:
        `setRelativeVolumeAdjustmentFrontRightChannel(int)`, `getPeakVolumeFrontRightChannel()`

    - #### setRelativeVolumeAdjustmentFrontRightChannel

          public void setRelativeVolumeAdjustmentFrontRightChannel(int volume)

      sets the relative volume adjustment for the front right channel.
      Parameters:
        `volume` - the relative volume adjustment for the front right channel.
      See Also:
        `getRelativeVolumeAdjustmentFrontRightChannel()`, `getPeakVolumeFrontRightChannel()`

    - #### getPeakVolumeFrontRightChannel

          public int getPeakVolumeFrontRightChannel()

      gets the peak volume for the front right channel.
      Returns:
        the peak volume for the front right channel.
      See Also:
        `setPeakVolumeFrontRightChannel(int)`, `getRelativeVolumeAdjustmentFrontRightChannel()`

    - #### setPeakVolumeFrontRightChannel

          public void setPeakVolumeFrontRightChannel(int volume)

      sets the peak volume for the front right channel.
      Parameters:
        `volume` - the peak volume for the front right channel.
      See Also:
        `getPeakVolumeFrontRightChannel()`, `getRelativeVolumeAdjustmentFrontRightChannel()`

    - #### getRelativeVolumeAdjustmentFrontLeftChannel

          public int getRelativeVolumeAdjustmentFrontLeftChannel()

      gets the relative volume adjustment for the front left channel.
      Returns:
        the relative volume adjustment for the front left channel.
      See Also:
        `setRelativeVolumeAdjustmentFrontLeftChannel(int)`, `getPeakVolumeFrontLeftChannel()`

    - #### setRelativeVolumeAdjustmentFrontLeftChannel

          public void setRelativeVolumeAdjustmentFrontLeftChannel(int volume)

      sets the relative volume adjustment for the front left channel.
      Parameters:
        `volume` - the relative volume adjustment for the front left channel.
      See Also:
        `getRelativeVolumeAdjustmentFrontLeftChannel()`, `getPeakVolumeFrontLeftChannel()`

    - #### getPeakVolumeFrontLeftChannel

          public int getPeakVolumeFrontLeftChannel()

      gets the peak volume for the front left channel.
      Returns:
        the peak volume for the front left channel.
      See Also:
        `setPeakVolumeFrontLeftChannel(int)`, `getRelativeVolumeAdjustmentFrontLeftChannel()`

    - #### setPeakVolumeFrontLeftChannel

          public void setPeakVolumeFrontLeftChannel(int volume)

      sets the peak volume for the front left channel.
      Parameters:
        `volume` - the peak volume for the front left channel.
      See Also:
        `getPeakVolumeFrontLeftChannel()`, `getRelativeVolumeAdjustmentFrontLeftChannel()`

    - #### getRelativeVolumeAdjustmentBackRightChannel

          public int getRelativeVolumeAdjustmentBackRightChannel()

      gets the relative volume adjustment for the back right channel.
      Returns:
        the relative volume adjustment for the back right channel.
      See Also:
        `setRelativeVolumeAdjustmentBackRightChannel(int)`, `getPeakVolumeBackRightChannel()`

    - #### setRelativeVolumeAdjustmentBackRightChannel

          public void setRelativeVolumeAdjustmentBackRightChannel(int volume)

      sets the relative volume adjustment for the back right channel.
      Parameters:
        `volume` - the relative volume adjustment for the back right channel.
      See Also:
        `getRelativeVolumeAdjustmentBackRightChannel()`, `getPeakVolumeBackRightChannel()`

    - #### getPeakVolumeBackRightChannel

          public int getPeakVolumeBackRightChannel()

      gets the peak volume for the back right channel.
      Returns:
        the peak volume for the back right channel.
      See Also:
        `setPeakVolumeBackRightChannel(int)`, `getRelativeVolumeAdjustmentBackRightChannel()`

    - #### setPeakVolumeBackRightChannel

          public void setPeakVolumeBackRightChannel(int volume)

      sets the peak volume for the back right channel.
      Parameters:
        `volume` - the peak volume for the back right channel.
      See Also:
        `getPeakVolumeBackRightChannel()`, `getRelativeVolumeAdjustmentBackRightChannel()`

    - #### getRelativeVolumeAdjustmentBackLeftChannel

          public int getRelativeVolumeAdjustmentBackLeftChannel()

      gets the relative volume adjustment for the back left channel.
      Returns:
        the relative volume adjustment for the back left channel.
      See Also:
        `setRelativeVolumeAdjustmentBackLeftChannel(int)`, `getPeakVolumeBackLeftChannel()`

    - #### setRelativeVolumeAdjustmentBackLeftChannel

          public void setRelativeVolumeAdjustmentBackLeftChannel(int volume)

      sets the relative volume adjustment for the back left channel.
      Parameters:
        `volume` - the relative volume adjustment for the back left channel.
      See Also:
        `getRelativeVolumeAdjustmentBackLeftChannel()`, `getPeakVolumeBackLeftChannel()`

    - #### getPeakVolumeBackLeftChannel

          public int getPeakVolumeBackLeftChannel()

      gets the peak volume for the back left channel.
      Returns:
        the peak volume for the back left channel.
      See Also:
        `setPeakVolumeBackLeftChannel(int)`, `getRelativeVolumeAdjustmentBackLeftChannel()`

    - #### setPeakVolumeBackLeftChannel

          public void setPeakVolumeBackLeftChannel(int volume)

      sets the peak volume for the back left channel.
      Parameters:
        `volume` - the peak volume for the back left channel.
      See Also:
        `getPeakVolumeBackLeftChannel()`, `getRelativeVolumeAdjustmentBackLeftChannel()`

    - #### getRelativeVolumeAdjustmentCenterChannel

          public int getRelativeVolumeAdjustmentCenterChannel()

      gets the relative volume adjustment for the center channel.
      Returns:
        the relative volume adjustment for the center channel.
      See Also:
        `setRelativeVolumeAdjustmentCenterChannel(int)`, `getPeakVolumeCenterChannel()`

    - #### setRelativeVolumeAdjustmentCenterChannel

          public void setRelativeVolumeAdjustmentCenterChannel(int volume)

      sets the relative volume adjustment for the center channel.
      Parameters:
        `volume` - the relative volume adjustment for the center channel.
      See Also:
        `getRelativeVolumeAdjustmentCenterChannel()`, `getPeakVolumeCenterChannel()`

    - #### getPeakVolumeCenterChannel

          public int getPeakVolumeCenterChannel()

      gets the peak volume for the center channel.
      Returns:
        the peak volume for the center channel.
      See Also:
        `setPeakVolumeCenterChannel(int)`, `getRelativeVolumeAdjustmentCenterChannel()`

    - #### setPeakVolumeCenterChannel

          public void setPeakVolumeCenterChannel(int volume)

      sets the peak volume for the center channel.
      Parameters:
        `volume` - the peak volume for the center channel.
      See Also:
        `getPeakVolumeCenterChannel()`, `getRelativeVolumeAdjustmentCenterChannel()`

    - #### getRelativeVolumeAdjustmentBassChannel

          public int getRelativeVolumeAdjustmentBassChannel()

      gets the relative volume adjustment for the bass channel.
      Returns:
        the relative volume adjustment for the bass channel.
      See Also:
        `setRelativeVolumeAdjustmentBassChannel(int)`, `getPeakVolumeBassChannel()`

    - #### setRelativeVolumeAdjustmentBassChannel

          public void setRelativeVolumeAdjustmentBassChannel(int volume)

      sets the relative volume adjustment for the bass channel.
      Parameters:
        `volume` - the relative volume adjustment for the bass channel.
      See Also:
        `getRelativeVolumeAdjustmentBassChannel()`, `getPeakVolumeBassChannel()`

    - #### getPeakVolumeBassChannel

          public int getPeakVolumeBassChannel()

      gets the peak volume for the bass channel.
      Returns:
        the peak volume for the bass channel.
      See Also:
        `setPeakVolumeBassChannel(int)`, `getRelativeVolumeAdjustmentBassChannel()`

    - #### setPeakVolumeBassChannel

          public void setPeakVolumeBassChannel(int volume)

      sets the peak volume for the bass channel.
      Parameters:
        `volume` - the peak volume for the bass channel.
      See Also:
        `getPeakVolumeBassChannel()`, `getRelativeVolumeAdjustmentBassChannel()`

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