com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyRecommendedBufferSize

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

-     public class ID3v24FrameBodyRecommendedBufferSize
      extends ID3v24FrameBody

  A recommended buffer size frame body is associated with an ID3v2.4 `RBUF` `frame` which is used to indicate a buffer size to a server from which an .mp3 file is being streamed. Sometimes the server is aware of transmission or coding problems resulting in interruptions in the audio stream. In these cases, the size of the buffer can be recommended by the server using this frame. Embedded tags are generally not recommended since this could render unpredictable behaviour from present software/hardware.

  For applications like streaming audio it might be an idea to embed tags into the audio stream though. If the client connects to individual connections like HTTP and there is a possibility to begin every transmission with a tag, then this tag should include a recommended buffer size frame. If the client is connected to an arbitrary point in the stream, such as radio or multicast, then the recommended buffer size frame should be included in every tag. Every tag that is picked up after the initial/first tag is to be considered as an update of the previous one. For example, if there is a `TIT2` frame in the first received tag and one in the second tag, then the first should be 'replaced' with the second.

  The recommended buffer frame body contains the following fields:

  Recommended Buffer Size Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | bufferSize | the recommended size of the buffer
  2. | embeddedInfoFlag | indicates that an ID3 tag with the maximum size described in the bufferSize field may occur in the audiostream. In such case the tag should reside between two MPEG frames, if the audio is MPEG encoded.
  3. | offsetToNextTag | If the position of the next tag is known, the offset is calculated from the end of tag in which this frame resides to the first byte of the header in the next. This field is optional and may be omitted.

  The 'buffer size' should be kept to a minimum. There may be only one recommended buffer size frame in a tag.

  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
    `ID3v24FrameBodyRecommendedBufferSize()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyRecommendedBufferSize(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v24FrameBodyRecommendedBufferSize(int bufferSize, boolean embeddedInfoFlag, int offsetToNextTag)` This constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getBufferSize()` gets the buffer size.
    `int` | `getOffsetToNextTag()` gets the number of bytes until the next tag.
    `boolean` | `isEmbeddedInfoFlag()` gets the flag indicating whether an ID3 tag with the maximum size described in 'Buffer size' may occur in the audiostream.
    `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` | `setBufferSize(int bufferSize)` sets the size of the buffer.
    `void` | `setEmbeddedInfoFlag(boolean embeddedInfoFlag)` sets whether an ID3 tag with the maximum size described in 'Buffer size' may occur in the audiostream.
    `void` | `setOffsetToNextTag(int offsetToNextTag)` sets number of bytes until the next tag.
    `java.lang.String` | `toString()` gets a string representation of the recommended buffer size 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

    - #### ID3v24FrameBodyRecommendedBufferSize

          public ID3v24FrameBodyRecommendedBufferSize()

      The default constructor is called when creating a new frame. The default values used are:
      - 0 byte buffer size
      - embedded info flag set to false
      - 0 offset to next tag

    - #### ID3v24FrameBodyRecommendedBufferSize

          public ID3v24FrameBodyRecommendedBufferSize(int bufferSize,
                                              boolean embeddedInfoFlag,
                                              int offsetToNextTag)

      This constructor is called when creating a new frame.
      Parameters:
        `bufferSize` - size of the buffer in bytes.
        `embeddedInfoFlag` - indicates whether an ID3 tag with the maximum size described in 'buffer size' may occur in the audiostream.
        `offsetToNextTag` - optional field indicating the number of bytes until the next tag.

    - #### ID3v24FrameBodyRecommendedBufferSize

          public ID3v24FrameBodyRecommendedBufferSize(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 recommended buffer size 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.

    - #### getBufferSize

          public int getBufferSize()

      gets the buffer size.
      Returns:
        size of the buffer in bytes.
      See Also:
        `setBufferSize(int)`

    - #### setBufferSize

          public void setBufferSize(int bufferSize)

      sets the size of the buffer.
      Parameters:
        `bufferSize` - size of the buffer in bytes.
      See Also:
        `getBufferSize()`

    - #### isEmbeddedInfoFlag

          public boolean isEmbeddedInfoFlag()

      gets the flag indicating whether an ID3 tag with the maximum size described in 'Buffer size' may occur in the audiostream.
      Returns:
        whether an ID3 tag with the maximum size described in 'Buffer size' may occur in the audiostream.
      See Also:
        `setEmbeddedInfoFlag(boolean)`

    - #### setEmbeddedInfoFlag

          public void setEmbeddedInfoFlag(boolean embeddedInfoFlag)

      sets whether an ID3 tag with the maximum size described in 'Buffer size' may occur in the audiostream.
      Parameters:
        `embeddedInfoFlag` - boolean indicating whether an ID3 tag may occur in the audiostream.
      See Also:
        `isEmbeddedInfoFlag()`

    - #### getOffsetToNextTag

          public int getOffsetToNextTag()

      gets the number of bytes until the next tag.
      Returns:
        number of bytes until the next tag.
      See Also:
        `setOffsetToNextTag(int)`

    - #### setOffsetToNextTag

          public void setOffsetToNextTag(int offsetToNextTag)

      sets number of bytes until the next tag.
      Parameters:
        `offsetToNextTag` - number of bytes to the next tag.
      See Also:
        `getOffsetToNextTag()`

    - #### 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 recommended buffer size 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.