doc: Update example.cfg

Fixes #23

doc/example.cfg

@@ -1,44 +1,174 @@
 [general]
-ionice			3
+# This section contains parameters of the program itself.
-max-load		6
+
-load-interval		30
+# * max-load <load>: Integer. Defines how parallel processing will behave. AtOM
-temporary-directory	%HOME%/.atom/tmp
+#     will try to keep the 1 minute load average between <load> and <load>+1 by
-database		%HOME%/.atom/atom.db
+#     adjusting concurrency.
-debug			0
+#     Initial concurrency will be set to half of that value.
+max-load		16
+
+# * 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.
+load-interval		10
+
+# * ionice <class> [niceness]: IO-hungry processes will be run with ionice class
+#     <class> and niceness [niceness] (if applicable). See man ionice for details.
+ionice			3 
+
+# * 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.
+temporary-directory	/tmp/AtOM-user/
+
+# * database <file>: String. Where the SQLite database should be stored.
+database		/home/user/.local/share/AtOM/atom.db
+
+# * debug <level>: Integer.
+#    0: No debug output, encoding and decoding errors logged to 
+#       <temporary-directory>/workerN.log
+#    1: Print some debug to stdout, log decoding and encoding commands to
+#       <temporary-directory>/workerN.log
+#    3: log SQL queries to <temporary-directory>/debug.log
+#debug			1
+
 
 [source]
-path		/var/lib/mpd/music
+# This section defines where are the files you want transcoded.
-skip		/last
-skip		/lastfm
-skip		/zzz-atrier
 
-[Ogg]
+# * path <directory>: String. The root of your collection.
-path		/mnt/Musique-OggQ2
+#     Default: /var/lib/mpd/music
-format		vorbis
+path			/mnt/Musique
-quality		1
+
-normalize	yes
+# * skip <directory>: String. Files in <directory> will be ignored. Note that
-channels	2
+#     <directory> can be any expression accepted by find.
-frequency	44100
+skip			/lost+found
+skip			/last
+skip			/lastfm
+skip			/zzz-atrier
+
+[Vorbis]
+# Each section not named 'general' or 'source' will define a new destination.
+
+# Common parameters:
+#  Mandatory parameters:
+#   * enabled: Whether or not to treat this destination (1=true/0=false)
+enabled			1
+
+#   * path: Where files will be written
+path			/mnt/Musique-OggQ2
+
+#   * format: copy, ogg, opus or mp3. Other formats may appear in the future -
+#   feel free to implement your preferred format.
+format			vorbis
+
+# 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.
+quality			1
+
+# Optional parameters:
+#   * normalize <yes>/<no>: Normalize output files.
+normalize		yes
+
+#   * rename <string>: Destination files will be named according to <string>,
+#     after expansion of special strings:
+#       %{album},
+#       %{albumartist},
+#       %{artist},
+#       %{disc},
+#       %{genre},
+#       %{releasecountry},
+#       %{title},
+#       %{track},
+#       %{year}.
+#     Untagged files or files in unrecognized formats will not be changed.
+rename			%{genre}/%{albumartist}/%{year}-%{album}-%{releasecountry}/%{disc}%{track}--%{artist}-%{title}
+
+#   * fat32compat <yes>/<no>: Rename files for compatibility with FAT32
+#     filesystems.
+fat32compat		yes
+
+#   * ascii-only <yes>/<no>: Rename files for compatibility with ASCII-only
+#     systems.
+ascii-only		no
 
 # you should not skip or copy application/octet-stream, they could be something
 # similar to "Audio file with ID3 version 2.4.0, unsynchronized frames"
-copy_mime-type	image/*
+
-copy_mime-type	text/*
+#   * 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.
+skip_mime-type		inode/x-empty
+skip_mime-type		audio/midi
+skip_mime-type		image/*
+skip_mime-type		text/*
+skip_mime-type		application/pdf
+skip_mime-type		application/javascript*
+skip_mime-type		very short file (no magic)
+
+#   * copy_mime-type <mime-type>: Same as skip_mime-type, except that files
+#     matching will be copied as-is to the 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.
+copy_mime-type		image/*
+
+#   * copy_extension <extension>: Copy files whose name and with ".<extension>"
+copy_extension		txt
+
+#   * channels <number>: Files with more than <number> channels will be
+#     downmixed. Useful if you create files for telephony music-on-hold.
+channels		2
+
+#   * 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.
+frequency		44100
+
+#   * 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.
+higher-than		200
 
 [Opus]
+enabled		1
 path		/mnt/Musique-opus
 format		opus
+
+# Opus parameters:
+#   * 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.
 bitrate		96
+
 normalize	yes
 frequency	48000
 copy_mime-type	image/*
 copy_mime-type	text/*
 
 [MP3]
-path		/mnt/Musique-mp3.test
+enabled		1
+path		/mnt/Musique-mp3
 format		mp3
+
+# 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.
 bitrate		96
+
+#   * 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.
 noresample	yes
+
 normalize	yes
 higher-than	128
 
@@ -50,6 +180,7 @@ skip_mime-type	image/*
 skip_mime-type	text/*
 
 [asterisk]
+enabled		1
 path		/mnt/Musique-asterisk
 format		vorbis
 quality		0