Libmtp

Building and Installing

See the "INSTALL" file.

Initiator and Responder

libmtp implements an MTP initiator, which means it initiate MTP sessions with devices. The devices responding are known as MTP responders. libmtp runs on something with a USB host controller interface, using libusb to access the host controller.

If you're more interested in the MTP responders, gadgets like MP3 players, mobile phones etc, look into:

• MeeGo:s Buteo Sync: https://github.com/nemomobile/buteo-mtp https://wiki.merproject.org/wiki/Buteo/MTP
• Android has an MTP responder implementation: https://android.googlesource.com/platform/frameworks/base/+/master/media/jni/
• Ubuntu/Ricardo Salveti has mtp-server and libmtp-server going: https://code.launchpad.net/~phablet-team/mtp/trunk https://bazaar.launchpad.net/~phablet-team/mtp/trunk/files

Heritage

libmtp is based on several ancestors:

• libptp2 by Mariusz Woloszyn was the starting point used by Richard A. Low for the initial starter port. You can find it at https://libptp.sourceforge.net/

• libgphoto2 by Mariusz Woloszyn and Marcus Meissner was used at a later stage since it was (is) more actively maintained. libmtp tracks the PTP implementation in libgphoto2 and considers it an upstream project. We will try to submit anything generally useful back to libgphoto2 and not make double efforts. In practice this means we use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2 source code. If you need to change things in these files, make sure it is so general that libgphoto2 will want to merge it to their codebase too. You find libgphoto2 as part of gPhoto: https://gphoto.sourceforge.net/

• libnjb was a project that Richard and Linus were working on before libmtp. When Linus took Richards initial port and made an generic C API he re-used the philosophy and much code from libnjb. Many of the sample programs are for example taken quite literally from libnjb. You find it here: https://libnjb.sourceforge.net/

Contacting and Contributing

See the project page at https://libmtp.sourceforge.net/ We always need your help. There is a mailinglist and a bug report system there.

You can also file github issues at https://github.com/libmtp/libmtp

People who want to discuss MTP devices in fora seem to hang out on the forums at AnythingbutiPod: https://www.anythingbutipod.com/forum/

Compiling programs for libmtp

libmtp has support for the pkg-config script by adding a libmtp.pc entry in $(prefix)/lib/pkgconfig. To compile a libmtp program, "just" write:

gcc -o foo pkg-config --cflags --libs libmtp foo.c

This also simplifies compilation using autoconf and pkg-config: just write e.g.

PKG_CHECK_MODULES(MTP, libmtp) AC_SUBST(MTP_CFLAGS) AC_SUBST(MTP_LIBS)

To have libmtp LIBS and CFLAGS defined. Needless to say, this will only work if you have pkgconfig installed on your system, but most people have nowadays.

If your library is installed in e.g. /usr/local you may have to tell this to pkgconfig by setting the PKG_CONFIG_PATH thus:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

Documentation

Read the API documentation that can be generated with doxygen. It will be output in doc/html if you have Doxygen properly installed. (It will not be created unless you have Doxygen!)

For information about the Media Transfer Protocol, see: https://en.wikipedia.org/wiki/Media_Transfer_Protocol

The official 1.0 specification for MTP was released by the USB Implementers Forum in may, 2008. Prior to this, only a proprietary Microsoft version was available, and quite a few devices out there still use some aspects of the Microsoft version, which deviates from the specified standard. You can find the official specification here: https://www.usb.org/developers/devclass_docs/MTP_1.0.zip

The Examples

In the subdirectory "examples" you find a number of command-line tools, illustrating the use of libmtp in very simple terms.

Please do not complain about the usability or documentation of these examples, they look like they do for two reasons:

1. They are examples, not tools. If they were intended for day-to-day usage by commandline freaks, I would have called them "tools" not "examples".

2. The MTP usage paradigm is that a daemon should hook the device upon connection, and that it should be released by unplugging. GUI tools utilizing HAL (hald) and D-Bus do this much better than any commandline program ever can. (See below on bugs.) Specificationwise this is a bug, however it is present in many, many devices.

That said, if you want to pick up and maintain the examples, please volunteer.

FAQ: Common Problems

Some MTP devices have strange pecularities. We try to work around these whenever we can, sometimes we cannot work around it or we cannot test your solution.

• Android locked screen: some devices just report zero files and no storages when the device screen is locked, it looks like so:

  mtp-detect Device 0 (VID=04e8 and PID=6860) is a Samsung Galaxy models (MTP). Attempting to connect device(s) Error 1: Get Storage information failed. Device: SHV-E210K LIBMTP_Get_Storage(): No data available OK.

  This is probably so as not to allow the MTP access to be used as a "backdoor" into the device. Unlock the device before listing files, set the autolock to some large value or disabled if it disturbs you, you are causing this to yourself, or should we say that your vendor is prioritizing security and privacy over ease-of-use. (You may talk to your vendor about this.)

• mtp-* tools doesn't work because someone else is already hogging the device

  This is a common problem, the most common case could be that gphoto2 (which can also talk PTP/MTP) is taking over the device as soon as it's plugged in. Some distributions are configured that way. Counter it like this:

  gvfs-mount -s gphoto2

  Then re-attach the device.

  Sometimes some gvfs daemons are running on the system and hogging the device, try stopping them with something like these commands:

  killall gvfs-mtp-volume-monitor killall gvfs-gphoto2-volume-monitor

  Then plug in the device and issue "mtp-detect" to figure out if this may be the case.

• Generic MTP/PTP disconnect misbehaviour: we have noticed that Windows Media Player apparently never close the session to an MTP device. There is a daemon in Windows that "hooks" the device by opening a PTP session to any MTP device, whenever it is plugged in. This daemon proxies any subsequent transactions to/from the device and will never close the session, thus Windows simply does not close sessions at all.

  For example this means that a device may work the first time you run some command-line example like "mtp-detect" while subsequent runs fail.

  Typical sign of this illness: broken pipes on closing sessions, on the main transfer pipes(s) or the interrupt pipe:

  Closing session usb_clear_halt() on INTERRUPT endpoint: Broken pipe OK.

  This means that device manufacturers doesn't notice any problems with devices that do not correctly handle closing PTP/MTP sessions, since Windows never do it. The proper way of closing a session in Windows is to unplug the device, simply put.

  Since libmtp actually tries to close sessions, some devices may fail since the close session functionality has never been properly tested, and "it works with Windows" is sort of the testing criteria at some companies.

  You can get Windows-like behaviour on Linux by running a udev-aware libmtp GUI client like Rhythmbox or Gnomad2, which will "hook" the device when you plug it in, and "release" it if you unplug it, and you start/end you transfer sessions by plugging/unplugging the USB cable.

  The "Unix way" of running small programs that open the device, do something, then close the device, isn't really working with such devices and you cannot expect to have command line tools like the mtp examples work with them. You could implement new example programs that just call to a mediating daemon like the Windows MTP stack does. (And change all programs using libmtp directly today.)

  If this bug in your device annoys you, contact your device manufacturer and ask them to test their product with some libmtp program.

• Samsung Android 2.3.x devices: these have a special MTP stack with some specific bugs that we have maybe nailed down now. It suffers from an "immediate connect" syndrome, i.e. you have to connect to the device within 7 seconds of plugging in, or it will go numb. This also goes for command-line activity with the example programs, so this device is better used with a GUI tool like Rhythmbox, gnomad2...

• Generic USB misbehaviour: some devices behave badly under MTP and USB mass storage alike, even down to the lowest layers of USB. You can always discuss such issues at the linux-usb mailing list if you're using Linux: https://www.linux-usb.org/mailing.html

  If you have a problem specific to USB mass storage mode, there is a list of strange behaving devices in the Linux kernel: https://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h You can discuss this too on the mentioned list, for understanding the quirks, see: https://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt

• Generic certificate misbehaviour. All devices are actually required to support a device certificate to be able to encrypt Windows Media (WMA/WMV) files. However there are obviously a lot of devices out there which doesn't support this at all but instead crash. Typical printout:

  Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed to get unicode property.

  This should only affect "mtp-detect", there is no other appl