Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Recursively mirror a directory tree of FLAC audio files to AAC or OGG.

Project description

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 ...]


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.


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
 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]


  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

Project details

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page