The Media Transfer Protocol (MTP) is a protocol developed by Microsoft to allow for the control of MP3 players and other portable media devices across a USB port. The libmtp project provides an open source C library that implements the basic MTP operations. The Ruby LibMTP project provides a set of wrappers around the C library to allow these operations to be performed from a ruby script.

The Ruby LibMTP project files are licensed under the GNU Lesser General Public License.

For more information, please visit the following sites:

Wikipedia: Media Transfer Protocol

Libmtp C Library Homepage

SourceForge Libmtp C Library

The RubyForge LibMTP Project Page

Many thanks go to the developers of the libmtp C library for doing all the hard work. Without them, I would still be listening to the songs that came with my MP3 player. It scares me even to think about it.

Getting Started

At the moment, we do not have a Ruby Gem for LibMTP, so you are stuck with a TAR file that contains the C source code for the wrapper. To build and install the library, download the latest release and untar it. On a Linux system, it might go something like this.

tar --gunzip -xf libmtp-0.0.3.tar.gz

This will create a directory with the source files and documentation. Go into this directory, and type the following:

ruby setup.rb

You will probably need to be root because this command will install the library into the ruby directory. Of course, the libmtp C library will need to be installed on the system in a directory where the extconf.rb can find it. Otherwise, none of this will work too well.

I have not tried this under Windows or on a Mac as I do not have easy access to either of these systems. If someone would like to get this stuff working on these systems, your help would be greatly appreciated.


All of the actual operations on an MTP device are performed using a LibMTP::Device object. This object is created by calling the LibMTP::connect function. Currently the C library only supports a connection to a single device which will be the first MTP device that it finds. Once a Device object is created, you can use it to operate on the MTP device as shown in the following example.

require 'device/LibMTP'

LibMTP::connect do |device|

  # Display a list of supported file types for this device.

  array = device.supported_filetypes()

  array.sort.each do |type|

    puts "Type: #{type}, "

    puts "Description: #{LibMTP::filetype_desc(type)}\n\n"


  # Get a list of tracks for this device.

  array = device.track_list()

  if(array.length > 0)

    # Retrieve the file for the first track in the array.

    # Store the file as test.mp3 in the current directory.

    device.track_get_file(array[0]['track_id'], "test.mp3")



When the code block passed to the connect method ends, the Device object will be destroyed and the connection to the MTP device will be terminated.

For more information, see the Project Documentation.


On a Linux system, you may need to be root in order to access the device. If the device is connected to the USB hub but you cannot get a connection, try typing lsusb and see if the device shows up. If it does not show up, you may have problems with the USB drivers. Until the device shows up when you type lsusb, the libmtp library will be unable to talk to it.

With SUSE Linux 10.1, I currently have a problem getting the device to show up on a USB port. If I type the lsmod command, I get something like the following for the usbcore driver:

usbcore 109700 3 ehci_hcd,uhci_hcd

For some reason, the ehci_hcd interferes with the device being recognized. On my system, nothing is using this driver, so I simply remove it by typing:

modprobe -r ehci_hcd

Once this driver is unloaded, I reconnect the device to the USB port and it shows up. If anyone knows what the cause of this is or how to fix it, please send me an email.

As it stands right now, the code has not been tested much. I am still working on writing the unit tests for this library. Hopefully, I can get that done soon.

Valid HTML 4.01 Strict Created By Xemacs Graphics By Gimp