Skip to content
recover meta-tags from iTunes
Lua
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc
.gitignore
LICENSE_1_0.txt
README.md
lua_shell.lua
nativesqlite.lua
sqltunes.lua

README.md

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!
You can’t perform that action at this time.