README

Recursively mirror a directory tree of FLAC audio files to AAC/OGG/MP3.
Source files can be filtered (by sub-directory, or full path) in order to
limit the files converted. The script will also attempt to retain all
meta-data fields in the output files.

At a Glance
===========

* Mirror directory tree of FLAC files audio files to AAC/OGG/MP3 (re-encoded
  using NeroAacEnc, oggenc, or LAME).
* Filter source tree using one or more sub-directory paths.
* By default, will only re-encode missing or out-of-date AAC/OGG/MP3 files.
* Optionally deletes orphaned output files.
* Multi-threaded encoding ensures full CPU utilization.
* Supports transfer of FLAC meta-data including *title*, *artist*, *album*.
* Converts FLAC replaygain field to Apple iTunes Sound Check.
* Optionally resizes and embeds album cover art JPEG files to destination
  files.
* Optionally copy cover art to destination directories.

Usage Model
===========

* Hard disk space is cheap, but flash-based media players are still limited
  in capacity.
* Create a lossy encoded "mirror" of your music files for portability.
* Setup a daily cron job to always keep your FLAC and AAC/OGG files
  synchronized.
* Re-encode your FLAC library to different AAC/OGG bit-rates in one command.

Running and Options
===================

Flacsync is run from the command-line, using the following format. ::

   flacsync [options] BASE_DIR [SOURCE ...]

``BASE_DIR``

Define the root path of a directory hierarchy containing desired input files
(FLAC).  A mirrored output directory will be created in the deepest path,
parallel to ``BASE_DIR``, and named after the selected output file
extension.

For example, if ``BASE_DIR`` is ``/data/flac``, the output dir will be
``/data/aac``.

``SOURCE ...``

Optional dir/file argument list to select source files for transcoding.  If
not defined, all files in ``BASE_DIR`` will be transcoded.  The ``SOURCE``
file/dir list must be relative from ``BASE_DIR`` or the current working
directory.

--version            show program's version number and exit

-h, --help           show this help message and exit

-c THREAD_COUNT, --threads=THREAD_COUNT
                     set max number of encoding threads [default:2]

-f, --force          force re-encode of all files from the source dir; by
                     default source files will be skipped if it is
                     determined that an up-to-date copy exists in the
                     destination path

-t ENC_TYPE, --type=ENC_TYPE
                     select the output transcode format; supported values
                     are 'aac','ogg','mp3' [default:aac]

-o, --ignore-orphans
                     prevent the removal of files and directories in the
                     dest dir that have no corresponding source file

-d DEST_DIR, --destination=DEST_DIR
                     define alternate destination output directory to
                     override the default. The standard default destination
                     directory will be created in the same parent directory
                     of BASE_DIR. See BASE_DIR above.

-r, --resize         enable resizing of cover art; by default the art that
                     is found will be saved to file without resizing.

-j, --copy-cover-art
                     in addition to embedding cover art, copy image file
                     directly to the desination sub-folder.


AAC Encoder Options:
---------------------

 -q AAC_Q, --aac-quality=AAC_Q
                     set the AAC encoder quality value, must be a float
                     range of 0..1 [default:0.35]

OGG Encoder Options:
--------------------
 -g OGG_Q, --ogg-quality=OGG_Q
                     set the Ogg Vorbis encoder quality value, must be a
                     float range of -1..10 [default:5]

MP3 Encoder Options:
--------------------
 -m MP3_Q, --mp3-quality=MP3_Q
                     set the Lame MP3 encoder quality value, must be a
                     initeger range of 0..9 [default:3]


Examples
========

1. Encode a directory of FLAC files to AAC. Output file will be written to
   ``/music/aac``.
   ::

      flacsync /music/flac
      cd /music/flac; flacsync .

2. Encode a directory of FLAC files to AAC. Output files will be written to
   ``/ipod``.
   ::

      flacsync -d /ipod /music/flac

3. Encode a directory of FLAC files to high-quality OGG, using 4 CPU
   threads.
   ::

      flacsync -c 4 -t ogg -g 9 /music/flac

4. Force re-encode two albums of FLAC files, even if the AAC files exist.
   ::

      flacsync -f /music/flac artist1/album artist2/album
      cd /music/flac; flacsync -f . artist1/album artist2/album