AtOM/doc/config

On first launch, AtOM will create an example configuration file for you. This is
only an example, suitable to *my* needs (I'm lazy).
Default config file is ~/.atom/atom.cfg.

The file is divided in sections, beginning with [<sectionname>]. The section
ends where the next one begins. Inside each sections, properties are defined
with <key><space><value>, where <space> can be either spaces, tabulations, or a
mix of both. <key> is always a single word. <value> shall never be quoted,
whether it contains spaces or not.

For example the following defines 'path' as '/usr/share/the big music library':
path        /usr/share/the big music library
If '/usr/share/the big music library' is quoted, quotes would be included in the
value.

Sections:
[general]
  This section contains parameters of the program itself.

  * max-load <load>: Integer. Defines how parallel processing will behave. AtOM
      will try to keep the 1 minute load average between <load> and <load>+1 by
      adjusting concurrency.
      Initial concurrency will be set to half of that value.
  * load-interval <seconds>: Integer. How often should we check the load average
      and adjust concurrency. Set this too low, and concurrency may be increased
      too quickly. Set this too high, and AtOM will not adapt quickly enough to
      load increase. In both cases, your hard drive will suffer. In my
      experience, 30 seconds is a good value.
  * ionice <class> [niceness]: IO-hungry processes will be run with ionice class
      <class> and niceness [niceness] (if applicable). See man ionice for details.
  * temporary-directory <directory>: String. Name speaks for itself: this is
      where FIFOs (for communicating with sqlite) and temporary WAVE files will
      be created.  Note that debug logs (if enabled) will go there too.
      Default: ~/.atom/tmp
  * database <file>: String. Where the SQLite database should be stored.
      Default: ~/.atom/atom.db
  * debug <level>: Integer. Currently defined values:
      * 1: few additional status informations.
      * 3: log SQL queries.

[source]
  This section defines where are the files you want transcoded.

  * path <directory>: String. The root of your collection.
      Default: /var/lib/mpd/music
  * skip <directory>: String. Files in <directory> will be ignored. Note that
      <directory> can be any expression accepted by find.

[<some arbitrary string>]
  Each section not named 'general' or 'source' will define a new destination.

  Common parameters:
   Mandatory parameters:
    * path: Where files will be written
    * format: ogg, opus or mp3. Other formats may appear in the future - feel
      free to implement your preferred format.

   Optional parameters:
    * normalize <yes>/<no>: Normalize output files.
    * rename <string>: Destination files will be named according to <string>,
      after expansion of special strings:
        %{album},
        %{albumartist},
        %{artist},
        %{disc},
        %{genre},
        %{title},
        %{track},
        %{year}.
      Untagged files or files in unrecognized formats will not be changed.
    * fat32compat <yes>/<no>: Rename files for compatibility with FAT32
      filesystems.
    * skip_mime-type <mime-type>: Files with mime-type <mime-type> will not
      be included in that destination. For more than one mime-type, use multiple
      times, as needed. The '*' character is a wildcard.
    * copy_mime-type <mime-type>: Same as skip_mime-type, except that files
      matching will be copied as-is to tha destination. E.g. image/* will copy
      covers and other images to the destination. In fact, AtOM will try to use
      hard links instead of copies.
    * channels <number>: Files with more than <number> channels will be
      downmixed. Useful if you create files for telephony music-on-hold.
    * frequency <hertz>: Files will be resampled as needed to <hertz>Hz
      sampling-rate. Shoutcast/Icecast streams require a constant sampling-rate.
      Telephony systems often require a sample rate of 8000Hz.
    * higher-than <bitrate>: Integer. Only reencode files with bitrates higher
      then <bitrate>kbps. This only applies if sample-rate, channel count and of
      course format are equal. If unset, only files with bitrates equal to that
      of the target will be copied (actually, hardlinking will be attempted
      first). As Ogg Vorbis target quality is not defined by its bitrate, Ogg
      Vorbis files will always be reencoded if unset.

  Ogg parameters:
    * quality <quality>: The quality parameter of oggenc. See man oggenc for
      more info. This is the only mode supported and planned. Still, if you want
      to be able to use bitrate settings, feel free to fork and file a pull
      request.
  Opus parameters:
        Please note that Opus supports only the following sample-rates: 8000,
        12000, 16000, 24000, and 48000 Hz. So don't set resampling on an Opus
        destination to any other value or files will be resampled twice.
    * bitrate <bitrate>: Set (VBR) bitrate to <bitrate>. Note that while Opus
      allows for decimal values, AtOM does not. The reason for this is simple:
      we do numeric comparisons, and Bash only manipulates integers.
    * loss <percent>: If you intend to stream the resulting files over an
      unreliable protocol, you may want to make use of Opus' Forward Error
      Correction algorythm. See the Opus-codec.org website for details.
      Default: 0
  MP3 parameters:
    * bitrate <bitrate>: Set ABR to <bitrate>. Again, if you want CBR or any
      other mode supported by lame, please fork and file a pull request.
    * noresample <yes>/<no>: LAME may decide to encode your file to a lower
      sampling-rate if you use a low bitrate. Setting this to yes will
      append --resample <original file's rate>, preventing any resampling from
      happening.