1# Android File Transfer For Linux (FreeBSD and Mac OS X!) 2 3[![License](http://img.shields.io/:license-LGPLv2.1-blue.svg)](https://github.com/whoozle/android-file-transfer-linux/blob/master/LICENSE) 4[![Version](http://img.shields.io/:version-4.2-green.svg)](https://github.com/whoozle/android-file-transfer-linux) 5[![Build Status](https://travis-ci.org/whoozle/android-file-transfer-linux.svg?branch=master)](https://travis-ci.org/whoozle/android-file-transfer-linux) 6[![Android-File-Transfer-Linux](https://snapcraft.io//android-file-transfer-linux/badge.svg)](https://snapcraft.io/android-file-transfer-linux) 7 8Android File Transfer for Linux — reliable MTP client with minimalistic UI similar to [Android File Transfer for Mac](https://www.android.com/intl/en_us/filetransfer/). 9 10It just works™. 11 12## Do I need it? 13 14If you're happy with `gmtp`/`gvfs`/`mtpfs` or any other mtp software, you might not need this software (but give it a try!). 15 16If you're suffering from crashes, missing tags, album covers, usb freezes and corrupted files, this software is right for you. 17 18## Pre-built Packages 19 20If your distribution does not provide `android-file-transfer-linux` package, you can still install it in your system. 21There's quite a few packages available: 22- Snapcraft: https://snapcraft.io/android-file-transfer-linux 23- AppImage: https://github.com/whoozle/android-file-transfer-linux/releases 24- MacOSX DMG image: https://github.com/whoozle/android-file-transfer-linux/releases 25- MacOSX Homebrew: `brew cask install whoozle-android-file-transfer` or `brew cask install whoozle-android-file-transfer-nightly` 26 27## Support me 28If you want to help me with development, click on the link below and follow the instructions. I'm developing AFTL in my spare time and try to fix everything as fast as possible, sometimes adding features in realtime (more than 100 tickes closed by now). 29Any amount would help relieving pain of using MTP. :D 30 31https://www.paypal.me/whoozle 32 33## Features 34 35* Simple Qt UI with progress dialogs. 36* FUSE wrapper (If you'd prefer mounting your device), supporting partial read/writes, allowing instant access to your files. 37* No file size limits. 38* Automatically renames album cover to make it visible from media player. 39* Supports Zune/Zune HD. 40* USB 'Zerocopy' support found in recent Linux kernel (no user/kernel data copying) 41* No extra dependencies (e.g. `libptp`/`libmtp`). 42* Available as static/shared library. 43* Command line tool (aft-mtp-cli) 44 45## FAQ 46[Please take a look at FAQ if you have issues with your operating system](FAQ.md). It's not that big, but those are the questions asked very often. 47 48## Building instructions 49 50### Gentoo 51 52 AFT for Linux is now included in Gentoo, you don't have to build anything, just run 53 ``` 54 sudo emerge -av sys-fs/android-file-transfer-linux 55 ``` 56 57 If you need fuse mount helper to mount MTP filesystem, you have to enable fuse use flag, e.g. adding the following in /etc/portage/package.use (which can either be a directory or a file) 58 ``` 59 sys-fs/android-file-transfer-linux fuse 60 ``` 61 62 You can use ```sys-fs/android-file-transfer-linux-9999``` ebuild if you want the latest git-version by adding the following entry into /etc/portage/package.accept_keywords (which can either be a directory or a file) 63 ``` 64 =sys-fs/android-file-transfer-linux-9999 ** 65 ``` 66 67### Prerequisites 68 69* You will need Qt libraries for building ui program. If you're planning to use only library (*Qt is not needed*), you could turn the option ```BUILD_QT_UI``` off. 70* For ubuntu and other debian-based distros use the following command: 71 72 ```shell 73 sudo apt-get install build-essential cmake qt5-default ninja-build libfuse-dev libreadline-dev 74 ``` 75 76 For Fedora: 77 ``` 78 dnf install make automake gcc gcc-c++ kernel-devel cmake fuse fuse-devel qt-devel readline-devel 79 ``` 80 81* Basically, you need `libqtX-dev` for UI, `libfuse-dev` for FUSE interface, `cmake`, `ninja` or `make` for building the project. You could use libqt5-dev as well. 82 83### Building with ninja 84 85```shell 86mkdir build 87cd build 88cmake -G Ninja .. 89ninja 90 91./qt/android-file-transfer 92``` 93 94### Building with make 95 96```shell 97mkdir build 98cd build 99cmake .. 100make 101 102./qt/android-file-transfer 103``` 104 105### Installing binary package on OS X / macOS 106There is a binary package that can be installed via Homebrew: 107 * First [install brew](https://brew.sh) if you don't have it already installed. 108 * Then the stable package may be installed via: 109 110 ```shell 111brew install homebrew/cask/whoozle-android-file-transfer 112 ``` 113 * Nighlty build may be installed via; 114 115 ```shell 116brew install homebrew/cask-versions/whoozle-android-file-transfer-nightly 117 ``` 118 119 * Please note: they are in conflict, so please make sure to uninstall it when you want switch between stable and nightly. 120 121### Building app package on OS X / macOS 122 123You'll need Qt installed to build the GUI app. Here are the build instructions with qt5 from homebrew (`brew install qt5`): 124 125```shell 126mkdir build 127cd build 128cmake .. -DCMAKE_INSTALL_PREFIX=~/Applications -DCMAKE_PREFIX_PATH=/usr/local/opt/qt5 129make 130make install 131 132open ~/Applications/android-file-transfer.app 133``` 134 135### Installation 136 137`sudo ninja install` or `sudo make install` will install program into cmake prefix/bin directory (usually /usr/local/bin) 138 139 140## How to use 141 142### FUSE interface 143 144```shell 145mkdir ~/my-device 146./aft-mtp-mount ~/my-device 147``` 148Remember, if you want album art to be displayed, it must be named 'albumart.xxx' and placed *first* in the destination folder. Then copy other files. 149Also, note that fuse could be 7-8 times slower than ui/cli file transfer. 150 151### Qt user interface 152 1531. Start application, choose destination folder and click any button on toolbar. 154 1552. The options available there are: `Upload Album`, `Upload Directory` and `Upload Files`. 156 The latter two are self-explanatory. `Upload album` tries searching source directory for album cover and sets best available cover. 157 1583. You could drop any files or folders right into application window, the transfer will start automatically. 159 160### Known problems 161 162* Samsung removed android extensions from MTP, so fuse will be available readonly, sorry. Feel free to post your complaints to http://developer.samsung.com/forum/en 163* Sometimes downloading fails with usb timeout, then phone becomes unresponsive. [Android bug #75259](https://code.google.com/p/android/issues/detail?id=75259) 164* Objects created in UI will not show up in FUSE filesystem. [Android bug #169547](https://code.google.com/p/android/issues/detail?id=169547) 165 166Up to date list of all known problems and bugs available [here](https://github.com/whoozle/android-file-transfer-linux/issues) 167 168## Contacts 169Please do not hesitate to contact me if you have any further questions, my email address is <vladimir.menshakov@gmail.com>. 170 171## Special thanks 172* All who filed bugs on github and wrote emails, many features appeared only because of your feedback. Thanks! 173* Alexey [gazay](https://github.com/gazay) Gaziev for useful suggestions, support and invaluable help with MacBook and MacOSX port. 174* @ssnjrthegr8 for the new logo! 175 176## License 177 178Android File Transfer for Linux is released under [GNU LGPLv2.1 License](https://github.com/whoozle/android-file-transfer-linux/blob/master/LICENSE). 179 180Copyright © 2015-2020 Vladimir Menshakov 181