Taken from misticriver.net: http://www.misticriver.net/showthread.php?t=50579

Originally posted by: _gmureddu_
Thanks for the hard work!

Background

The iriver Clix is a rather interesting media player. Unlike its predecesor, the U10, the Clix can't switch its way of communicating with the host comoputer. The U10, though being an MTP device pretty much everywhere but Asia, can be "transformed" into what is called an MSC (Mass Storage Class) USB device (also known as UMS, USB Mass Storage device). This means that the USB MassStorage device driver (on any compliant Operating System) is used to "mount" the device (or asign a volume letter in Windows). The Clix, on the other hand, uses a different USB protocol, the MTP (Media Transport Protocol). This protocol was developed by Microsoft corporation to be used in media devices, such personal media players or personal digital media players. Amongst the advantages of this protocol is the support for "metadata", which sort of simplifies the process of managing a media libray. However this protocol was for quite some time, local to Microsoft Windows. It was first released with version 10 of Windows Media Player as a user mode device driver.

The MTP protocol is actually a revision of another protocol: PTP (Picture Transfer Protocol), which is widely used in digital cameras and used in early (non-Apple) mp3 players. In Linux this protocol was the backbone for applications such as gphoto which allowed for synchronization of digital cameras (though some can also connect to the PC as MSC devices). For this to happen, libptp was devoped, and now the same thing has happened with the increased numbers of media devices, and now there's a way to communicate with these new devices in Linux (and other *nixes) too: libmtp.

libmtp provides both a protocol and command line tools to control and access MTP devices. As it is a library it can be utilized by other programs to sync with these devices, and actually there are two (mantained) applications which do just that: The amazing Amarok media player and gnomad2. As its name implies, gnomad2 was first deviced as a means to synchronize with portable media players from Creative (and Dell), the Nomad series, which used a proprietary protocol over the USB bus to sync with the computer. For use with these devices, it was first developed with the libnjb library and API (an implementation of the PDE, Portable Digital Entertainment, protocol), but grew to accomodate the newer MTP devices, through the use of libmtp. Gnomad2 was first developed by Linus Walleij, who also happens to be a developer and release manager for libmtp. As of Gnomad2-2.8.11 and Amarok-1.4.5, both programs now support libmtp-0.1.3 (the latest release) which means less need for the command-line interface (though this interface also lets you control a lot of aspects of your player).

Using libmtp

If you happen to be the happy owner of a Clix 2Gb with firmware 1.11, chances are you will be able to do sync your Clix to an extent using Amarok. The 1.11 firmware fully works with libmtp alpha releases (0.0.x), or should I say, libmtp alpha worked well with the 1.x firmware on the Clix. When the Clix got its 2.x firmware update, the alpha versions of libmtp stopped working with it, which is to say bad, as most Linux distributions pack one or another alpha version of libmtp either in the installation media or is readily available from the vast numbers of Internet repositories for the various Linux distributions. As per the second week of february 2007 an updated versio of libmtp, Amarok and Gnomad2 exists that should be available for all major distributions on their update repositories. These versions should be compatible and should allow you to sync your Clix with firmware 2.01.

Synchronizing with Amarok

The following instructions are valid for Amarok 1.4.x (including latest 1.4.5)

Syncing with Amarok is by far the easiest way to get your Clix working on Linux. To do so, you will have to manually configure your clix in Amarok (the following screenshots are taken in a Spanish localized Gnome desktop, appropriate translations and descriptions are provided bellow each pic):



Open the main Amarok configuration window from the menu Preferences -> Configure Amarok.

In the window that opens, choose Media Devices:



On the right panel you should see something like:



In this screenshot I have already configured the Clix, the name field should be empty.

Click the add new device button, and you should see a window like this:



Fill in the name field for the device, and leave the mount point field empty, as MTP devices don't mount as such. Now select MTP device from the drop down menu:



At this point you can press OK on both windows and try to connect to your Clix, to do so, first select the media devices tab on the left-hand navigation panel in Amarok:



This will display the media devices panel, which is empty as the device is not connected, yet:



Now simply hit connect and you should see the contents of your Clix:



Now, you can start transfering files... Well, sort of (see ahead). To do that, simply browse your library, select a track (or tracks) and right-click on it/them and select transfer to media device (or drag and drop):



This will cause the songs to be placed in a transfer queue in the media devices tab:



You can simply right click on the track/tracks to be synced or click the transfer button at the top panel to start the transference.

However, at this point, you'll most likely be greted with several error messages.The files cannot be transfered into your Clix (at least not yet). And you'll have to use the command line to do that. However, the necessary entries on the Clix' database for your tracks will be created. Even the directories, the only thing missing is the actual files. The way Amarok creates the entries is under the Music directory, but instead of creating the usual artist/album pair, it directly creates the album directories, and resorts to metadata for the artist information (though that info is correctly placed in the db).

As per Amarok 1.4.5 with libmtp-0.1.3 support, this is no longer true, and you should be able to sync your files just fine. However there is a "slight" problem with character encoding. Amarok uses by default ID3Tags version 2.4, this means that it uses LibTag as the backend for handling the Tags, but this also poses a problem for "older" ID3Tags v1 and 2.3, making the tags incompatibles with v1 and v2 (up to 2.3) compatible players (XMMS, Audacious, etc). The problem has got to do with character encoding. UNICODE character encoding in 2.3 tags (EasyTag uses 2.3) uses UTF-16, where as 2.4 uses UTF-8, even though Amarok is capable of understanding correctly these tags, the problems arise when you try to sync your files, as the tags will be missread, and some files will fial to sync (especially those files with non-standard characters, like accentuated characters, Asian language encoding, etc), so you will have to either update your tags or change them. Being a Spanish speaker, I stumbled onto this problem rather quickly. I don't know if by forcing the characters to be in ISO format has any better results than UNICODE.

Synchronizing with Gnomad2

Gnomad2 does not synchronize as such, but rather transfers files back and forth MTP/"NJB" devices and your computer. Its main interface is a two pane window with one side representing your computer (left side) and the other your device (right side):



Upon starting, the program will scan your computer for comaptible devices attached to it and then will retrive the information on it, this takes just a little while, then you can transfer files back and forth. Gnomad2 is optimized for mp3 and wma files, so it works very well with these types of files, however it lacks support for reading metadata on ogg files, even though you can transfer these just fine, and add them to playlists. Gnomad2 is pretty straight forward to use and it also allows you to manage your device once you have transfered all your files, so you can create playlists on the unit once you have uploaded your files with a simple right click on the playlists tab:



Not only can you create, but you can merge (mix, mezclar), playback, edit, export and delete them. Pretty much all (except maybe playback, I have not tested this) is avialable for the Clix.

There's also a tab for data, so you can transfer back and forth other files. It would be much more appreciated to have a shell extension like a GNOME-VFS2 plugin for MTP devices, but in the mean time such a plugin is implemented, Gnomad2 offers a way to transfer regular files to your DAP.

A rather neat feature of Gnomad2 is the ability to add files to a given playlist when you transfer the files. You can add the files to a single playlist of multiple playlists:



Gnomad2 is not perfect, though. It allows you a lot of things with your Clix, but it can crash at times. I had a strange crash upon transfering files from the Clix to my computer after it writing a file on my computer (the transfer finished) it crashed without any apparent reason. I belive it did so, because I was trying to transfer an Ogg file off the DAP (and since it can't read metadata off Oggs, it may have crashed due to that). Should you encounter any problems with Gnomad2 on your system, make sure to report a bug report , if you can provide a backtrace of the problem (try to reproduce it, launching the program from a command line interface, and see what is printed on the console, provide that so the developers can know what's going on, and hopefully correct it). As I previously daid, Gnomad2 does not support Ogg files all that well, as it is unable to read off their metadata, but if you happen to have some files already in your DAP transfered in Windows or with Amarok, you'll notice that those files' metatada is perfectly readable, and editable. Hopefully as more DAPs support OGG and FLAC, they'll add support for these as well.

Transfering files from the command line

These instructions are for v0.1.3, libmtp-0.1.3 on some distros like Fedora, in the libmpt-examples packages still has the standalone commands for compatibility reasons.

So to transfer the files all that's left to do is to open a command line emulator, gnome-terminal, Konsole, xterm or whatever you choose, and enter the necessary commands. Warning you may require to install a separate package depending on your distribution. For instance, in Fedora Core, the package libmpt-<version> only includes the library and not the commands, which are bundled in the libmpt-examples package. Consult your distribution's packages for the correct package.

The first step is to determine the directory to which you'll be transfering the files. To do that (in libmtp-0.0.2x and 0.1.x) use the mtp-folders command, before you actually issue such command, close any application/connection to the device, as it may be blocked, unplug it and replug it and then:

Code:
OK.
*libmtp-0.1.x is less prone to block the device than the previous alpha versions (0.0.x), howver it may still block and you have to unplug/replug it.

Notice that to the left of each directory, there's a numeric value. That's is very important, as it is going to be the argument for the transfer command to send the files to. You'll see a lot of "ptp2/ptp_usb_getdata: read 1 bytes too much, expect problems!" messages, don't worry. It is possilbe that in the next few steps the communication with the Clix may jam, and an error stating that you should reset your device may be printed on the screen. Do not panic!, just unplug and replug and it should work again.

Ok, so now that you know the code for the directory you want to transfer a file to, let us send the file... Let's say we ant to send the file Metallica - Enter Sandman.ogg, to the Metallica/Metallica folder, which number code is 1900544:

Code:
In the example above it would have also been possible to use the "higher level" reference to the directory you want to send the files to, instead of the numeric value. However, since there are two directories with the same name, the best way to get the files to the desired destination is to use the actual numerical reference. Here's one major difference between different versions of the libmtp commands. The alpha versions do support referencing the directories by their "natural" name (high level name, like "Stone Temple Pilots" instead of 1441792), the beta versions, however (libmtp-0.1.x) for some reason don't seem to bode well with that.

There is one major caveat, though. It is not possible to send several files at once using wildcards. For this reason, it is necessary to either issue each time the command for each of the files you want to get into your Clix (a pain in the butt) or (another pain in the rear) code a small shell script to automate the process... You can write a one liner shell script like the following to get all the files in the example above to the Clix:

Code:
This will get the job done, however should any of the files fail to transfer, will jam the communication between the PC and the Clix, requiring you to unplug and replug it and then manually transfer the files which were beyond the one that failed. You can expect to see some problems in character encoding. Even when the Clix uses UTF-8 character encoding, avoid using special characters in your files such as accentuated vowels and other characters (?!°~`^ etc). I still have to confirm if the new libmtp supports "batch transfers" using wildcards from the command line.

Viewing the files on the Clix

You can see all the files present on the Clix. The easiest way is to do that with any of the applications which support querying MTP devices such as gnomad2 or Amarok, but if you want to do it the "geek" way, you can use the mtp-files command. This command will output all the files present on the Clix, which depending on your configuration, may overflow the terminal's buffer rendering you unable to see all the files (you may redirect the output to either a file or to the "less" command, but showing how to do that is beyond the scope of this "tutorial").

Just as it happens with the directories, each and every file has a unique ID on the Clix' filesystem, for instance:

Code:
Deleting files

To delete any one file from the command line, it is important to know the file ID, even though it is apparently possible to remove files using their name rather than their ID. In any case, by now you may have guessed it, to remove the files you require the command mtp-delete, well not quite, the command is called mtp-delfile, which does exactly that:

Code:
Creating directories on your Clix

You can create new directories on your Clix from the command line, by using the command mtp-newfolder. The way this command works is very similar to the way the command mtp-sendfile works. Basically the summary of the command is as follows:

Code:
Basically what this means is that you have to provide the name of the new direcotry and the parent directory's id (so the Clix "know" where to create the new directory), hence let us see at an example:

Code:
OK.
This creates the directory My Folder under the Music directory. We can confirm that the directory was created by issuing the mtp-folders command:

Code:
OK.
As you can see, the directory was successfully created and it is perfectly visible in the Device Browser on the Clix.

libmtp-0.0.2x and libmtp-0.1.x

The main difference (at user level) between the two versions is that instead of having a bunch of commands to perform a series of operations (sendfile, delete, newfolder, sendtrack, getfile) they all are part of a single command which depending on the options passed to it and the arguments will perform these operations, and most importantly, the support for sending files onto 2.0x firmware Clixes.

Now that applications have started supporting libmtp, and as the protocol, the library and applications get better, there will be no reason to not be able to use any MTP device on Linux, Mac or any other POSIX platform, hopefully on any hardware platform.

It would be wishful thinking when libmtp will be an integral part of *nix based systems (MacOS/Linux/BSDs) as to even have virtual filesystems modules for it (for instance a Gnome virtual filesystem module for VFS2 to browse MTP devices with mtp:// in Nautilus or Konqueror or even Finder). I still hunger for such a feature...

I hope the contents of this post/thread are useful to some users here on MisticRiver and other places, and I'm confident that support for the protocol will only get better and better as the USB-IF reviews and formulates a standard for the protocol just like they did for the MSC devices, so that all the required documentation is made available for implementation on as many platforms as MSC is currently supported.

I posted this on a separate thread so it would get more exposure. So basically one of the devs is getting a Clix and that should enable the team to better indentify problems with the Clix and libmtp.