Skip to content

kluete/recover_itunes

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

51 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

About recover iTunes

This small Lua-based utility recovers meta-tag data from audio tracks that were legally purchased on the iTunes store. It will:

  • scan a directory of untagged M4A tracks, typically from the iPhone's /Purchases directory, mounted via libimobiledevice
  • fetch their meta-data from iTunes' SQLite database, located at /iTunes_Control/iTunes/MediaLibrary.sqlitedb
  • fetch any cover art from /iTunes_Control/iTunes/Artwork/Originals/
  • save a copy of each renamed track with its embedded meta-data

It was designed for Linux and tested on Debian.

Rationale

iTunes keeps track meta-data in its own separate database so audio files are not just devoid of any identifiable information, they'll have unhelpful filenames such as "-49907963407597370.m4a"

This program recovers the following meta-data:

  • title
  • artist
  • album
  • track number
  • cover art bitmap
  • modification/purchase date

It handles UTF-8 characters (including accents) and filters-out illegal characters in POSIX filenames

F.ex., Clementine will go from something like: before

To: after

Target Audience

This may be of interest to:

  • Linux desktop users who purchase music via their iOS device's iTunes store
  • want to enjoy those tracks on any platform they see fit (f.ex. I use my own music player on Debian/Xfce)
  • can't run iTunes on Linux or don't like running it on other platforms
  • like to mitigate iTunes' instability wrt library zaps
  • find audio fingerprinting lacking, especially for more underground artists

As well as anyone curious about iTunes' SQLite schema.

Requirements

  • Lua 5.3 because its 64-bit integers can handle SQLite indices as-is
  • either
    • the command-line sqlite3 binary
    • OR a native Lua SQLite dynamic library built for Lua 5.3
  • AtomicParsely to write MP4 meta-tags

On Debian you'd do something like

apt-get install lua5.3 sqlite3 atomicparsley

Usage

sqltunes.lua <in_dir> <itunes_db_dir> <out_dir>

Example

After having mounted your iPhone on Linux via libimobiledevice:

# retrieve mount point
myiosroot=$(mount -t fuse.gvfsd-fuse | cut -d ' ' -f3)"/afc:host="$(ideviceinfo -k UniqueDeviceID)
# run
lua5.3 sqltunes.lua $myiosroot/Purchases $myiosroot/iTunes_Control/iTunes "out_"$(date +'%F_%H-%M')

Technical details

  • this program is read-only -- no data whatsoever is written to the iPhone
  • it is theoretically possible to retrieve meta-data from tracks in the global iTunes library (i.e. outside the /Purchases directory) but this program isn't designed for it. In a large audio library you're likely to encounter multiple tracks with the same (short) filename, in different sub-directories, which this program doesn't currently handle. Not much point anyway since you likely already have them elsewhere with full meta-data
  • if you have several iOS devices (concurrently or at different times), make sure to process one device at a time and not to mix up their files; the same audio track will have different (source) filenames/checksums, i.e. looking up a track from device A with the database from device B will likely fail.
  • if you get a Lua error signaling failure to retrieve a track's tags, chances are the problem is with iTunes' library state, not this program. First check that you can see the track on your iPhone in iTunes' purchases playlist; redownload it from the iTunes store if you don't. Otherwise reboot the iPhone and try again ("science!")
  • reading files directly via FUSE's AFC protocol over USB can be slow. To speed it up, copy relevant iOS files to your HDD first, then process them locally
  • there's currently a hardcoded (hackish) 31-year timestamp offset for the purchase date, maybe because the Julian calendar starts on 19-December-1969
  • ffmpeg/avconv don't seem to correctly handle m4a cover art
  • a native Lua SQLite library is really only needed for development/debugging. For plain usage, CLI sqlite3 is suffficient

Fineprint & Cop-out

  • although a trigger-happy lawyer will no doubt find something to scream bloody murder about, there's no real hacking going on here. iTunes' database is stored in the vanilla, open-source SQLite format and retrieving a track's meta-data comes down to a single, albeit tortuous, SELECT statement (this cop-out kind of moot after publication in [Hackaday.com] (http://hackaday.com/2016/07/21/ever-buy-music-from-apple-use-linux-you-need-this-tool/))
  • do not try to write modified files back to iOS manually; at best iTunes will ignore them, at worst you'll corrupt the database
  • if your desktop audio player is iTunes anyway, stick to it
  • iTunes stores all sorts of data inside audio files, with some debate about standard-compliance; no attempt is made here to address those issues
  • use at your own risk
  • please share any fixes/improvement
  • enjoy!

About

rip meta-tags from iTunes database

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages