ftpmusync: FTP Music Synchronizer
4f793216 — Charles Daniels 5 years ago
0.0.3 release
5e89694e — Charles Daniels 5 years ago
0.0.2 release: fixed some crashes and entry point
ebce2937 — Charles Daniels 5 years ago
added roadmap



You can also use your local clone with git send-email.

#ftpmusync - FTP Music Synchronizer

ftpmusync is a music synchronization tool. It is specifically designed for synchronizing a local music folder to another device over FTP. This is useful because many smartphone-based media player applications have an "FTP server" feature for allowing easy access to their stored media library.

#Key Features

  • Only sync files which are missing or need updated (a file is considered to need an update if it's size on the local and remote differ, in which case the local file is always assumed to be more up to date).

  • Automatic detection of enrolled devices on a LAN network.

    • Note that this operates by scanning the entire LAN subnet - make sure whoever own's your network is ok with you doing this!
  • Sync to multiple devices.

  • Support for arbitrary prefixes on the remote side.

  • Unicode path handling via URL-encoding.


ftpmusync depends on the netifaces library.

ftpmusync can be installed via setup.py install.


usage: ftpmusync [-h] [--version] [--verbose] [--debug] [--port PORT]
                 [--ip IP] [--user USER] [--password PASSWORD]
                 [--prefix PREFIX] [--srcdir SRCDIR] [--allow_scan]
                 [--overwrite] [--token TOKEN]
                 (--scan | --scan_all | --enroll | --sync)

A tool for syncing music via FTP to applications such as Foobar2000 which have
the capability to host FTP based sync servers. Optionally, automatic discovery
of managed devices may be used.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verbose, -v         Display verbose output messages.
  --debug, -D           Display debug output messages. Implies -v.
  --port PORT, -p PORT  Specify the port FTP is expected to be running on.
                        (default: 21)
  --ip IP, -i IP        Specify an IP address to sync explicitly
  --user USER, -u USER  Specify FTP user. (default: anonymous)
  --password PASSWORD, -P PASSWORD
                        Specify FTP password. (default: anonymous)
  --prefix PREFIX, -e PREFIX
                        Specify prefix on FTP server. (default: ./)
  --srcdir SRCDIR, -d SRCDIR
                        Specify the source directory. (default: ~/Music)
  --allow_scan, -a      Enable features that require scanning the network.
                        WARNING: this feature or action may trigger commonly
                        used network monitor or intrusion-detection software.
                        Please do not use this feature on a network you do not
                        own without permission from the local systems
  --overwrite, -w       If asserted, any conflicting paths on the remote are
                        unconditionally overwritten. By default, only paths
                        where the file sizes differ are overwritten.
  --token TOKEN, -t TOKEN
                        Override the token, which is the system hostname by
                        default. This is used to check if a given target host
                        is managed by this instance of ftpmusync. You may want
                        to override this if you wish to sync to the same
                        device from several systems, or if your system
                        hostname changes frequently for some reason.
  --scan, -s            Output a list of IP addresses which are managed by
                        ftpmusync on the current LAN network. Requires
                        --allow_scan to be asserted.
  --scan_all, -S        Output a list of IP addresses which have open FTP
                        ports on the current LAN network. Requires
                        --allow_scan to be asserted.
  --enroll, -n          Enroll an host to be managed by this ftpmusync
                        instance. you must specify --ip to use this action.
  --sync, -y            Sync music files now. If --allow_scan is asserted and
                        no --ip is provided, all results that would be
                        returned by --scan are used as sync targets.

#Supported Platforms

ftpmusync should work on any host operating system and FTP server in principle, however it has thus far only been tested on the following configurations:

  • OpenBSD 6.4 local to iOS12+Foobar2000 remote

If you've given ftpmusync a try, let me know what systems were used, what worked, and what didn't.


  • More performant FTP wrapper

    • Currently, every FTP command is executed in a new FTP session, this can be very slow. The FTP wrapper should be modified to allow an existing session to be re-used if one is available.
  • GUI

    • A GUI frontend could be added relatively easily, as ftpmusync is already written as a library with a CLI front-end; a GUI could hook the same functions with minimal changes.
  • The net module could be updated to only import netifaces if scanning is requested, which would allow ftpmusync to work with only the Python standard library in cases where scanning is not required.

  • Other methods for determining if a remote file needs updated besides just size.

  • Ability to synchronize playlist files updated on the device back to the host.

  • Automated path-normalization for m3u playlist files.