# Interacting with iTunes

The primary requirement in interacting with iTunes is establishing a link between Yate and iTunes. This link can be initiated from within Yate or iTunes. Regardless as to how the link is established, it is transient and is removed when the linked files are closed in Yate.

If you're going to use Yate to manage your iTunes metadata it is almost mandatory that you do not allow iTunes to keep your media folder organized. When iTunes organizes your media files, it will automatically rename and move your files around as it sees fit. Renaming and/or moving files in Yate may not stick if iTunes goes and changes the file names/locations after the fact. Another disadvantage of the Keep iTunes media folder organized option is that iTunes may split album contents into disjoint folders depending on the metadata. The only practical approach to album organization is regardless of your folder structure, the tracks of an album are in a single folder. You disable the keep media folder organized option in iTunes by unchecking the setting in iTunes Advanced Preferences.

When linking tracks, a lookup is performed in the iTunes database. Two primary methods are employed:

Linking by Metadata
  When linking via this method, the first step is to attempt to locate a track in iTunes which has the same Title, Album, Artist and file location. If this is found the file is successfully linked. If the metadata was matched but the location could not be matched, a second matching attempt is made which includes the track number.
Linking by Permanent ID (PID)
  When linking via this method an identifier representing the track in the iTunes database is used. This method is somewhat preferable as it is location independant and does not require consistant metadata in the iTunes library and and audio files. The downside of this method is that the so called permanent IDs must be acquired and they may be invalidated in the case of iTunes rebuilding its database.

Whenever a file is linked, its location is patched, if required, in iTunes.

Yate has distint commands to link by metadata and by PID. If you wish you can configure the application's linking commands to use PIDs if available and metadata if not. This is enabled by setting the Prefer PIDs when linking option in Preferences-iTunes. Note: PIDs are meaningless and should not be retained if you have more than one iTunes library. When PIDs are not preferred, the Link to iTunes by PID command can be used to manually force linkage by PID.

As we assume you will be doing most of your metadata editing in Yate, the most common method of linking is to use the File>Link to iTunes menu item or toolbar item. An attempt will be made to link all selected files not yet linked. Note that FLAC, DFF and DSF files cannot be linked to iTunes.

If linking by metadata and a metadata match cannot be made, the above link method will fail. If you are new to Yate, this more than likely due to the fact that at some point iTunes did not write its metadata to the actual files. This is especially true with WAV files, where iTunes never puts the metadata in the files. (Yate gets around the WAV issue by force feeding iTunes WAV metadata). The failure can also be an indicator that you simply have little or no metadata for a track in iTunes. In this case the PIDs must be acquired.

If you drag tracks from iTunes into Yate. The dragged tracks will be opened and linked. This method always works as iTunes passes enough information to Yate to let it associate an iTunes item with a physical file. Depending on the Open Mode, more files may be opened than were dragged. Only the dragged tracks will be linked. Once you've dragged the tracks into Yate, you can edit the metadata. When the changes are saved in Yate, iTunes will be updated and successive normal attempts to link will work.

Yate can be configured to automatically save the Permanent ID whenever a track is linked. This is done via the Auto Import settings in Preferences-iTunes.

To set up the sort of permanent linkage manually, drag the tracks from iTunes into Yate. Then do the following:

- Actions>Save iTunes PIDs
- File>Save

The above sequence will retain the PID information, automatically unlink the files so that iTunes does not get updated when saving the file from Yate. You may not want this to happen as iTunes may contain more metadata than the files (Yate) at this point. Saving the files will preserve the PID information. The sequence can be automated in an action by the following statements:

- Save iTunes PIDs
- Save all files (Modified)

You can assign the action to a keyboard shortcut or even to a toolbar button. Using the above method, you can drag thousands of tracks from iTunes into Yate, save the link information and acquire the PIDs.

If your iTunes library was rebuilt, you can remove the PIDs from the UI via Actions>Remove iTunes PIDs or by an action using the statement of the same name.

- Remove iTunes PIDs

Once you have link capability you can actively work on your files. If the files are linked and you make changes to the metadata, rename or move the files, iTunes will be updated whenever you save the files. If you make changes to the files when you were not linked, you can still update iTunes by linking and then doing a Refresh iTunes from the Actions menu.

If after linking you notice that your files have little or no metadata (very common with WAV files pre-Yate), while there appears to be metadata in iTunes, you can remedy the situation by doing an Import Base Settings from iTunes via the Actions menu. Once done your files will contain the same metadata as iTunes.

If you have thousands of tracks in iTunes, it is probably not feasible to drag/edit/save without losing your sanity. If you are running iTunes v11 or later, you can run a batch process to extract the PIDs from iTunes.

iTunes keeps many metadata items in its library which it never writes to the files. When files are linked to iTunes, you can pass rating, play count, skip when shuffling, start time, stop time, volume adjustment, classical (new to iTunes 12.5), loved/disliked (new to iTunes 12.5) and remember playback position metadata between Yate and iTunes. You can also extract iTune's artwork for an album and overwrite the linked file's artwork. (iTunes at times did not write out artwork).

The main window's iTunes column displays various state indicators. If any of the indicators are displayed the file is linked. The indicators are:

> ✓
>   linked with no metadata differences.
> ☆
>   track has an explicit album rating. See The iTunes Album Rating for more information on explicit album ratings. Note that album ratings are not used by the Import from iTunes functionality and can only be cleared by the Export to iTunes functionality.
> C
>   classical metadata differs
> ♥
>   loved/disliked differs
> M
>   media kind differs
> ▼
>   permanent ID differs
> #
>   play counts differ
> ★
>   ratings differ
> R
>   remember playback position differs
> ✖
>   skip when shuffling differs
> ⇤
>   start time differs
> ⇥
>   stop time differs
> ⬆
>   volume adjustment differs

You can choose to ignore any of these items, via Preferences - iTunes. You can also set any of the items to always import and always export when you open or save files while linked.

Classical metadata refers to the fields: Work Name, Movement Name, Movement Number and Movement Count. The proper understanding of what has to be done to properly synchronize classical and grouping metadata can be found in iTunes, Classical Metadata and the Grouping Field.

The iTunes Media Kind value is mapped to Yate's Media Type field. When setting the media kind, any value other than one of the following is ignored: Audiobook, Alert Tone, Booklet, Home Video, iTunesU, Movie, Music, Music Video, Podcast, Ringtone, TV Show, and Voice Memo. iTunes will refuse to process some settings. For example you cannot change the media kind of a video file to be Music.

We've discussed linking to iTunes, but Yate can also be used to add files to iTunes as part of your standard new album workflow. You add files via the File menu's Add to iTunes item or via a toolbar button. An attempt will be made to add all selected files not already linked to the iTunes library. Files successfully added will be linked. Note that adding files can be verify slow if your iTunes library is large. Yate simply tells iTunes to add the files and then waits, and waits, and waits... If Preferences - iTunes - Auto Import - Permanent ID is set, the permanent IDs will be imported when the files are added.

When files are linked, and Yate renames and/or moves a file, the file's location will automatically be updated in iTunes, if necessary.

Once a file is linked, you can manually import and export iTune's metadata retained in its database which is not written to audio files. You do this via the Actions menu items: Import from iTunes and Export to iTunes. The values that get imported or exported depend on what items you have enabled to be imported/exported via Preferences - iTunes. You can also compare the iTunes values with the Yate values and selectively import or export any value regardless of the preference settings. For more information see Compare iTunes Values.

For both importing and exporting, if the file being manipulated has more than one rating field, the first rating is used.

When linked files are saved, Yate will automatically tell iTunes to refresh its metadata. All changes you have made and saved in Yate, which are supported by iTunes will be applied to the iTunes database.

Hint: Link to iTunes before you start making lots of changes to your tag information. This maximizes the chances of your files being located in iTunes the next time you link. If you've made changes to your files' Album, Artist or Title metadata and you forgot to link first, you can attempt to link with the initial values in place when the files were first loaded or last saved. You do this via a File>Link to iTunes with Initial Values. This only really applies if PIDs are not being used.

Note: No operations are performed between iTunes and FLAC, DFF or DFS files. If you want to change metadata in WAV files, link, then make the changes in Yate so that iTunes updates its library. iTunes does not write WAV metadata to the files, nor does it display any artwork you place in the files (other Audio players will).

If for any reason you want to drop the linkage between iTunes and Yate, you can use the File menu Unlink from iTunes item. The only reason to ever use this function is if you do not want to refresh iTunes when saving changes.