REAPEAKS file format v1.1 (last updated 5/14/2008)
------------------------------------------------------------------------------
Copyright (C) 2006-2008, Cockos Incorporated

A ReaPeaks file stores peak information for a media file.

Typically a ReaPeaks file is named with the media file's name plus a .ReaPeaks
extension, but it doesn't have to be (REAPER itself supports putting them in 
a temporary directory with a hashed name).

The file format is a binary format, with all multi-byte integers stored in 
Little Endian (Intel) format.

ReaPeaks file:
  4 bytes: "RPKM" (v1.0) or "RPKN" (v1.1) magic header
  1 byte integer: number of channels of source file (usually 1 or 2)
  1 byte integer: number of mipmaps. As of REAPER 2.x, the maximum 
                  mipmaps supported is 4.
  4 byte integer: samplerate of source file 
  4 byte integer: last modified time of source file (i.e. from stat() .st_mtime)
                  Note that REAPER will allow for small variations (a few 
                  seconds), as well as within a few seconds of one hour off 
                  (to allow for DST changes etc)
  4 byte integer: file size of source (i.e. from stat() .st_size). 
                  Note that these last two members are purely for making sure
                  that an updated file is detected--you can completely ignore
                  them on read if rebuilding peaks is not an option.
  <mipmap header 1>
  <mipmap header 2>
  <mipmap header ..>
  <mipmap header n>
  <mipmap data 1>
  <mipmap data 2>
  <mipmap data ..>
  <mipmap data n>

mipmap header format:
  4 byte integer: division factor (can be approx 4..1,000,000)
                  This value represents the number of samples represented by
                  each peak value. For example, if the source samplerate is 
                  44100, and each mipmap peak value represents 1 second, the
                  division factor is 44100. If the source samplerate is 44100,
                  and each mipmap peak value represents 100ms, then this value
                  is 4410, etc. NOTE: the first mipmap should be the highest 
                  resolution, and subsequent mipmaps should be decreasing in
                  resolution (increasing in division factor)
  4 byte integer: number of peak samples in this mipmap ("n")

mipmap data:

  The mipmap data for all mipmaps is stored sequentially, using the size of the
mipmaps from the previous mipmap header fields to determine the mipmap positions.

    If v1.1: <n * number of channels * 2> 2 byte integers: the peak data
       The peak data is a collection of 2 byte signed sample pairs (-32768 to 
       32767), maximum and minimum values for this interval. 
        Example: stereo samples (MX=max, MN=min, ???? = 2 bytes):
          L0MX L0MN R0MX R0MN L1MX L1MN R1MX R1MN ...
        Example: mono samples (MX=max, MN=min):
          L0MX L0MN L1MX L1MN L2MX L2MN ...
  -or-
    If v1.0: <n * number of channels> 2 byte integers: the peak data
       The peak data is a collection of 2 byte signed samples (-32768 to 32767).
       Note: REAPER (as of 1.0rc1) will calculate whether the peak is positive or 
       negative, but only uses the absolute value of the peak when displaying. 
       This effectively halves the dynamic range of the v1.0 peaks format.
        Example: stereo samples (???? = 2 bytes):
          LFT0 RGT0 LFT1 RGT1 LFT2 RGT2 ...
        Example: mono samples:
          LFT0 LFT1 LFT2 ...


Currently (as of REAPER 2.x), REAPER generates 3 peak mipmaps for each ReaPeaks:
  1. At approximately 400 peaks/sec (divfactor 110 at 44khz), depending on a
      preferences configuration.
  2. At approximately 10 peaks/sec (divfactor 4410 at 44khz)
  3. At approximately 1 peaks/sec (divfactor 44100 at 44khz)



<eof>