TuneSpan Scripting Documentation & Pre-made Scripts for TuneSpan
TuneSpan allows you to truly manage the media files in your iTunes Library, giving you the ability to effortlessly move them to wherever you choose (an external drive of any kind, even a network drive) and easily keep track of all locations.
TuneSpan uses the term "span" to describe relocating your media files; you can have your files spanned across many different drives without any confusion or hassle.
TuneSpan never removes any of your tracks from iTunes, so your playlists, play counts, etc. are always preserved.
TuneSpan makes copies of your media files at the selected location; none of your media files are ever deleted automatically. Once a file has been successfully copied, TuneSpan will set the new location in iTunes. That's the spanning process for a track; copy its file and update its location in iTunes. And, if you choose, TuneSpan can clean up after itself: After tracks have been successfully spanned, TuneSpan can move the original files to the Trash, and even check for empty folders and move those to the Trash as well to help keep your system tidy.
TuneSpan's interface provides the ability to quickly see where your media files are, and easily restore them to their original locations, or to move them around again.
Not only does TuneSpan provide the ability to easily move your media files around, but it also allows you to browse your iTunes Library in much more comprehensive and sophisticated ways.
First and foremost, TuneSpan has a location browser, so you can see where your media files are located. TuneSpan also provides more advanced filtering options than iTunes. For example, if you select a media type, the rest of the interface will update to only show playlists which contain that media type and only show locations with files of that media type. Moreover, filters can be combined to narrow what you see in the interface, with a media type selected; you can then select a playlist and the locations will be updated to only show files for tracks of the selected media type in the selected playlist. In the toolbar, you can quickly see what filters are active, and click to bring up a menu to easily modify or clear your active filters.
TuneSpan provides primarily a drag-and-drop interface, but can also be fully controlled by the keyboard, and contains many contextual menus to provide advanced functionality and usability.
iTunes manages multiple library files, one of which is a readable (but not editable) XML file which is created to allow 3rd-party applications such as TuneSpan to access the track and playlist information in iTunes.
TuneSpan does not directly modify the iTunes Library, but uses AppleScript to set track attributes, such as location.
In iTunes 12.2 and newer, there is a "Share iTunes Library XML with other applications" checkbox option in the Advanced Preferences. If this option is off, iTunes will not create an iTunes Library XML file and TuneSpan will not be able to load.
To be able to use TuneSpan, make sure "Share iTunes Library XML with other applications" is enabled.
If this Advanced Preference in iTunes is turned on, and you are still having trouble loading TuneSpan, please Contact Developer Directly.
TuneSpan can open iTunes Libraries from any location, as well as manage multiple iTunes Libraries. If your iTunes Library is not found in its default location, you can simply locate your iTunes Library through TuneSpan. If you have multiple iTunes Libraries you wish to open, you can select Change Library… from the File menu or hold down the Option key when loading TuneSpan to change your iTunes Library.
TuneSpan will keep track of iTunes Libraries that you've loaded so that you can easily switch between them without having to relocate the files each time you reload. But, it is also simple to select a new iTunes Library for TuneSpan to load and it will be remembered from then on.
Even though TuneSpan loads the readable XML iTunes library file, TuneSpan has you locate the main binary iTunes Library file (with either no extension or extension ".itl") so that TuneSpan can always locate and load the latest version of the readable XML library file.
TuneSpan stores some library specific preferences for your convenience, but most of TuneSpan's preferences are shared between all libraries you load. All of the interface display options and all of the options that you see in the applications General, Updating, and Advanced Preferences (except one mentioned below) are shared between all libraries. Although, TuneSpan automatically stores some other preferences that are library specific, such as, open folders in the Playlists and Locations source lists, tracks saved in the spanning queue, last spanned tracks, saved span location, span location history, and in the Advanced Preferences, files to leave alone for spanned tracks deleted from iTunes.
Copy Files & Set Locations
For each track, TuneSpan first copies the track's file to the new intended location, creating subfolders automatically to organize your media. By default, TuneSpan uses the same media organization as iTunes, but you can customize how TuneSpan organizes your media.
After the files has been successfully copied, TuneSpan uses the AppleScript command set location to inform iTunes of the new file location.
Verify Locations & Clean Up Successfully Copied Files and Empty Folders
After the first simple steps have been done for each of the selected tracks, TuneSpan verifies that iTunes knows the intended location of each track. To do this, TuneSpan tells iTunes to quit, allowing iTunes to save its library and update its readable XML library file. After iTunes has quit, TuneSpan rereads the XML library and verifies the location of each selected track. If iTunes knows the intended location, then TuneSpan can clean up after itself, moving each successfully copied file from its original location to the Trash. TuneSpan can also check for empty folders and move those to the Trash as well. You can choose whether or not you want TuneSpan to clean up after itself in the preferences.
If iTunes does not update the location for any tracks, TuneSpan can reattempt the span a set number of times. If the span continues to fail, TuneSpan will move the copied files to the Trash, leaving the original files in their original locations. TuneSpan will still move any empty folders to the Trash to make sure there are no duplicate files or clutter left behind.
Never Deletes Files, Only Moves Them to the Trash
TuneSpan never deletes any files or empty folders, they are only moved to the Trash. Upon completion, TuneSpan offers a button to tell Finder to empty the Trash if you choose to do so. But, there is an exception, sometimes files on network drives cannot be moved to the Trash, even the Finder can only immediately delete them. If this is the case, TuneSpan will warn you that some files could not be trashed and offer to delete them immediately for you. But, TuneSpan will not automatically delete your files; files will only ever be immediately deleted when you explicitly give permission to do so.
Keep Listening to Your Music
Also, you can continue to listen to your music in iTunes during the spanning process. Before TuneSpan quits iTunes, TuneSpan will check if you are listening to music. If you are, TuneSpan will relaunch iTunes and start playing the track again where it was left off.
Restoring Files is Just as Easy
TuneSpan also offers a Restore Mode which works identically to the Span Mode except it will just relocate each file to wherever it came from before it was spanned by TuneSpan.
If you consolidate your library through iTunes, TuneSpan will update its library to follow the new locations for all of your tracks. But, iTunes will only make copies of your files and leave the originals in their current locations, creating duplicate files on your system. Instead, you can consolidate your library with TuneSpan and it will clean up after itself, leaving no duplicates behind. In TuneSpan, simply select Select All Track to Consolidate Files… in the Spanning Queue menu (in the Edit menu or right-click the spanning queue drop zone). You can set any span location to consolidate your tracks too, but of course, you can just select your default iTunes Media location as well.
If you delete a spanned track from iTunes, it won't be any kind of issue for TuneSpan. But, when you delete tracks from iTunes whose files aren't in the iTunes Media folder, iTunes won't offer to move the files to the Trash, it's just a built-in behavior of iTunes. Since iTunes will leave these files behind, your system could become cluttered with unused media files. But, TuneSpan can help you deal with this annoying situation.
TuneSpan will detect files left behind from spanned tracks deleted from iTunes. TuneSpan will even make sure that these stray files haven't been re-added to your iTunes Library as new tracks. TuneSpan does this checking during the loading process, if some truly stray files are detected, it will alert you of the situation and show you a list of the files whose tracks have been deleted from iTunes. In the presented alert you have the options to leave files alone, trash files, or be reminded later (on next load). In the list you can select and deselect files to leave some alone and trash others, if you choose. Any files that you choose to leave alone will be remembered, and TuneSpan will not offer to trash the files again (unless you reset the list). You can also have TuneSpan always leave all files alone which will disable the checking process entirely. You can adjust this option and clear the list of files to leave alone at any time in TuneSpan's Advanced Preferences.
Just like in the spanning process, TuneSpan never deletes any files or empty folders, they are only moved to the Trash. After files are moved to the Trash, TuneSpan will prompt you with a success message and offer a button to tell Finder to empty the Trash if you choose to do so. But, there is an exception, sometimes files on network drives cannot be moved to the Trash, even the Finder can only immediately delete them. If this is the case, TuneSpan will warn you that some files could not be trashed and offer to delete them immediately for you. But, TuneSpan will not automatically delete your files; files will only ever be immediately deleted when you explicitly give permission to do so.
This is just another way TuneSpan helps keep your system tidy. You should rarely need to think about it, but if you delete some spanned tracks from iTunes, just remember to launch TuneSpan.
You're covered. TuneSpan has built-in crash recovery. Just relaunch TuneSpan and respan or re-restore your tracks. TuneSpan will reselect your previously selected tracks and span location, or will reset restore mode and guide you through the process safely and informatively. If you can't recover on TuneSpan's next launch, you can quit, selecting Quit & Recover Next Launch in the alert sheet to keep TuneSpan in crash recovery mode for a later restore. But, it's important that you allow TuneSpan to complete its recovery process immediately after a crash that occurred while spanning or restoring. Here's why:
When TuneSpan crashes while spanning or restoring, its library is not saved properly, so TuneSpan may not know all of the tracks' intended locations. Also, iTunes may not know all of the tracks' intended locations either. There is also a chance that duplicate files could be left in the original track locations. TuneSpan's crash recovery will resolve all of these issues and make sure that TuneSpan and iTunes know the intended track locations and that no duplicate files are left behind. If you completely follow the recovery process after any crash, everything will be fine.
Hold down the Option key when dragging a selection to the spanning queue to remove the selection from the list. This can be very useful if you want to exclude certain tracks (such as tracks in a playlist) from a span.
In the browser, hit Spacebar to jump to the top of the list. When you're at the top, hit Spacebar again to jump to the bottom.
When resizing either the Playlists or Locations views, hold down Shift to resize both views simultaneously and equally. Also, you can hold down Option while resizing either view to lock the width of the middle view, allowing you to either push in or pull out the width of the opposite view.
Nearly every aspect of the TuneSpan interface has helpful contextual menus: Right-click around to see what options can be accessed with a quick click.
To select the iTunes Library you want to load on launch, hold down the Option key as TuneSpan loads. If TuneSpan is already loaded you can hold Option while reloading TuneSpan or select Change Library… from the File menu
You can fully manage your span locations through modifier keys:
Hold down Option as you select a location from your history to remove it from the list. If the location cannot be found and is disabled, hold down Option as you open the menu to enable all items. Also, you can click your currently selected span location while holding Option to clear it.
To add a location to your history without having to actually span to it, hold down Command as you open the menu to add the selected location to the list.
Also, be sure to check out the options in the preferences ( Option + , ).