From Winamp iPod plugin ml_iPod
Revision as of 19:37, 5 April 2010 by Abu (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



What is ml_iPod?

The Winamp iPod Plugin (aka ml_ipod) is a plugin for the wonderful Winamp media player. It allows you to manage your iPod from within the Winamp media library. ml_iPod always strives to keep compatible with the latest versions of Winamp. Very old versions of Winamp may not work with ml_iPod.

Winamp comes with iPod support, how does that relate?

Starting with Winamp 5.2, the Winamp distribution contains a different iPod handling system, it is part of the generic portable music player support (pmp).

ml_iPod is much older and at the moment has more features than the pmp_* plugins. Don't confuse these two modules. If you want to use ml_iPod (which this site is dedicated to), you must not install the iPod support that comes bundled with Winamp. If you have done so already, you will get the opportunity to uninstall it during the ml_iPod installation.

For a comparison between the two plugins, see ml_iPod versus pmp_iPod

What devices are supported?


It supports all older kinds of iPods, from the old first generation iPods, to the iPod mini, photo, video, nano, classic and shuffle and everything in between. The Classic 80GB/160GB and 3g Nano iPods have support by ml_iPod since ver 3.02. 4g nanos since 3.06.

iPhones and iPod Touch is supported now in a limited way. Updates on this found on the iPhone page and in the forum thread

CAUTION1: iPhone 3G and iPod touch with FW 2.0 has problems, see the iPhone page. FW 3.x does not work with ml_iPod. We gave up on this issue.

CAUTION2: nano 5G (with the camera) is NOT supported

In addition, the Motorola smart phones SLVR and ROKR are supported since v1.42 SLVR.png

Do I have to jailbreak my iPhone or iTouch?

No, if you run firmware 1.x on the device. But if you have a jailbroken one, you can use the AfterSync app, see IPhone For the workaround on FW 2.x, the device needs to be jailbroken, see IPhone.

What is the latest version of ml_iPod?

You can see (and download) the latest official version on the Sourceforge download page. As of Apr 2010, it is 3.09

If you want to have the newest features and fixes, you can download Achim's latest development build

Do I have to have iTunes installed for this to work?

The winamp ipod plugin works with or without iTunes installed for regular iPods. It makes no difference. For iTouch and iPhone iTunes must be installed.

But you should make sure that iTunes and WinAmp are never running at the same time when your iPod is attached. Two applications that both want to access the iPod database could (and will) lead to trouble.

If I used to use iTunes, what will happen to my Ratings/Playcounts? Will they be lost in the switchover to ml_iPod?

You can preserve playcounts and ratings with the ml_impex (Import/Export) plugin for Winamp. This plugin allows the user to Import the iTunes database (including the ratings and playcounts) into the Winamp Library and vice versa. Using this plugin will prevent the loss of ratings/playcounts when you switch from iTunes to ml_ipod.

Can I use iTunes and ml_iPod in turn for one iPod ?

Yes, with limitations: As far as music is concerned, all should work well. But the podcast handling is incompatible, you must manage your podcasts with ml_iPod. Some people have reported iTunes to remove the album art that has been put on the iPod with ml_iPod, but that should not happen since v2.01.

iTunes and WinAmp must never run at the same time when your iPod is attached.

Can ml_ipod transfer to iPod in background so I could continue to enqueue transfers like in iTunes?

No, We won't do it because it would require too much work. A good deal of code would have to be rewritten to implement this, as the current code can't accomodate it. If you want that feature, switch to pmp_ipod.

How can I update/add Album art to songs already on my iPod if I DO NOT have the original songs on my Harddisk?

Album Art transfer without Original Harddisk Music

Does the ipod plugin work with ipod video?

Yes, starting with v1.40 video files (*.mp4) are handled correctly. Make sure that you meet all the prerequisites as mentioned on Copying Videos to iPod (e.g. the MP4 audio plugin must be installed in Winamp for this feature to work etc.).

Does this work with Windows 98 or Windows Me?

The iPod support plug-in has been tested on and works with Windows 98, Windows Me, Windows 2000, Windows XP, and Windows Vista. iTunes, however, requires Windows 2000 or higher, so if you need to use iTunes to upgrade your iPod's firmware, you will need to use either a Mac or Windows 2000, Windows XP, or Windows Vista.

The iPhone/iTouch support relies on an iTunes installation, so it does not work on Win98 or ME.

If you are running Windows 98, then this page might help you.

How can I find out which version I'm using?

Preferences dialog (click to enlarge)

Go to the Winamp preferences, into the Plugins->MediaLibrary section.

There you see an entry "Winamp iPod support vXXX". This is the actual ml_ipod version that is installed on your computer. In the example on the right it is 1.42a07.

My iPod does not support XYZ, can you build that into ml_iPod?

Usually the answer is NO, because ml_iPod can not control the iPod's behaviour. See the article on IPod firmware

What are "hidden settings?"

There are some special settings that can not be controlled in the GUI. They are for very special cases or debugging purposes. For more information, see Hidden Settings.


My iPod doesn't show up in Winamp!

Ml tree1.png

Have you have connected your iPod to the computer, but can't see its contents in Winamp? Follow this guide:

1) Are you using a version of Winamp 5 that has the Media Library?
Yes: Go to (2)
No or not sure: Get the full or pro version of Winamp at winamp.com.

2) Do you have the latest version of the Winamp iPod plug-in?
Yes: Go to (3)
No or not sure: Get the latest official release from Sourceforge or the even newer current development build.

3) Does the iPod show up as a drive letter in Windows Explorer?
Yes: Go to (5).
No: Go to (4).

4) Has Windows detected the iPod and installed drivers for it?
To check that, look in your system tray (right-hand side of the taskbar, next to the system time) and look for either a green arrow or a USB plug with a checkmark in a green circle. If you hover the mouse over it, a tooltip will come up that says Safely remove hardware. Double-click that. A window should open; check Display device components at the bottom. If somewhere under Hardware devices it says "Apple iPod USB Device" you're set. Otherwise, contact Apple Support.

Under "Apple iPod USB Device" it should also say "Generic Volume" and usually a letter in parenthesis; this is the drive letter that Windows has assigned your iPod. If there is no such letter, you need to assign a drive letter manually. To do that in Win XP choose Start->Run, type "diskmgmt.msc". Find your iPod in the window that opens now, right click on it and select "Change Drive Letter and path...", assign an unused letter. Now the iPod should show up in Windows Explorer as a drive. If all that didn't work, you need help from a professional (maybe something is broken with your Windows setup, or your USB card, or whatever)

5) Do you see anything under "Devices" in the media library?
Yes: Go to (6).
No: Double-click "Devices". See in the image on the right where the iPod is supposed to show up. If it still doesn't show, go to (6).
No Devices entry at all in media library? Go to (6).

Note: ml_iPod does not show the iPod in the "Portables" section, which is new with Winamp 5.2 and is reserved for the pmp_* plugins!

6) Has the iPod been used before and has some songs on it?
Yes - Go to (7)
No - Try using the "Format" option in the ml_iPod preferences to get it to show up:
Open up Winamp preferences, under "General Prefrences" click "iPod Support". Under the "General" tab, in the middle is "Format iPod". Hopefully you dont have any music on it because this will completely erase your ipod and return it to "out-of-box" condition but with Winamp iPod support settings instead of iTunes settings. From the drop-down box, select the drive letter of your iPod and then click "Format iPod". Bam! When it's done, open Media Library (alt-L) and "Devices" should be listed along with "iPod".

If that doesn't work, you have to "Restore" the iPod in iTunes (sorry, Apple provides no other way for this). After that, you may need to try to format the iPod again.

7) Is it an iPod shuffle that has been used with iTunes?
Yes - In iTunes set the "Enable Disk Use" option to on.
No - Go to (8)

8) Does the iPod work with iTunes?
Yes - Use iTunes to put at least one song on the iPod, then it should work.
No - Contact apple technical support, saying that it doesn't work with iTunes.

9) But I don't want to install iTunes
Very understandable. Again: Try the "Format" option in the preferences. If this doesn't work, find a PC (no Mac!) with iTunes installed. Unfortunately, Apple does not give us any other chance.

iPod classic, touch, iPhone or nano 3G/4G: The iPod says "0 songs"

The new iPod devices (classic and nano 3G/4G) need a specially formatted database. This was not implemented in ml_iPod 3.01. Version 3.02 handles it fine. So, inside the iPod view in Winamp, everything looks fine, and you can upload songs without any problems. But after you ejected your iPod, the iPod refuses to recognize the songs. If you attach it to iTunes now, iTunes tells you that you have to restore it because of a damaged database. This is not true!. Simply use the newest ml_ipod, and it should be fine.

If you still have this problem: Disconnect your iPod. Start Winamp. Now press Control and Space keys and hold them both down while you attach your iPod, until the dialog to select the iPod type comes up. In this dialog, select the correct(!) type and click 'ok'.

If that doesn't work there is a little trick with the registry and the ml_iPod.ini. The articles are Hidden_settings and Fwid.

Album Art does not work

That's often an issue with new generation iPods. Always make sure you have the latest ml_iPod version. If you have an iPod classic or nano 3G, you must use ml_iPod 3.02 or newer.

If the album art does not show up on your iPod or is messed up, more often than not ml_ipod did not guess the correct iPod type, so you've got to help.

  • Disconnect your iPod
  • Start Winamp
  • Now press Control and Space keys and hold them both down while you attach your iPod, until the dialog to select the iPod type comes up
  • In this dialog, select the correct(!) type and click 'ok'.
  • After your iPod shows in Winamp, hit the eject button
  • Wait for complete eject (The iPod says "ok to disconnect")
  • Disconnect iPod
  • Reconnect iPod
  • After iPod shows in Winamp, use the "Refresh all album art" feature in iPod tools.

Vista users: It has been reported that this Ctrl-Space hotkey does not work on Vista. Don't know why, and I have no Vista machine to test with. If that happens to you, simply remove the line starting with "modelNumStr=" in your device ini file (see below) while Winamp is not running. Save the file. Start Winamp. Now the dialog should definitely come up.

If that still does not work on Vista and you don't see the dialog, you have to edit the right device identifier into that file (I hope that is not necessary). For an iPod classic the line must be "modelNumStr=MXX01", for a nano 3g "modelNumStr=MXX02", for a nano 4g "modelNumStr=MXX06".

My iPod Shuffle does not play any song, it just flashes the LED

Symptoms: It shows your ipod nicely in winamp and you can transfer songs from the PC to the ipod with Winamp, but when you disconnect the Shuffle and remove it from PC it "says" there are no songs on it (yellow - green - yellow - green led flashing) ....

That means that ml_ipod did not recognize it correctly as a Shuffle and did not write the additional files that are needed by the Shuffle. Might be caused by an incorrect "format" in ml_iPod v1.40..v1.42 (fixed with 1.42p14).

Cure: Please look into X:\iPod_Control\Device (X: being your Shuffle). Is there a file called SysInfo? If yes, rename it to SysInfo.orig, then run Winamp and upload a song to the Shuffle. Eject it. Everything should be ok now.

'This device does not support playlists' when creating a playlist

Symptoms: You can not create any playlist although you have an iPod that supports playlists. Right-clicking the ipod and choosing 'new playlist' or 'new smart playlist' spits out this device does not support playlists

This is the inverse of the above problem, this time a regular iPod is detected as a Shuffle.

Cure: Please create an empty file X:\iPod_Control\Device\SysInfo (X: being your iPod). Then restart Winamp. Everything should be ok now.

My iPod Shuffle skips some of the songs

Symptoms: If you transfer a bunch of songs they all seem to go. If you look at the files on the ipod, they all seem there. If you look under Devices it shows all songs and you can play them. If you transfer 20 songs, you might be able to play only 15 on the Shuffle. It is always the same 15. You can delete everything and transfer the missing 5 and they will play so it doesn't seem to be a song issue.

Cure: It has been reported that this helps:

  1. From WinAmp format the Shuffle
  2. immediately close WinAmp and unplug and plug back in shuffle
  3. iTunes will open, give it a name and go to the settings
  4. check enable disk use and uncheck open iTunes
  5. unplug again (just for checking) and close iTunes
  6. plug in, open WinAmp and transfer songs

Transcoding does not work

Up to v2.01, the transcoding feature was broken. That's because it used the external "transcoder", which itself was broken for many file formats. Starting with v2.01, transcoding is fully functional again! (not for iTouch/iPhone)

Some special characters are not processed correctly

ml_ipod is not designed to work with Unicode strings. But Winamp changed part of its API to use Unicode with 5.23. So there are some conversions necessary. That may lead to problems if you have special characters like ä, ö, ƒü, ƒß etc. in your track titles or playlist names.

As a workaround, simply dont't use these characters ;-) Stick with plain ASCII, and all will be well. If that is a serious issue, try using pmp_ipod, see ml_iPod versus pmp_iPod.

Submission to last.fm is unreliable?

Winamp 5.5 broke some things in the audioscrobbler plugin. Please the one that comes with ml_iPod 3.02 or newer.

Why is only one play submitted to last.fm for a track even though I've played it more than once since I last connected my iPod?

This isn't a bug, but rather a limitation of the iPod firmware. The iPod only records the time of the most recent play in its database. last.fm submissions must include a timestamp, and because ml_iPod only has access to the time of the most recent play, it can only submit one instance of the song, regardless of how many times it's actually been played since the last submission.

I can't log into SourceForge...I use the same account information from this Wiki but it won't accept it

ml_ipod Wiki accounts are SEPARATE from SourceForge accounts. You will need to create two accounts to be able to log into both SourceForge and ml_ipod Wiki. You need the SourceForge account to enter bug reports or feature requests. Create a new SF login here.

Dealing with bugs

Winamp crashed when I did XYZ with the iPod plugin, what should I do?

First you must make sure that the problem is actually caused by ml_iPod. Sometimes other plugins cause Winamp to die, but it shows up as a general protection fault in ml_ipod. To be sure, you have to do a clean install of Winamp and ml_iPod, then reproduce the error.

If it is still there, search in the forum if somebody else has had the same problem already. Then, browse the known bugs.

If you could not find anything and are absolutely sure that it is caused by ml_ipod, read the next section and then post a new bug report.

What is necessary for a bug report?

Bugs should be reported via the bug tracker.

It should contain all the necessary information:

  • ml_ipod version (see above in the "Basics" section how to find out, don't say "the latest")
  • Winamp version (give the exact version number)
  • iPod type (5gen, Nano, Shuffle...) and size of iPod
  • Always attach an archive with the specific files for your iPod. The easiest way to do this is right-click on the iPod icon in Winamp, then choose "Help...->Create archive for bug report"
  • If that can't be done (maybe Winamp does not even show your iPod), zip all the debuglog*.txt and *.ini files from your ...\winamp\plugins\ml_ipod folder on your harddisk and attach them. If the problem is related to the transfer of songs, enable transfer logging in the preferences and attach the \Program Files\Winamp\iPod Transfer Log.txt. If possible, send the device files, too (see next FAQ entry)
  • Include an eMail address where we can contact you, or log in with your SourceForge ID.

The requested archive file may be quite big, usually too big to attach it at SourceForge. In this case, please upload it to a webserver (your own webspace, or you can upload it to stashbox.org (preferred site!), mytempdir.com, sendspace.com or another free hosting service) and add the URL to the bug report.

What are the "device files"?


The term "device files" is used for the database files that are located on your iPod device. You can find them in Windows Explorer. If your iPod is shown as drive X:, navigate to X:\ipod_control\itunes

This folder is usually hidden in Windows Explorer, you may have to enable "Show hidden files and folders" in Explorer (Folder options->View->Advanced settings)

The important files that are needed for tracking down bugs are

  • X:\ipod_control\itunes\iTunesDB
  • X:\ipod_control\itunes\ml_ipod.ini
  • X:\ipod_control\itunes\mlipodSmartPlaylists
  • X:\ipod_control\itunes\OTGPlaylistInfo* (if present)
  • X:\ipod_control\itunes\Play Counts (if present)

If you have to send the device files for debugging, please stuff all these files into a zip archive. Caution, if you have thousands of songs on your iPod, the iTunesDB may be quite big, usually too big to attach it in the forum or at SourceForge. In this case, please upload it to a webserver (your own webspace, or you can upload it to stashbox.org (preferred site!), mytempdir.com, sendspace.com or another free hosting service)

What are "main debuglog" and "device debuglog" ?

ml_ipod records some debug information while it runs, that might be helpful to find bugs. They are created in the ...\winamp\plugins\ml_ipod folder on your harddisk. The file debuglog.txt is called the main debuglog, it contains information that is not related to a specific read or write operation on the iPod.

There is another file, that has the driveletter of your iPod in its name. E.g. if your iPod is shown as F: in Windows, the filename will be debuglog_F.txt. This file is called the device debuglog. Both are important for the developers.

If they are too big to attach in the forum, you can put them on a free webspace as explained above for the device files.

What is the "iTunesDB" ?

The "iTunesDB" is a file on your iPod that acts as the main database for the iPod. It contains the names of all your songs, albums, videos..., as well as your playlists. In short, everything that he iPod needs to know to build up its menus and to play music is stored in this file. If you run iTunes, this file is written by iTunes when you eject your iPod. If you run Winamp/ml_iPod, it is written by ml_iPod.

For debugging, it might be necessary to send your iTunesDB to the development team. Please zip it, it can be quite large! You can find it at the following path (X: being the drive letter of your iPod):

  • X:\ipod_control\iTunes\iTunesDB

What are the ini-files where ml_iPod stores its configuration ?

There are two ini-files:

  • The iPod specific stuff is stored in X:\ipod_control\iTunes\ml_ipod.ini (X: being the drive letter of your iPod) We call this the device ini file
  • The global settings are stored in the general winamp.ini. It is usually found under C:\Program files\Winamp\winamp.ini. If you have enabled "seperate settings for each user" during the Winamp setup, it can be found under C:\Documents and Settings\loginname\Application Data\Winamp\Winamp.ini. We call this the global ini file or Winamp ini file

More on this see Hidden settings

What is the "SysInfo file" ?


The "SysInfo" as well is a file on your iPod. It contains information for identifying your specific iPod model. For debugging, it might be necessary to send your SysInfo to the development team. You can find it at the following path (X: being the drive letter of your iPod):

  • X:\ipod_control\Device\SysInfo
Personal tools
Translations of the Wiki