# Linking to iTunes/Music/TV

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

When linking, a lookup is performed in the Apple application's library. Two primary methods are employed:

Linking by Metadata
  When linking audio files via this method, the first step is to attempt to locate an item in the application which has the same Title, Album, Artist and file location. Files containing a video track attempt to match only by the Title. If a unique match 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 with audio files which includes the track number. If this second attempt works, the file's location is updated in the iTunes or Music.
Linking by Persistent ID (PID)
  When linking via this method an identifier representing the track in the Apple application's library is used. This method is preferable as it is location independant and does not require consistant metadata between the application's library and audio files. The downside of this method is that the so called persistent IDs must be acquired and they may be invalidated in the case of the Apple app;ication rebuilding its database.

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 - Apple Apps. If a PID match fails in this case, an attempt to match by metadata will occur. Note: PIDs are meaningless and should not be retained if you have more than one library in a given Apple application. When PIDs are not preferred, the Link to Apple App 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 Apple App>Link to Apple App menu item or toolbar item. An attempt will be made to link all selected files not yet linked. Note that APE, DFF, DSF, FLAC, OGG and WV files cannot be linked.

If linking by metadata and a metadata match cannot be made, the link method will fail. If you are new to Yate, this more than likely due to the fact that at some point the Apple application (primarily iTunes) did not write its metadata to the actual files. This is especially true with WAV files, where iTunes and Music never put the metadata in the files. (Yate gets around the WAV issue by force feeding WAV metadata to iTunes and Music). 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 an Apple application into Yate. The dragged tracks will be opened and linked. This method works as Apple apps pass enough information to Yate to let it associate one of its items with a physical file. Note that in Music, this only works when dragging from the Songs view. 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, the Apple application will be updated and successive normal attempts to link will work.

You can also load and link tracks which are currently selected in iTunes, Music and TV via the File>Open Selected Items in menu.

Yate can be configured to automatically save the Persistent ID whenever a track is linked. This is done via the Auto Import settings in Preferences-Apple Apps. Unless you have more than one library, this is strongly recommended.

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

- Apple Apps>Save Apple App PIDs
- File>Save

The above sequence will retain the PID information, automatically unlink the files so that the Apple application does not get updated when saving the file from Yate. You may not want this to happen as the Apple application 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 action statements:

- Save Apple App 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 an Apple App into Yate, save the link information and acquire the PIDs.

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

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, the Apple application will be updated whenever you save the files. If you make changes to the files when you were not linked, you can still update the Apple application by linking and then doing a Refresh Apple App 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 the Apple application, you can remedy the situation by doing an Import Fields from Apple App via the Actions menu. Once done your files will contain the same metadata as Apple's application.

If you have thousands of tracks in an Apple application, it is probably not feasible to drag/edit/save without losing your sanity. You can run a batch process to extract the PIDs from from the Apple application.