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:

To:

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!

kluete / recover_itunes