Transfer and transcode your music at the same time
Clone or download
DarwinAwardWinner Properly apply default encoder options
Previously, the default encoder options were set too late for them to
have any effect. This sets them earlier so that they are actually
Latest commit 9c97372 Sep 26, 2017


Transfercoder: Transfer and transcode your music

This script is my answer to the common problem of wanting to put one's music library onto a device that doesn't support some of your music formats. All the solutions that I've seen to this problem have at least one of the following drawbacks:

  • Assume that I want to transcode everything into a single format, even though the device supports multiple formats.
  • Handle tags incorrectly/not a all during transcoding
  • Require importing my music into a large, complicated media player

So I wrote my own script to do it. You specify your music directory and the device's music directory, as well as the file extensions that require transcoding and the format to transcode to. All your music is copied to the device, preserving the directory structure. Any files with the specified extensions are transcoded, keeping the same base name and changing the extension. All other files are copied with no modification. This includes all other files, not just other music files. So your album art and stuff gets transferred too. Transcoding happens in parallel if you have multiple cores avilable. Running the same script a second time will only update files that have changed in your music directory. The default transcoding options will transcode several lossless formats to ogg.

In order to know when a source file has been updated, this script saves the first 32 bytes sha256 hash of the source file in the transfercoder_src_checksum tag in each transcoded destination file. This means that simply changing the time stamps of files in your music directory will not cause them all the be transcoded again. If you don't want this, then use the --no-checksum-tags option, and it will avoid adding these tags and instead rely on the file time stamps, transcoding a file any time the source file is newer.


Transfercoder is now structured as a Python package, so you can install it using pip:

pip install

This should install Transfercoder and all the other Python packages that it depends on. After this, you should now have a command called transfercoder in your $PATH.


Once you have installed Transfercoder, you can use it like this:

transfercoder /home/yourname/Music /media/musicplayer/music

This command will copy your music from the first path to the second while transcoding lossless formats like FLAC in the source path to Ogg Vorbis files in the destination using ffmpeg.

See the help (transfercoder --help) for more options.


  • Python with the plac, mutagen, six, ffmpy, and tqdm modules installed. (These packages should get installed automatically if you use pip to install Transfercoder.) The script should work with both Python 2 and 3, but as of version 3.2 it is primarily tested on Python 3. (In recent versions, I've added type annotations, so it probably won't work on Python 2 unless you remove them.)
  • ffmpeg - For transcoding (Make sure ffmpeg is complied with support for encoding and/or decoding the formats you require)
  • Rsync (optional) - For faster copying of small changes

As indicated, rsync is an optional dependency. It is primarily useful if you changed only file tags on files that do not require transcoding, in which case there will only be a small difference to transfer.


  • You can only choose one target transcoding target format. I can't see a reason you would want more than one. You wouldn't want to transcode flac to ogg and then transcode wavpack to mp3.
  • No playlist support. Playlists can get complicated. They may have relative or absolute paths, and the device may expect them in odd formats. You'll need to come up with your own solution here, or just use a media player that handles them.
  • Transfercoder intentionally avoids copying replaygain tags when transcoding. This is because in my experience, different formats of the same song need different replaygain adjustments, even though in theory they should have identical volumes. Instead, just add replaygain tags to your transcoded library on your device after syncing. I have also written a tool for that called rganalysis.