macOS Catalina (and Big Sur) and iTunes Media Files

Status: Dec 2020 - Confirmed that Big Sur uses the same Media file locations


Apple decided to abandon iTunes with its Catalina macOS release. In Catalina the iTunes media swiss army knife has been replaced with three  seperate applications and some functions that are now "hidden" in sharing.

The impact is that upgrading to Catalina changes quite a lot of macOS media handling. This is likely to be problematic, for many Mac users, as media content is one of the most valuable things on a well used Mac.

This note provides guideance as to where the various media files are stored and what you can do to make things managable.


iTunes File Locations

With iTunes all your media was contained within:

  • ~/Music/iTunes (by default)

Sitting under this you had:

  • "iTunes Music" or "iTunes Media" - folder (depending on how old your library is) where your various media files were kept
  • "iTunes Music Library.xml" - the old library index file
  • "iTunes Library.itl" - the new library index file

If you have set iTunes to manage your library then all your media files will be sitting under this directory structure, including: Music, Movies, TV & Podcasts

This was nice as you could move the library by just copying/moving the entire directory structure and all was well.

This is no longer the case with Catalina.


Catalina Music, TV, Podcast

With macOS Catalina what was once handled by one big iTunes application is now handled by three big applications and Books ;-) .

  • Music - for your music content and music videos
  • TV - for your Movies and TV content
  • Podcasts - for your podcasts
  • Books - for your books which was moved out of iTunes some time ago

Each of these has its own media storage location, but depending on how you started, the actual media content could still be held within your prior iTunes Library (above).

The default locations for media in this new world are:

  • ~/Music/Music - for you music files
  • ~/Movies/TV - for your movie and tv files
  • ~/Library/Group Containers/243LU875E5.groups.com.apple.podcasts/Library/Cache - podcasts are now held in special container and not directly manageable
  • ~/Library/Containers/com.apple.BKAgentService/Data/Documents/iBooks/Books - iBooks were moved into a special container sometime ago, again to some surprise and have a habit of disappearing ...

The details for the various apps and storage locations are described in turn.

NOTE: These media file locations are also valid with "Big Sur"


Music

  • ~/Music/Music

Sitting within this you will have:

  • Media - folder where media content files are kept
  • "Music Library.musiclibrary" - the new music library catalog file (replacement for "iTunes Library.itl", but this is really a directory which contains a further set of files including Preferences.plist file)

NOTE: the plist file is a binary files, but you can see contents using the plutil command.

If you had an existing iTunes library then on starting the new Music app, you will be prompted to migrate your library Music. This will load the catalog and set the media location to the existing iTunes media location.

If you want re-consolidate your music and music videos under the new Music library then:

  1. Ensure you have a Media directory in ~/Music/Music (i.e. ~/Music/Music/Media)
  2. Change Media location via: Music - Preferences - Files to: /Users/<YOU>/Music/Music/Media .  Then select - "Keep Music folder organised" and "Copy files to Music Media folder when adding to library". You will get prompted to copy files as per preferences, so select "Yes".
  3. Now in Music - select: "File - Library - Organise Library..." and when prompted select "Yes". It is only now that it will copy all the content from you existing iTunes media folder to the new location.

NOTE: There is a signficant bug in new Music App when it comes to keeping your iTunes cover art.  There are many reports of intital migration resulting in lost cover art, and if you have very large iTunes libray then the cover art migration process can take more than a day to complete. I have found that even it you do manage to get the inital migration to Music to process the cover art successfully, if you move your library to different a machine then the cover art will get lost again and fixing is either a programming exercise or a laborious manual process.

See "Music Cover Art" below for more information.


Music Cover Art

Music cover art is one of the problem areas in moving from iTuness to Music. In iTunes cover art is managed via a special catalog within the iTunes media library. There are a number of different levels of cover art that iTunes and Music manage:

  • Indivdiual Media File - such as .mp4 or apple .m4a / .m4p variations. These can have cover art embedded into then using "meta tags"
  • Album - this is a collection of Individual Media Files within a directory/folder. Unlike an individual media files the director/folder does have directly embedded graphics, so instead the cover art graphic that is displayed must be managed as part of the overall library catalog. In the case of iTunes this cover art catalog/cache was held within the iTunes media directory. In Music the catalog is stored in seperate & fixed location.
  • Artist - these are the small icon graphics that are displayed in middle panel if you view your library by Artist. Many moons ago these used to be based on Album cover art. Now they are created automatically by iTunes or Music app and there does not appear to be a way to manually populate this data.

In Music the cover art directory appears to be maintained seperately in:

  • ~/Library/Containers/com.apple.APMArtworkAgent/Data/Documents

This container based catalog is obviously not in the same directory tree as ~/Music/Music .

The consequence of this is that if you move your Music directory to another machine, then you will be leaving behind the cover art catalog.

Apple answer to this problem is that any moving of media data from one Mac to another should be done via the Migration Assistant, which is aware of all the various files and locations.

NOTE: Big Sur appears to have address some of the cover art bugs. See my Big Sur update.


TV

  • ~/Movies/TV

Sitting within this you will have:

  • Media - folder where media content files are kept
  • "TV Library.tvlibrary" - the TV/movie library catalog (again like Music this is a directory which contains the various library catalog files)

The migration from iTunes to Catalina TV is equivalent to that for Music. The migration to TV library occurs when you first run TV app. This generates a new catalog and media files will be left in iTunes folder.

If you want to consolidate into new ~/Movies/TV directory then you will need to follow simillar step to Music above:

  1. Ensure you have Media directory in ~/Movies/TV (ie ~/Movies/TV/Media)
  2. Change Media location via: TV - Preferences - Files to: /Users/<YOU>/Movies/TV/Media . Select - "Keep Media folder organised" and "Copy files to Media folder when adding to library". You will get prompted to copy files as per preferences, select "Yes".
  3. Now in TV - select: "File - Library - Organise Library..." and when prompted select "Yes". It is only now that it will copy all the content from you existing iTunes media folder.

NOTE: The Movie / TV content migration seems to work and be less problematic than music one. One reason is that there is no Cover Art. A problem I have seen is that if you have downloaded movies from the iTunes Store, then these now appear twice in your Movie library, one for the downloaded copy and a second one for the iTunes store cloud version. If you delete the downloaded version from your library and then re-download the file, this fixes the problem. If you have a large number of Movies then this will result in a lot of very large downloads.


Podcasts

Be aware that the Podcasts app, will want to automatically delete played podcasts and if you have old podcast that are no longer available then this will result in lost podcasts. So ensure you change your Preferences to stop auto deletion of played podcasts.

I have sucessfully moved Podcasts from one machine to another by copying the entire directory tree and contents:

~/Library/Group Containers/243LU875E5.groups.com.apple.podcasts/Library/Cache

Why bother and some good things & bad things

All this moving media content around is a nuisance, so why bother. The reason is that media files take up lot of storage space and many people move them to external storage for both more storage, but also to provide greater data security. Having a large media store on a single disk has high risk of failure, in fact it is guaranteed to fail eventually.

With iTunes this was pretty easy to do as you could simply move/copy the entire iTunes directory to an alternate location and then restart iTunes holding the "Option" key and select the new location.

When you have the catalog and media content in different directories and music and music and movies managed seperately this is not possible. So the easiest way is to accept the Catalina change and move to two seperate consolidated directories.

Having seperate library for Music and Movies means you have some additional flexibility in the files location.

I have also found that when consolidating under the new directories that the new APFS file system must be using some type of hard linking as my 700GB existing media library, did not grow to double the size on consolidation.

Once I had consolidated my content into each of the seperate directories, Movie and Podcasts appear to be readily movable, but music is problematic due Cover art bugs.  On consolidating to new location I was able to remove the old iTunes directory, to help recover disk space.


Driven by necessity

This blog posting was driven by desperation, as recently our family media Mac mini running Catalina crashed and I had to go to some substantial lengths to get back all the media content on it.

The recovery process meant peeling off the details of changes that have occured to iTunes and its storage solution. The documentation for Catalina was very limited and less detailed than what was previously available on iTunes.

To validate and test this I have used a combination of repaired Mac, a KVM virtual machine based on Time Machine backup of dead Mac and a MacBook Pro laptop, so process of recovery of Catalina based media required quite a lot time, 3 Macs and lots of storage to test various alternate recovery techniques.


References & Links:

Reading and Modifying OS X plists - very old blog on plists tools

Move or Manage the Music, Apple TV and Podcasts Libraries - Rocket Yard (MacSales) partial information on how to manage Catalina media libraries

What happened to iTunes ? - Apple's answers to the surprise they gave us ...

Big Sur - does this change things, fix things or it is the same. I have done some initial testing and documented finding in my "Big Sur" update


Low Res Image (based on Arcade Fire - Funeral) - via SoundCloud - Out of Tune