shape
*.m3u
Trees

  *****************************************************************************
 *******************************************************************************
*******                                                                   *******
******      CONTENTS                                                       ******
*******                                                                   *******
 *******************************************************************************
  *****************************************************************************


  MPPDEC -- The MPEGplus / Musepack(tm) Decoder

     1. General usage
     2. Syntax
     3. Options
     4. Output files
     5. Wild card support
     6. Known Bugs
     7. Future Plans


  MPPENC -- The MPEGplus / Musepack(tm) Encoder

     8. General usage
     9. Syntax
    10. Options
    11. Input files
    12. Output files


  REPLAYGAIN -- Loudness and Peak Level Processor

    13. General usage
    14. Syntax
    15. Options
    16. Input files


  TAGGER -- A Simple Tagging Utility

    17. Usage
    18. File naming convention


.mpc Musepack(tm) is a registrated trademark of Andree Buschmann.
Windows(tm) is a registrated trademark of Microsoft Corperation.
OS/2(tm) is a registrated trademark of International Business Machines.



  *****************************************************************************
 *******************************************************************************
*******                                                                   *******
******      DECODER                                                        ******
*******                                                                   *******
 *******************************************************************************
  *****************************************************************************


1. General usage

There are several possibilities to use this MPEGplus decoder:

    - decode ONE MPEGplus file to ONE PCM file
    - decode MULTIPLE MPEGplus files to MULTIPLE PCM files
    - decode MULTIPLE MPEGplus files to ONE big PCM file which contains
      the audio of all input files
    - decode ONE or MULTIPLE MPEGplus files to the standard output
      for pipe processing
    - play ONE or MULTIPLE MPEGplus files

--------------------------------------------------------------------------------

2. Syntax

    - to decode ONE MPEGplus file to ONE PCM file:

          mppdec input.mpc output.wav

    - to decode MULTIPLE MPEGplus files to MULTIPLE PCM files:

          mppdec input1.mpc input2.mpc input3.mpc output_directory

      the output files have the same name as the input files. Only an
      additional extension is added. So you got the files:

          output_directory/input1.mpc.wav
          output_directory/input2.mpc.wav
          output_directory/input3.mpc.wav

    - to decode MULTIPLE MPEGplus files to ONE PCM files which contains
      the audio of all input files

          mppdec input1.mpc input2.mpc input3.mpc outputfile

      If a file 'outputfile' exists and has the extension '.mpc', '.mp2',
      '.mp3', '.mpp' or '.mpp' it is NOT used as output file. This is
      to avoid unintended loss of data by things like:

          mppdec *.mpc

      This is handled like

          mppdec *.mpc -

      if stdout is associated with a file or a pipe,
      or like

          mppdec *.mpc /dev/audio

      if stdout is associated with a terminal to avoid binary output to a
      terminal which is really silly.

    - to decode ONE or MULTIPLE MPEGplus files to the standard output
      for pipe processing

          mppdec input1.mpc input2.mpc input3.mpc -

      It is also possible to call

          mppdec input1.mpc input2.mpc input3.mpc

--------------------------------------------------------------------------------

3. Options

    --silent
            Do not write any message while decoding. Should be the first
            option if also the copyright message should be suppressed.
    --start x
    --skip x
            Start decoding at x seconds. Negative values from -0...-100 are interpreted
            as percent (0...100%) of the total title length. Default: 0 (from start)
    --dur x
            Decode a period of x seconds. Negative values from -0...-100 are interpreted
            as percent (0...100%) of the total title length. Default: -100 (all)
    --noprev
            Do no clipping prevention. Leave original level. Default.
    --prev
            Do clipping prevention. The decoder reduces the output level if needed
            to significantly reduce clippings introduced by the typical envelope changes
            of lossy audio codecs.
    --scale x
            Scale output by an additional factor. Factor can be in the range from -10...+10.
            Negative values change the phase, values between -1 and +1 reduce level,
            other increase level. If using with --gain, --scale is an
            additional scaler. If --prev is used, clipping is always
            prevented even when you are using very large scalers.
    --gain x
            Replaygain correction:
            0: No usage of replaygain, if using clipping protection this is
               done on a title by title base, i.e. every title's gain is
               reduced so that exactly this title is not clipped.
            1: No usage of replaygain, if using clipping protection this is
               done on an album base, i.e. every title's gain is
               reduced so that:
                 - every title of an album is attenuated by the same amount
                 - no title of this album is clipped
            2: Usage of the title based replaygain, rest like 0.
            3: Usage of the album based replaygain, rest like 1.
    --random
            Mix all this option following files. Should be the last option of any.
            This option following options can't be associated with a file.
    --wav
            PCM Output is a Microsoft WAVE file. Default.
    --aiff
            PCM Output is a Apple/SGI Audio Interchange Format file
    --raw
            PCM Output is a raw PCM 2 channel file with the machine's endianess
    --raw-le
            PCM Output is a raw PCM 2 channel file with little endianess
    --raw-be
            PCM Output is a raw PCM 2 channel file with big endianess

    Only mppdec16, mppdec24, mppdec32:
    --bits x
            Number of valid bits in the PCM output. Default is all bits.
    --dither x
            Amount of dither added. 0 is no dither, 1 is +/-1 LSB triangular dither
            (if no noise shaping is applied). Useful is 0.0...1.0 depending on the
            noise floor of the original audio, listening level, used bits and much
            more. Default is a good guess depending on the bits used (--bits) and
            the usage of --shape.
    --shape x
            Select noise shaping type. Default is off. Noise shaping also
            affects spectral distribution of the added dither (if used).
            This reduces noise by up to 15 dB and reduces artefacts but introduces
            a lot of ultrasonic noise.

              x   type    audible noise   unweighted noise
              0   none        0 dB            0 dB
              1   light      -5 dB           +3 dB
              2   medium    -10 dB          +12 dB
              3   heavy     -15 dB          +30 dB



Clipping prevention/Replaygain control:

Clipping prevention is done by the decoder (command line tool mppdec
or plugins). The decoder needs some information inside the MPEGplus file
which is not written by the encoder but by the replay gain tool.
It writes some bytes in the header of the MPEGplus file.

Therefore the procedure is:
  - RIP the CD you have bought
  - Encode the PCM files to MPEGplus files
  - Use replaygain to set this information in the MPEGplus files:

    replaygain --auto        <list_of_files>
      Determine average loudness and peak level of all
      files automatically and store it in the files

    replaygain --autoHQ      <list_of_files>            (not yet implemented)
      like --auto, but also regards overdrives in the D/A converter.
      Much slower, but more secure for critical material.

    replaygain --list        <list_of_files>
      List title based settings of the listed files

    replaygain --listall     <list_of_files>
      List title and album based settings of the listed files,
      a display width of 100 or 132 is recommended for this list

    replaygain <value_in_dB> <list_of_files>
      Set title based replay gain to the given value

    replaygain 0 <list_of_files>
      Reet title based replay gain to the original value of 0.

Level corrections I've found are between -12 dB and +24 dB for titles
and between -9 dB and +4 dB for albums. Title based correction
are correct in the region of +/- 3 dB for most of the titles (98%),
for albums of +/-1 dB. Manual correction of title based replaygain
is seldom necessary, but possible. Often it is that a silent spacer
titles is played too loud.

Replay gain corrections makes loud titles more silent and silent titles
louder. This reduces (also if clipping prevention is not used) clipping
for overdriven loud titles (pop music since the middle of the 90's),
but also increases the probability of distortions of titles with a
high dynamic, because they become louder. The setting is a balance between
these two problems.

Well recorded audio is not many changed in loudness. If the loudness
is reduced the audio engineer has badly leveled the CD so it is likely
that the CD sounds distored. They misuse the CD audio level to enlarge
the loudness and significantly reduce quality.

Don't complain that loudness equalization reduces level of overdriven CDs!
Prevention this is not possible except by distoring ALL CDs in the same
way as this stupid CDs.

Take your instruction manual. Search the item "volume control" and
use, if available, this control to control loudness.

Decreased level has nothing to do with lost quality if you do not use a 8 bit sound card.
A volume control on an audio gadget also don't have something to do with quality loss.
Most people don't have the volume control at the right end and I also think quality
is not the best if volume control is on the right end.


Possible replay options:

  --scale x             linear scaler by a factor (1 = dflt., 0.5 = half, 2 = double)
  --prev                activate clipping prevention
  --noprev              deactivate clipping prevention (dflt)
  --gain 0|1|2|3        replay gain mode 0, 1, 2 or 3 (0 = dflt)


Useful combinations:

Change volume. 0.5 reduces volume, 2 enlarges volume and very likely introduce additional
distortion. --scale 1 you don't need to use, it's default. --scale 0 can be used to test
MPEGplus streams or to determine the exact length of a decoded WAV.

  --scale 0
  --scale 0.5
  <no options>
  --scale 2
  --scale 10


With title based clipping prevention. If a title would clip its level is reduced
as much as necessary to prevent clippings.

  --scale 0.5 --prev
              --prev
  --scale 2   --prev
  --scale 10  --prev


Same, but clipping prevention is done on an album base. All titles of one album
are level reduced by the same amount so no title of the album is clipped.

  --scale 0.5 --prev --gain 1
              --prev --gain 1
  --scale 2   --prev --gain 1
  --scale 10  --prev --gain 1

Without "--prev" "--gain 1" make no sense.


With title based loudness equalization without clipping protection:

  --scale 0.5 --gain 2
              --gain 2
  --scale 2   --gain 2
  --scale 10  --gain 2


With title based loudness equalization with clipping protection:

  --scale 0.5 --gain 2 --prev
              --gain 2 --prev
  --scale 2   --gain 2 --prev
  --scale 10  --gain 2


With album based loudness equalization without clipping protection:

  --scale 0.5 --gain 3
              --gain 3
  --scale 2   --gain 3
  --scale 10  --gain 3


With album based loudness equalization with clipping protection:

  --scale 0.5 --gain 3 --prev
              --gain 3 --prev
  --scale 2   --gain 3 --prev
  --scale 10  --gain 3


Trouble shouter (one possibility per line)

  - I hear distortions
        --prev
        Reduce Volume control to avoid amplifier overload
  - Too silent
        Pump up the volume control
  - Too loud
        --prev --gain 1
        additional use volume control
        additional use --scale 0.5
  - As loud as possible
        --scale 3 and turn volume control to the right end
  - I want to damage my hearing completely
        --scale 99
  - ... but without clippings
        --scale 3 --prot
    (This do avoid clippings in the MPC decoder domain, not possible
    clippings in DA converters or amplifiers)
  - loudness switches between titles due to clipping prevition
    and replay gain correction disturbs:
        use --gain 1 or 3 instead of --gain 0 or 2

--------------------------------------------------------------------------------

4. Output files

    (none)

        Plays the files if sound support is available, otherwise write PCM
        data to standard output

    (none) > file

        Write the PCM data to 'file'

    (none) > device

        Write the PCM data to 'device'. If the device is an audio device the
        parameters are set properly. Note that the ESounD device (/dev/esd)
        and the Windows Audio device (/dev/audio) and also the Windows Null
        device are virtual devices only existing inside the program. Windows
        has a real Null Device which is called 'nul'. Note that -- if device
        is not seekable -- the WAVE header is not fully correct.

    (none) | program

        PCM data is written to the standard input of program.  Note that the
        WAVE header is not fully correct.

    file

        Write the PCM data to 'file'

    directory

        Write the PCM data to 'directory/filename.new_extenstion'.  The old
        extention is still part of the name, it is not removed.  So you got
        names like 'The Power of Love.mpc.wav'.

    -
        Write the PCM data to standard output

    - > file

        Write the PCM data to 'file'

    - > device

        Write the PCM data to 'device'. If the device is an audio device the
        parameters are set properly. Note that the ESounD device (/dev/esd)
        and the Windows Audio device (/dev/audio) and also the Windows Null
        device are virtual devices only existing inside the program. Windows
        has a real Null Device which is called 'nul'. Note that -- if device
        is not seekable -- the WAVE header is not fully correct.

    - | tee > file

        Write the PCM data to 'file'. Note that the WAVE header is not fully
        correct.

    - | tee > device

        Write the PCM data to 'device'. If the device is an audio device the
        parameters are NOT set properly. Note that the WAVE header is
        always not fully correct. THIS IS A GENERAL PROBLEM OF PIPES. THEY
        ARE NOT FULLY TRANSPARENT, they can't forward ioctl() and lseek()'s.

    - | program

        PCM data is written to the standard input of program.  Note that the
        WAVE header is not fully correct.

    /dev/null

        Do a full decode and discard data

    /dev/dsp*
    /dev/audio* (Unix)

        Decode and write the data to an audio device. There are multiple
        audio devices possible:
            1st device:  /dev/dsp0, /dev/audio0, /dev/dsp, /dev/audio
            2nd device:  /dev/dsp1, /dev/audio1
            3rd device:  /dev/dsp2, /dev/audio2
            4th device:  /dev/dsp3, /dev/audio3
        Parameters are set properly.

    /dev/esd (Unix)

        Decode and write the data to the enlightenment sound daemon.
        Parameters are set properly.  If the sound daemon runs with a sample
        frequency of 48 kHz sound quality may be very poor. A big advantage
        is the multiple open feature of the sound daemon, sources will be
        mixed in this case.

    /dev/audio (Sun)

       Decode and write PCM data to the Sun Onboard-Audio device. Parameters
       are set properly.

    /dev/audio (Windows/Intel)

       Decode and write PCM data to the Windows WAVEOUT multimedia
       subsystem. Parameters are set properly.


--------------------------------------------------------------------------------

5. Wild card support

MS-DOS
    - Only '*' and '?' are supported
    - You can't address directory with wild cards, only files
    - '*' can only be the last part of the basename or the extension, i.e.
      things like:
          mppdec *dance.mpc output.wav
      do not work.

Windows
    - Only '*' and '?' are supported
    - You can't address directory with wild cards, only files
    - Attendion: There are a lot of bugs in the MS VC++ wildcard support
      if you heavily use charcters with bit 7=1.

Unix
    - You can address directory and files with wild cards, i.e. things like:
          $ mppdec */*.mpc output.wav
      work.
    - You can also use [] and {} shell pattern

--------------------------------------------------------------------------------

6. Known Bugs

    - CBR from older Streamversion do not work
    - Noise shaping has a little bug if used with multiple input file support
    - special prepared (invalid) MPEGplus files can cause Segmentation faults
    - No resynchronization on bit errors
    - Playback of any less than 1152 samples of the file


--------------------------------------------------------------------------------

7. Future Plans

    - support for Linux ALSA
    - support for OS/2 audio
    - support of G4 PPC Altivec
    - integer decoder (Motorola 560xx or TI TMS320C30)









  *****************************************************************************
 *******************************************************************************
*******                                                                   *******
******      ENCODER                                                        ******
*******                                                                   *******
 *******************************************************************************
  *****************************************************************************


8. General usage

There are several possibilities to use this MPEGplus encoder:

    - encode ONE Wavefile to ONE MPEGplus file
    - encode MULTIPLE Wavefiles files to MULTIPLE MPEGplus files
    - encode MULTIPLE Wavefiles files to ONE big MPEGplus file which contains
      the audio of all input files
    - encode ONE or MULTIPLE Wavefiles files to the standard output
      for pipe processing
    - record ONE MPEGplus file from the soundcard (if computer is fast enough)

--------------------------------------------------------------------------------

9. Syntax

    - to encode ONE PCM file to ONE MPEGplus file:

          mppenc input.wav output.mpc
      or
          mppenc input.wav

      if output name should be derived from the input name
      by substitution of the extention by .mpc

    - to encode MULTIPLE PCM files to MULTIPLE PCM files:

          mppdec input1.mpc input2.mpc input3.mpc output_directory

      the output files have the same name as the input files. Only an
      additional extension is added. So you got the files:

          output_directory/input1.mpc.wav
          output_directory/input2.mpc.wav
          output_directory/input3.mpc.wav

    - to decode MULTIPLE MPEGplus files to ONE PCM files which contains
      the audio of all input files

          mppdec input1.mpc input2.mpc input3.mpc outputfile

      If a file 'outputfile' exists and has the extension '.mpc', '.mp2',
      '.mp3', '.mpp' or '.mpp' it is NOT used as output file. This is
      to avoid unintended loss of data by things like:

          mppdec *.mpc

      This is handled like

          mppdec *.mpc -

      if stdout is associated with a file or a pipe,
      or like

          mppdec *.mpc /dev/audio

      if stdout is associated with a terminal to avoid binary output to a
      terminal which is really silly.

    - to decode ONE or MULTIPLE MPEGplus files to the standard output
      for pipe processing

          mppdec input1.mpc input2.mpc input3.mpc -

      It is also possible to call

          mppdec input1.mpc input2.mpc input3.mpc


--------------------------------------------------------------------------------

10. Options

10.1  Basic Options

    --silent
            Do not write any message while encoding. Should be the first
            option if also the copyright message should be suppressed.
    --start x
    --skip x
            Skip beginning of the audio file. Value is in seconds.
            Default is 0.
    --verbose
            Increase verbosity. You can use this option twice to get the highest
            currently supported verbosity
    --scale x
            scale input signal. "1" is default, "0.5" halves level, "2" doubles levels.
            Use with care. Do not use to prevent clippings in the decoding phase
            (there are two reasons: First you can't reconstruct the original loudness,
            Second you don't know the multiplier you need. This can be 0.6...1.0,
            and the typical scaling by 0.7 or 0.98 don't help significantly).
    --delinput
            delete input file after encoding. Default is off.
    --forcewrite
            Allowing overwriting of existing files. Default is off.
    --fadeshape x fade shape (dflt: 1.0)
            Select a fade shape. Small values are first fast fading then slow fading.
            Large values the opposite.
            See http://www.uni-jena.de/~pfk/mpp/img/fade.png
    --fadein x
            Fade-In time in seconds. Default is 0.
    --fadeout x
            Fade-Out time in seconds. Default is 0.


10.2  Profile Options

    Quality should be choosen by using the following options:

    --thumb       Low quality. Sounds dull and artefacts are audible
                  typical bitrates:  61...75...90 kbps
                  maximum bitrate: 90 kbps

    --radio       Medium...high quality. Should be distinguishable from the original.
                  Some lack of stereo imaging.
                  typical bitrates: 121...139...169 kbps
                  maximum bitrate:  237 kbps

    --standard    High quality. Normally undistinguishable from the original in ABX tests.
                  typical bitrates: 146...172...198 kbps
                  maximum bitrate:  303 kbps

    --xtreme      High quality. Normally undistinguishable from the original in ABX tests.
                  Some reserve for listeners with "Golden Ears" or for transcoding.
                  typical bitrates: 172...204...224 kbps
                  maximum bitrate:  329 kbps

    --insane      High quality. Normally undistinguishable from the original in ABX tests.
                  A lot of reserve for listeners with "Golden Ears" or for transcoding.
                  Full bandwidth encoding also for inaudible signals.
                  typical bitrates: 240...242...288 kbps
                  maximum bitrate:  383 kbps

    Low bitrates are typcial for: Samual Baraber:  Adagio for Strings
    Medium Bitrates are for:      Sarah McLachlan: Building A Mystery
    High Bitrates are for:        Giora Feidman:   Jewish Folk Song
    Peak levels are by:           Fatboy Slim:     Kalifornia


10.3  Expert options affecting quality

Tweaking of quality for very experienced users. Do not use an option you can't explain!

    --ms x
            Select Mid/Side Stereo coding
              0: independent coding of channels
              1: use normal Mid/Side coding
              2: use enhanced Mid/side coding (default)
    --cvd x
            ClearVoiceDetection
              0: off (much faster, little bit less datarate, less quality)
              1: on  (slower, some more datarte, better quality). Default.
    --bw x
            Maximum bandwidth in Hz
            Default: Full bandwidth if necessary
    --ltq x
              iso: ISO threshold in quiet (not recommended)
              ank: more sensitive threshold in quiet (dflt)
              fil: even more sensitive threshold in quiet

    --ltq_gain x
            Raise absolute threshold of hearing by x dB. Default: 0 dB
    --ltq_max x
            Maximum level for ltq (dflt: 83.0 dB)
    --minSMR x
            Minimum SMR of x dB over full bandwidth (dflt: 0.0)
    --tmpMask x
            exploit postmasking: 0: off, 1: on (dflt: 1)
    --nmt x
            set the NMT-value to x dB (dflt:  6.0)
    --tmn x
            set the TMN-value to x dB (dflt: 18.0)
    --ans x
            Adaptive Noise Shaping Order: 0: off, 1...5: on (dflt: 5)
    --ltq_var x
            adaptive threshold in quiet: 0: off, 1: on (dflt: 1)
    --shortthr x
            short FFT threshold (dflt:  5.0)
    --transdet x
            slewrate for transient detection (dflt: 100.0)
    --minval x
            calculation of MinVal (0:old, 1:buschmann, 2:klemm)

----------------------------------------------------------------------

11. Input files

PCM input can come from:

    A Microsoft WAVE file with linear PCM input
    From the standard input
    From a sound card
    From several lossless compressed (not data reduced!) PCM formats

11.1  Microsoft WAVE

  Microsoft WAVE format, 44.1 kHz, 8...32 bit, 1...8 channels

11.2  Standard Input

  -           for stdin (only WAVE files)

11.3  Sound card

  /dev/audio1  for soundcard (OSS only at the moment)

11.4  Lossless compressed PCM formats

                Windows         Linux           Solaris
    LPAC        okay (1.36)     okay            okay
    FLAC        -               okay            okay
    APE         -               -               -
    RKAU        -               -               -
    SZIP        okay            okay            okay
    Shorten     okay            okay            okay

--------------------------------------------------------------------------

12. Output files

Output_File must be (otherwise file name is generated from Input_File):
  File name  with extention MPC, MP+ or MPP
  -          for stdout
  /dev/null  for trash can







================================================================================
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""


--- Personal remarks ---

Shared lib für Encoder + Decoder
XMMS/WinAmp-Unterstützung über Shared Lib
Quelle dokumentieren
Endian-Umrechnung im Dekoder, damit sind 64 bit und Memory Mapped Files möglich
Clipping-Restauration des Coders bei 0dB+ - Aufnahmen
SV8
Abbruch bei vorzeitigem Dateiende sauberer!
===================================================================


Kopierten Filterkoeffizienten in New_V überflüssig machen?

Einige Optimierungen in Helper2 und Helper3

pfacc für Scalar
abx mit adaptiver Punktvergabe für richtig/falsch
typischer Bitverbrauch für die einzelnen Sektionen bestimmen

Erase Filterbank vor jedem Titelwechsel: Sinnvoll oder schädlich?

---------------------------------------------
Doku Webpage for 16 bit and 32 bit options.


Schreiben von Sparse WAV-Files bei Nullen

WAVCMP portabel machen.
------------------------------------
mpp.h in Makefile includen und einzelne Linktime Features dort ein- und ausschalten.

16 bit und 32 bit zu einer Version, die 16, 24 und 32 bit kann, zusammenfassen.
--------------------------------------------------------------------------------

ID3 V1/1.1 Tags kopieren bei Nichtpipe-Modus?
Uebersteuerungen bei Noiseshapen beim Berechnen der Recent Errors ignorieren?
