Restore/Synchronize Database
Version 4.0
(former Restore PlayHistory/Playlists/Metadata)
- MediaMonkey Add-on -

by Zvezdan Dimitrijević

This is information about the new enhanced version of Restore/Synchronize Database add-on for MediaMonkey v3.x-4.x. The old version of this add-on was already very effective for transferring data between database files, but the new version is even more powerful and it has added many very useful options; among others it allows import/export of records about unmatched files, i.e. files that are missing from the database, so you could restore data even to the empty databases.

Donation

The previous version of the add-on has a free access to download, but the new enhanced version is available only to those who donate to me using PayPal because I have spent too much of my time developing it. Just leave me a note about your e-mail address, if it is different than the one that you have registered at PayPal, since I am sending this version of the add-on using e-mail attachment.

If you didn't get my e-mail for a day or two after your donation, you could check your Spam folder first and, if you cannot find it in there, please send me an e-mail with the information about donation to: . Actually, if you are a GMail user, I recommend that you put my e-mail address to your Contact list before you make donation, so that GMail will not treat my e-mail sent to you as a spam. Thanks in advance!

Euro (EUR) US Dollar (USD)

Compatibility

This add-on doesn't work with MediaMonkey v5! Actually, none add-on made for some previous version of program could work with MM5, either by me or by another authors, since MM5 has completely different programming interface than before. If you really like my add-on and think that it is essential for your work with the program, you have several possibilities:
- you could stay with MM4;
- you could ask MM developers to implement support for old add-ons in MM5;
- you could wait for me to port the add-on to MM5, but don't hold your breath.

If you decide to stay with MM4, rest assured that I will still improve and support the add-on as long as there is an interest for it.

What is new

v4.0 - 2016-12-21

Installation

Just double-click on the RestorePlayHistory-xx.mmip file; if you are on Vista or Win7 and you got "Product installation error", make sure you have MM set to "Run as Administrator".

Usage

First of all, it is highly recommended that you make a periodical backup of the database file. You could use this add-on to make the backup or you could copy the database file by yourself - here you could find its location depending of the version of MediaMonkey and Windows.

This add-on could restore data from/to some backup (external) database file, but it cannot restore the current (active) database with itself. However, if you have corrupted current database and you don't have any backup file, with this new version of the add-on you could do this:
- open the program and turn off the Folder Monitoring continuous scan option for all folders (Tools > Options > File Monitor button on the Library sheet);
- exit the program;
- make a copy of your current database file to some temporary folder and delete it from the MM folder where it is stored or just rename it;
- start the program and, since the current database is missing now, the program will create a new empty one;
- open the add-on's dialog box using Tools > Scripts > Restore/Synchronize Database menu item;
- enter the path of file that you have copied to the temporary folder into the Backup database file text box;
- choose Add unmatched files;
- set other data that you want to restore;
- click on the Import button;
- if everything is fine, resume your settings of the Folder Monitoring.

RestorePlayHistory-4.0-01b

The Restore/Synchronize Database dialog box could be opened using its corresponding item in the Tools > Scripts menu. The backup (external) database file should be specified first in the Backup database file text box. The data will be transferred (restored) from that file to the current database if you choose Import or they will be transferred from the current database to the specified backup file if you choose Export. The backup database file should be different than the current database file.

Immediately after you specify the backup file, the add-on will start comparing the backup with the current database and that process could be very slow, especially with the higher Matching criteria (more about it latter). So, if you have large database with too many records, it is recommended that you choose lower Matching criteria before you specify the backup database file. The remaining options in the dialog box determine which data will be restored and for which files.

File restrictions
You could choose which files should be restored using several Restore data only for options. If you turn on the Selected file(s) option, data will be restored only for matched and/or unmatched files that belong to the group of files that are selected in the main filelist. You cannot import data for unmatched files if you turn on the Selected file(s) option, since you can select only files in the filelist that belong to the current database, but you could import data for matched files. The export of data is possible using this option both for matched and unmatched files. If you want to restore data for unmatched files, you need to turn on the Add unmatched files option as well, which will be mentioned in details latter.

With the Files in collection option (Filtered files in MM3) you could choose to restore data only for matched and/or unmatched files in the specified collection. This option is mutually exclusive with the previous Selected file(s) option, i.e. you could use one of them, but not both. Similarly with the previous option, you could export data both for matched and unmatched files from the specified collection without a problem, also you could import data for matched files just fine.

It is very important to know that the import of unmatched files using some specified collection could result with faulty data in some cases! It shouldn't be a problem if you have selected collection with a criteria having simple fields that are stored only in the Songs table, e.g. Type, Extension, Bitrate, Comment, Grouping, Custom 1-5... The native collections, like Music or Video, are based on the Type field and they are generally safe.

However, there could be a problem if you use some field whose data are stored in several tables, e.g. Artist, Album Artist, Album, Genre, Tempo, Mood, Occasion, Quality, Composer, Conductor, Lyricist, Producer, Actor or Playlist, while using conditions where you could choose one or more values from the table with check boxes (conditions like "contains/starts with" are safe). If you are not sure what kind of collection is that you want to use to import unmatched files, just send me an e-mail with the screenshot of the collection's settings and I will tell you if it is safe for use.

The last option from the Restore data only for group is Unmatched files and it should be turned on if you want to restore data only for such files; the matched files will not be restored in that case even if you have them. This option is enabled only if you turn on the Add unmatched files option first.

The Matching criteria combo box determines which criteria will be used to match files between the backup and current databases. These criteria are cumulative, e.g. if you choose the 4-th one, all previous testing will be executed before that one:
0. only corresponding files at specified locations
1. previous criterion OR equal full paths (folders\filename.extension)
2. all prior criteria OR equal checksums
3. all prior OR equal filename.ext AND FileLength AND Album AND Year AND Track#
4. all prior OR equal paths w/o drive letter, first folder & ext. AND SongLength
5. all prior OR equal filename w/o ext. AND SongLength AND AlbumArtist AND Album AND Year AND Track#"

These criteria are already known from the previous versions of the add-on, excluding the first one in the list (0.). The 2-5. criteria cover situations with modified file locations after backup. The 4-5. criteria further cover situations with different media formats in the backup and current databases, e.g. if the backup database contains .flac tracks and the current one contains .mp3 tracks instead, but with the same filename, song length and other mentioned tags. The data for tracks that are not matched between the current and backup database files would not be restored, unless you choose the Add unmatched files option.

The old version of the add-on allowed matching only one-to-one file, so duplicates was not all restored. However, the new version allows duplicates in matched files (duplicates in the backup file on the import, or duplicates in the current database on the export), in which case their data (particularly the play history) will be merged into the target files. The second criteria is default in the new version because each additional level of matching could slow down the add-on and could even result with the false duplicates.

Locations of files
If you want to use the first option from the Matching criteria list, you need to have specified locations of files that are stored in the backup and current databases using the Backup/Current location of files text boxes. This is useful if you have the same hierarchy of folders in both backup and current databases differing only in their base folders. For example, I could have the same structure of folders within the c:\Users\Zvezdan\My Music\ folder in the backup database and e:\Media\Music\ in the current database.

You could specify Backup/Current location of files even if you choose some another criteria from the Matching criteria list, but in that case the matching will be first tested for the first criterion, i.e. for the specified locations, and after that for another criteria. If you leave these location text boxes empty, the matching will not be performed using the first option from the Matching criteria list, so you need to specify some another criteria or you will get zero matched files.

The Backup/Current location of files text boxes could be used not only to specify locations for matching criteria, but also for specifying the source and destination locations when adding unmatched files and copying of media files if the corresponding options are turned on.

Unmatched files (missing in database)
The Add unmatched files option allows adding records of files that are missing in the current database if you choose Import, or you could use it to add files that are missing in the backup database file on Export. For example, if you have one old backup database file on the shared NAS, and if you have added some media files to the current database in the meantime, you could choose that option to export records about those files to the backup database.

If you turn on the Add unmatched files option, all fields of unmatched files from the Songs table will be copied and also data from other tables related to the metadata (Artists, Genres, ...), even if you have turned off the Restore metadata in related tables option. However, if you want to restore play history for unmatched files, you need to turn on the Restore playhistory option as well. The records about unmatched files could be restored only for files that physically exist at the source location if you choose the Only if physically exist option.

When using the Add unmatched files option, only records about files are transferred to the target database, but not media files themselves, unless you turn on the Copy media files option as well. The Copy media files option is enabled only if you have specified Backup/Current location of files. This option is not as sophisticated as the native Add/Rescan files to the Library option of the program, e.g. it cannot copy other files from the folder that are related to the copied media files (e.g. .txt or .html), so if you want such thing you better use the MM option to add missing files instead. If you choose to copy media files, you could determine what will happen if you have copied files with the same names as the ones at the target locations using the Overwrite files option.

Play history
The Restore playhistory option should be turned on if you want to restore the playing data in the Played table and the PlayCounter/LastPlayedDate fields in the Songs table for matched and/or unmatched files. If you run this add-on twice with the same backup file, and if you choose this option again, it will not add the play history twice - the add-on will compare those data from the backup and current database files and if they are same it will skip them, i.e. it will add (merge) only the new playing data.

However, if you turn on the Clear existing playhist. of matched files first option, the add-on will remove all playing data from the Played table for matched files from the target database before restoring them from the source database. Also, the PlayCounter/LastPlayedDate fields in the target Songs table will be based only on the data from the source database in that case.

The Use Played table to get Play counter option should be turned on if you want to calculate the value that will be stored to the target PlayCounter field based only on the restored playing data from the source Played table; otherwise this add-on will calculate that value using the PlayCounter field from the source database. If you play your media files only on the computer, these two values should be the same. However, if you play your files on some portable player, the PlayCounter field could contain value that is different (greater) than the number of playing data in the Played table. So, you should choose which kind of calculation you want to use for that field.

Playlists
You could restore both Static playlists and/or AutoPlaylists using the corresponding Restore options. However, some type of playlists will be restored even if you do not select them if they are parents of the playlists of the chosen type. For example, if you have some auto-playlist that has the child static playlists, that auto-playlist will be restored if you select Static playlists even if the AutoPlaylists is turned off.

The Clear all pls. first option is enabled only if you have turned on both Static playlists and AutoPlaylists check boxes. If you have that option turned on, the add-on will clear the Playlists and PlaylistSongs tables in the target database completely before restoring playlists from the source database. Please be very careful when using that option! If you turn it off, the add-on will merge the playlists from the source database with the existing ones in the target database. This option is mutually exclusive with the next Replace equiv. pls. option.

The Replace equiv. pls. option should be turned on if you want to replace the content of playlists in the target database with the content of playlists from the source database which have the same names (within the same parent playlist). That option is enabled if you have either Static playlists or AutoPlaylists check box turned on and it is mutually exclusive with the previous Clear all pls. first option, i.e. you cannot replace playlists with the same names if you choose to clear all playlists in the target database first.

The Only on last level option should be turned on if you want to replace playlists with the same names only if they are on the last (rightmost) level of playlists, i.e. they don't have child playlists. Otherwise, the content of all equivalent playlists will be replaced, even if they have child playlists.

Collections/Views (Filters in MM3)
The Restore collections/views option should be turned on if you want to restore collections and views in MM4, or filters in MM3. If you turn on the Clear related tables first option as well, the collections/views will be completely cleared in the target database before restoring the collections/views from the source database. Please be very careful when using that option! If you turn it off, the add-on will merge the collections/views from the source database with the existing ones in the target database.

The Replace equivalent collections with the same names option should be turned on if you want to replace collections in the target database with the collections from the source database which have the same names. Similarly to the playlists, the Replace ... option cannot be used if the previous Clear ... option is turned on.

Metadata
You could restore the selected metadata for matched files if you turn on the Restore metadata in related tables option, in which case the add-on will update Songs table and other tables that are connected to it by some field, e.g. Artists or Genres. All metadata will be automatically restored for unmatched files if you turn on the Add unmatched files option, even if the Restore metadata in related tables option or some particular metadata below that option is turned off.

The All check box doesn't represent any new option; it is actually added to allow a quick way to toggle on/off all check boxes for particular metadata below it.

The Update tags in files too (only on Import) option allows updating of tags in media files for the corresponding metadata in database on Import. If you forget to turn on that option, but you want to have updated tags in files as well, after restoring of metadata in database you could choose the Synchronize Tags option of the program.

The remaining check boxes on the bottom of the dialog box allow you to choose which particular metadata you want to restore, e.g. Date Added, Artist...

Info line and commands
The information line on the bottom of the dialog box displays the total number of files in the backup (external) and current databases, as well as the number of matched, unmatched and existing files both for the backup and current databases. If you don't have duplicates, the number of matched files for the backup and current databases should be equal.

The leftmost button on the bottom of the dialog box allows showing/selecting of matched/unmatched files in the main filelist of the program, with the particular action that could be chosen from the following dropdown list (Keep matched, ...). The next combo box determines which chosen files will be showed/selected - only those from the current filelist or those from the entire Library.

You could click the Backup button if you want to make a copy of your current database file using the destination path specified in the Backup database file text box.

After you have adequately set all previously mentioned options, you could click the Export button if you want to transfer data from the current database to the specified backup file, or you could click the Import button if you want to transfer data from the specified backup file to the current database. Then just wait for the add-on to finish, it could be rather slow and maybe will need several minutes with larger databases.

Additional INI keys

The [RestorePlayHistory] section of the MediaMonkey.ini file contains one less used option that is not represented with GUI:
  • PlistAltMethod - determines the restoring method of static playlists in MM3: slower, but more reliable method = 0 (default), faster method = 1. The default method is very slow, but it is more reliable when the backup file contains corrupted database. The another method could cause the missing tracks from playlists, but it is a way faster. For example, with one test database the faster method lasted approx. 150 seconds instead of 1600 with the default method.

    The MediaMonkey.ini file is stored in the c:\Documents and Settings\User_Name\Application Data\MediaMonkey\ folder for MM4 and Win7. You could find the location of the .ini file depending of the version of MediaMonkey and Windows here. If you want to modify the mentioned key in it using e.g. Notepad, you should do that with closed MediaMonkey application.

    Important

    This add-on is relatively dangerous and could cause some corrupted data in the current database, especially if you forcibly terminate the program during its execution! Please make one more backup of the current database before you apply this add-on. Well, maybe you should make a copy of the backup file itself, because, if you mistakenly choose the Export command instead of Import, this add-on will modify the backup file as well.

    If you have upgraded computer or changed hard disk and if you copied all media files to it keeping the same folder structure, then you could first try to transfer MM database to it and update it using
    Update Location of Files in Database add-on instead since it is a way faster and simpler to use.

    Disclaimer

    This software is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software.

    Notice

    This add-on is a false positive reported as a worm by F-Secure. The author of F-Secure promised me that will update its database and put the add-on on white-list, but still didn't. If you go to the www.virustotal.com/en/ site, you will see that it is safe tested by 54 popular anti-virus engines; the only one reporting a worm in it is F-Secure. By the way, the F-Secure was constantly having the largest number of false positives in last few years according to the Real-World Protection Test by AV-Comparatives.

    If you are interested about my other add-ons for MediaMonkey, you could visit the following page.