ml_iPod Documentation: Table of Contents
  1. Introduction
    1. Requirements
  2. Installing ml_iPod
  3. Opening ml_iPod
  4. Configuring ml_iPod
    1. General
    2. Transfer Settings
    3. Volume
    4. Speech
    5. Transcoding
    6. Hotkeys via the Nullsoft Global Hotkey's plugin
  5. iPod Tools
    1. Rename iPod
    2. Normalize volume (mp3gain) for all songs
    3. Remove songs not in ML
    4. Copy to hard drive all songs not in ML
    5. Sync all ML smart views to smart playlists
    6. Full database cleanup (part 1-3)
    7. Cleanup part 1: Remove orphaned database entries
    8. Cleanup part 2: Database contents check
    9. Cleanup part 3: Probe for lost songs
    10. Fix corrupt timestamps in ML
  6. Copying songs/videos to iPod
    1. from the Media Library
    2. from Playlist Editor
    3. from Windows Explorer
    4. Transcoding incompatible songs
    5. Transferring encrypted iTunes Music Store songs
  7. Copying songs to hard drive
  8. Managing songs on iPod
    1. Searching iPod
    2. Editing song(s) info
    3. Rating songs
    4. Deleting song(s) off the iPod
    5. Sorting Media Library columns
    6. Compilations
  9. Playlists
    1. Normal Playlists
    2. Smart Playlists (live playlists)
    3. Transferring a local playlist to the iPod
    4. Sorting a playlist
    5. Renaming a playlist
    6. Deleting a playlist
  10. Podcast and Audiobook support
  11. Syncing
    1. Syncing Ratings
    2. Syncing Podcasts
  12. Autofill
  13. Ejecting iPod
Introduction

Note: This documentation is still a work in progress.

Hello and welcome to the documentation for the Winamp Media Library iPod Plugin, or as it is most often called, ml_iPod.
ml_iPod was originally developed by Justin Frankel and Christophe Thibault then later taken over by Will Fisher. The plugin is now under development by Achim Bursian.

  1. Windows 98*, ME*, 2000, XP
  2. Winamp Full (Version 5 is recommended, but some people have reported it working with Winamp 2. Winamp 3 is not supported.)
    1. gen_ml.dll - The Media Library needs to be installed when Winamp Full is installed to be able to access ml_iPod.
  3. One USB or Firewire port

* Windows 98 and ME do not have the appropriate drivers in order to view an iPod.  Apple's own iPod Updater will not work in Windows 98 or ME.  The following links should help in order to get an iPod working in 98 or ME:

  1. http://forums.ipodlounge.com/showthread.php?s=&threadid=6581
  2. http://www.98-drivers.com/ipod.html
  3. http://www.geocities.com/mmcfly8888/
Installing ml_iPod
  1. Make sure Winamp is closed.
  2. Find the ml_ipod installer and open it.  (Most often named iPod_Support_vxx.exe)
  3. Choose the destination you would like the plug-in to be installed.
  4. If pmp_ipod.dll is detected at the time of ml_iPod's installation, this step will help prevent the destruction of your iPod's database. The two plug-ins cannot coexist since they both try to read and modify the iPod's database at the same time. Please read the textbox in this step for further clarification.
  5. After the installer copies all of ml_iPod's files to the Winamp Plug-in folder, setup is complete and you may now choose whether or not to run Winamp and show the release notes.
Opening ml_iPod
  1. Open Winamp.
  2. Right click on Winamp and click Media Library or press Alt + L.
  3. Navigate to the left hand side of the Media Library and click on the iPod in the Devices section.
Configuring ml_iPod

Note: Device specific settings of ml_ipod are stored on the iPod itself (in \iPod_Control\iTunes\), so your settings will stay the same from computer to computer.

To access ml_iPod's preferences, simply right click on the iPod in the Devices section of the Media Library and click "iPod configuration..." or open Winamp's preferences (hotkey: CTRL + P) and navigate to iPod Support. There is also a Config button on the ml_iPod interface which will open the preferences.

If serveral iPods are connected, select which iPod you want to configure at the bottom of the preferences using the pull down menu.

The following is an explanation of ml_iPod's different preferences:

Library View Options:

iPod view layout: In "Artist/Album/Track view," the Media Library will be separated into three sections. The top left section will display the artists, while the top right section displays the albums on the iPod. The bottom section displays individual tracks from according to the selected items in the two sections right above it. This is very helpful for large music collections. In this view, no manual sorting is possible.

"Simple List View" will display all tracks at once from all artists and albums. Manual sorting (by artist, track...) is possible.

Ratings and Play Count Sync Settings:

Sync Ratings, Play Counts and Last Played Times on Connect: Every time an iPod is connected, the iPod and Media Library will be synced so all ratings, play counts, and last played times match.

Sync Ratings, Play Counts and Last Played Times on Disconnect: This setting does the same as the above setting when the iPod is ejected through Winamp.

Format iPod:

Please use caution when using this feature! Using ml_iPod's format feature will only erase songs/videos which are stored in the iPod_Control folder on the iPod. Calender and Note information will be left in tact.

To format the iPod, select the drive letter in the pull down menu then click the "Format iPod" button. A warning will appear then a confirmation box will confirm whether or not your iPod is an iPod Shuffle. Formatting will start after you have confirmed your iPod type.

Misc:

Don't check for updates: Enabling this setting will stop the automatic checks for updates of ml_iPod. (NOT recommended)

Look for iPods on network drives and fixed drives: ml_iPod will search for drives which mimic the iPod's file structure. This is mainly for debugging purposes.

Smart Playlist Live Updating: Smart Playlists will be updated on-the-fly by the iPod firmware whenever attributes of certain tracks change (playcount, rating, last played). This is the same as the "Live" checkbox in iTunes.

Prefer iPod to Media Library for playback: If a file double-clicked in ml_iPod, it will be accessed directly on the iPod file system instead of on the computer's hard drive.

Support to send video files: This will allow for the transfers of video files (*.mp4) to the iPod. Keep in mind, this feature is still experimental.

Sync to iPod Settings:

Sync Settings: configures what and how things will be synced on a sync

Show Confimation Box on: allows a confirmation box to be shown on all transfers, only on syncs, or never

Sync from iPod Settings:

These two fields allow the user to specify where and how songs from the iPod are copied when the Copy to Hard Drive feature is used.

Maintain Transfer Log:

If logging is enabled, each song/video that is transferred or erased will be written to a file called "iPod Transfer Log.txt." The file is stored in the root Winamp directory (usually C:\Program Files\Winamp\).

Advanced:

The advanced file settings allow for files to have unique filenames specified by the user. It is recommended to keep "Use iPod compatible mangled filenames" enabled since there may be compatibility issues with some iPods.

Volume Boost:

The volume boost feature allows for files to be played louder than originally intended. Enable the checkbox below the slider to apply the volume boost to only files transferred after the checkbox is enabled.

Note: Please be responsible when using this feature. Prolonged listening at high volumes can cause hearing loss. Apple has a website setup to warn consumers about this issue: http://www.apple.com/sound/.

Volume Normalization:

Normalize all tracks to: sets the decibel level files will be set to when using the normalize feature with the mp3gain utility

Skip tracks longer than: If a track is longer than this value, it will not be normalized. Useful for long audiobooks.

Audiobooks:

Use this field to enter genres which will classify audiobooks. Please put each genre on a line by itself. No empty lines are allowed.

Podcasts:

Sets the directory in which podcasts are stored and what genre they use.

Note 1: Transcoding a lossy file (MP3, AAC) to another lossy format will cause a loss in sound quality.

Note 2: The transcoding feature used by ml_iPod is buggy and is unlikely to be fixed any time soon. It is an external program and the author stated it as "broken"..

Transcode incompatible files: If enabled and an incompatible file is found during transfer, ml_iPod will attempt to transcode the file using the encoder which is selected in the transcoder settings. To access the transcoding settings, click the "Configure..." button.

Transcode MP3 files using: Enable the checkbox in order to use an external encoder when transcoding MP3 files. Use the field below to enter the full pathname of the encoder and its parameters. Quotes are needed around the pathname if the pathname contains spaces.

Use hymn on M4P files using: (Note: This feature is dependant on which installer you downloaded, one comes with hymn support and the other does not.) When enabled, ml_iPod will use Hymn to remove the DRM restrictions from M4P files that are being transferred.

To enable certain functions of ml_iPod to be mapped to hotkeys, you must have Nullsoft's Global Hotkey's plugin installed, which comes with Winamp.

Instructions to set a hotkey:

  1. Open Winamp's preferences (CTRL + P)
  2. Go to Global Hotkeys and make sure it is enabled
  3. Choose and action that is prefixed with "iPod:"
  4. Select the Hotkey field below and enter the key(s) to be used as the hotkey
  5. Click the Add button
iPod Tools

To access the iPod tools, right click on your iPod in the Media Library and hover over "iPod Tools". The sections below assume the iPod Tools menu is open.

Renaming an iPod will change the name that is displayed in the Media Library -> Devices section for that iPod. The name change will also be reflected in Windows Explorer and iTunes.
Using mp3gain, ml_iPod will normalize the volume of all songs to the same volume. This feature can be configured in the Volume tab of ml_iPod's preferences.
If any song is found to be on the iPod that is not in the Media Library's database, the song will be removed from the iPod.
If a song is found to be on the iPod that is not in the Media Library's database, the song will be transferred to the hard drive.
Smart views can be found under the Local Media section of the Media Library. When using this function, all of the smart views under Local Media will be mirrored onto the iPod as Smart Playlists.
Instead of running the database cleanup tools separately, all three can be ran consecutively. The cleanup status (for the full and individual cleanups) can be seen at the bottom of the main interface of ml_iPod in the Media Library.
This will scan the iPod's database for track entries where the corresponding *.mp3, *.m4a or *.mp4 file is no longer on the iPod. Such entries are removed from the database.
This feature will scan the database to make sure each file on the iPod still matches the data in the database (trackname, artist...) This is a lenghty process, because every file has to be opened and scanned for ID3 tags.
Probing for lost songs will scan through the iPod's music folders and check whether or not each file has an entry in the iPod's database. If a corresponding entry is not found, it will be added. Thus "lost songs" that are not listed in the iPod menus but are still on the device will be recovered.
Older versions (v1.1..v1.32) of ml_iPod had a bug that caused wrong timestamps in the iPod database as well as in the Media Library. This feature will fix timestamps that were affected by this bug. The "Smart sync ratings" feature is dependant on correct timestamps.
Copying songs/videos to iPod

Shortly after the completion of the steps to transfer items, a small window will open to show the progress of the transfer.

  1. Click on a smart view under Local Media
  2. Select which artist(s), album(s), or song(s) will be transferred (Ctrl and Shift can be held down to select multiple items)
  3. Right click on a highlighted item
  4. Open the "Send to:" submenu
  5. Click on the iPod (actual name may vary depending on how the iPod itself is named) to transfer to
  1. Select which items will be transferred (Ctrl and Shift can be held down to select multiple items)
  2. Right click on a highlighted item
  3. Expand the "Send to:" menu
  4. Click on the iPod (actual name may vary depending on how the iPod itself is named) to transfer to

Before using Windows Explorer to transfer items, make sure the Media Library is open to the iPod view.

  1. Open the folder which contains the files to be transferred
  2. Select which files and/or folders you want to transfer
  3. Drag and drop them into the iPod view of the Media Library

Note: When a single folder is dragged into the iPod view, a playlist will be created with the name of those folder. To prevent the playlist creation, hold CTRL while dragging the folders into the iPod view.

If an incompatible file is found during transfer, ml_iPod will do its best to convert the file(s) to the format chosen in the Transcoding preferences (see Transcode incompatible files)

In order to transfer songs purchased through the iTunes Music store, ml_iPod uses Hymn to decrypt the file(s) before transferring it. Hymn will only work if your computer is authorized to play those files (authorization is done through iTunes) or if a decrypted key can be found on your iPod. Using Hymn will not result in a loss of quality in the M4P file.

To transer an encrypted M4P file, the use hymn must be enabled and its location must be entered in the Transcoding preferences.

Transferring can be done the same as other files. Please use the tranferring steps above.

Copying songs to hard drive

Ml_iPod allows you to transfer a song from your iPod to a local hard drive. This is useful in the case that music on a local hard drive is lost and there are copies of those songs on your iPod. Setting for this feature can be found in the Transfer Settings tab in ml_iPod's preferences.

  1. Select the artist(s), album(s), or track(s) to be copied
  2. Right click on a highlighted item
  3. Click "Copy to Hard Drive"
Managing songs on iPod

There are two layouts that can be used to view the contents of an iPod. To configure this, go to the General tab of ml_iPod's preferences and select between "Artist/Album/Track View" or "Simple List View."

To search an iPod for specific items, type the search term in the "Search:" field at the top of the iPod view.

  1. Select which item(s) you want to edit (Ctrl and Shift can be held to select multiple items)
  2. Right click on a highlighted item
  3. Click on "Edit Item(s) Information"

Note: Edits are only stored in the iPod's database and are not written to the actual files.

  1. Select which item(s) you want to rate (Ctrl and Shift can be held to select multiple items)
  2. Right click on a highlighted item
  3. Expand the "Rate" menu
  4. Click on a rating from 1 to 5 stars or No Rating
  1. Select which item(s) you want to delete (Ctrl and Shift can be held to select multiple items)
  2. Right click on a highlighted item
  3. Click on "Remove from iPod"
  4. Click Yes to confirm delete

Alternatively, items can be selected and you can hit Delete on your keyboard.

To sort (descending or ascending) by a specific column, simply click on that column once.

To form a compilation of albums, right click on an album and click "Edit item(s) information..." and add "[C]" (without quotes) to the beginning of the Comment field.

Playlists

Playlists on the iPod are viewable in the Media Library by expanding the iPod view. This can be done by double clicking on the iPod (under Devices) or clicking the triangle to the left of the iPod.

To create a new playlist:

  1. Right click on the iPod under the Devices section
  2. Click "New Playlist"
  3. Name the playlist

Transferring songs to a playlist via Media Library -> iPod view:

  1. Select which item(s) you want to put into a playlist (Ctrl and Shift can be held to select multiple items)
  2. Right click on a highlighted item
  3. Expand the "Send To Playlist..." menu
  4. Click the playlist to add the items to or create a new playlist by clicking "New Playlist"

In order to view a smart playlist in Winamp, the files need to be loaded in the Media Library's database.  The smart playlists will still be viewable on the iPod (once ejected) if files are not in the Media Library.

To create a new smart playlist:

  1. Right click on the iPod under the Devices section
  2. Click "New Smart Playlist"
  3. Name the playlist

To edit the query, select a smart playlist, then use the field to the right of "Query:". To make things easier, click the Edit button to the right of the query field and use either the Simple View Editor or Advanced Editor to develop your query.

To limit the number of items in the smart playlist, enter an amount in the "Limit to:" field and select what to limit.

The Playlist section of the Media Library must be used to transfer a playlist. To add a playlist, right click on the Playlist section then choose how you would like to add a playlist.

To tranfer a playlist:

  1. Right click on a playlist in the Playlist section of the Media Library
  2. Expand the "Send to:" menu
  3. Click on the iPod you wish to transfer to

Playlists can be sorted by track number, artist, album, title, last played, or randomly. There is also an option to to smart shuffle the playlist which will group or separate tracks by album, artist, or genre

  1. Select a playlist on the iPod
  2. Click the "Sort by..." button
  3. Click which sort method you would like to use
  1. Right click on a playlist on the iPod
  2. Click "Rename Playlist"
  3. Enter the new name in the Rename Playlist window

There are two options for deleting a playlist. The first is to "Remove Playlist Only" and the other is to "Remove Playlist and Files." "Remove Playlist Only" will only remove the playlist and not touch any of the files contained in the playlist. However, the second option WILL remove both the playlist and the files in the playlist from the iPod. Please use caution when using the second option.

To delete a playlist:

  1. Right click on a playlist that is on the iPod.
  2. Click either "Remove Playlist Only" or "Remove Playlist and Files"
Podcast and Audiobook support

New in version 1.41 of ml_iPod is podcasting and audiobook support. Please keep in mind that support is still limited. Unfortunately, podcasts and audiobooks will not show up in their respective menus on the iPod. Luckily, the menus can be remedied via Smart Playlists.

Here are some example queries that can be made for Podcasts:

Tips for using podcasting support:

To mark podcasts for removal during the next sync, you must enable "Remove podcasts with rating >= 1 from iPod during podcast sync" and then when listening to the podcast on the iPod, rate the podcast from 1-5. This is useful for those podcasts that just don't catch your attention and you want to skip over.

Note: Songs marks as podcasts will not show up when you use the "Shuffle Songs" feature on the iPod.
Syncing

Syncing is the process of mirroring your Media Library onto your iPod. This includes songs, ratings, and playcounts. To do this, click the "Sync" button in the main iPod view.

To sync the Media Library smart views, please refer to the Syncing smart views section.

  1. Go to the iPod view in the Media Library
  2. Click on the "Sync Ratings" button
  3. Choose how you would like ratings and playcounts to be synced (explanations below)

Smart Sync: Smart Sync will only sync playcounts and ratings. It will compare the playcounts and ratings of files in the iPod's database and the Media Library's database. Whichever database has the most current metadata, it will be copied to the other database. (ie. If your iPod has the most current metadata for a song then your Media Library will be updated.)

Copy Play Counts and Ratings from iPod to Winamp: The metadata from the iPod will be transferred to the corresponding files in the Media Library.

Copy Play Counts and Ratings from Winamp to iPod: The metadata from the Media Library will be transferred to the corresponding file on the iPod.

  1. Go to the iPod view in the Media Library
  2. Click on the "Sync Podcasts" button
See the Podcasting and Audiobook support section for more details.
Autofill

Autofill is a feature mainly invented for the iPod Shuffle. It's function is to select songs randomly from your Media Library and transfer them to the iPod Shuffle. First it will remove all played songs on the iPod then refill it with new songs.

To use Autofill:

  1. Go to the iPod view in the Media Library
  2. Click the Autofill button at the bottom of the Media Library

Autofill can be customized by going into the "Sync Settings" of the Tranfer Settings tab in the ml_iPod preferences.

Ejecting iPod

Please do not disconnect the iPod unless the "Do not disconnect" sign is not on the iPod's display. To safely disconnect the iPod, click the "Eject" button on the right-hand corner of the iPod view and wait for the "Do not discconnect" sign to disappear on the iPod. The iPod can also be ejected by right clicking on your iPod under the Devices section and click "Eject iPod."

Credits: Timmy Authement and Achim Bursian