Ausführliche Referenz

Diese englische Referenz bewahrt die ausführlichen Erläuterungen aus der bisherigen Anleitung. Beispiele und Hinweise zu älteren Android-Versionen stammen aus der damaligen Version. Für die aktuelle Einrichtung beginne mit den anderen Hilfekapiteln.

Preferences Explained

Run After Media Scan

Whenever the system scans for media files and broadcasts that it is finished, Gazania will process the playlists again. This usually happens when the SD card is mounted. As the audio IDs will very likely have changed, it is necessary to recreate all playlists. Therefore it is recommended to enable this setting.

Matching Precision

By default tracks are matched by their file path. This ensures unique and consistent references to all tracks and makes sure that the tracks in the playlists are exactly the same ones as the ones in iTunes. This only works though if you have all your music within the iTunes folder and synced as such to your device. This also allows Gazania to scan for missing tracks and orphaned media store references. Thus the playlists always stay fully functional and in sync with the iTunes playlists.

But Gazania can also be used to create playlists with audio spread across the device. E.g. you have multiple audio sources and folders. You could still create playlists from iTunes by setting Matching Precision to one of the other options. Gazania will then create the playlists with whatever audio files it finds on the device that match according to this setting.

Scan Missing Tracks

When audio files are added to the device via syncing apps they may not directly be added to the android media store. Therefore they cannot be found when Gazania processes the playlists. This will result in missing files in the playlists. With this option enabled Gazania will check if there are files that are on the device but not yet registered in the media system. If so it will ask the system to scan them and afterwards process the playlists. If there are a lot of new and valid (they are in the iTunes library xml and on the device) files that are not yet in the media store, this may take a while.

Note: If your library has changed a lot or if you have synced it the first time and if it is on a removable storage and you experience inconsistencies in your music player, then it is recommended to eject and mount the storage again to initiate a system scan of all media on it. This will fully refresh and cleanup the paths stored in the android media store.

Cleanup Orphan Tracks

When you rename a track in an organised iTunes library it will rename the file. So the next time you sync your library the old file will be deleted and a new created. In this case or when you delete a track from disk, the deleted file will be still in your android media store. The Cleanup Orphan Tracks option will make sure that any track in the android media store, that is registered within the iTunes folder, and that does not exist on disk anymore, will be removed from the android media store.

Together with Scan Missing Tracks this makes sure that you always have clean and refreshed media store and thus all playlists work well.

If you see the message “Checking for x potential orphans.” and no actual orphans are found, it means that there are x files in your (synced) iTunes folder that are not registered within iTunes. You may have to make a clean sync or have a look at Settings in iTunes and possibly add your whole iTunes folder again to iTunes.

Note: Gazania will never delete any of the actual audio files.

Split Smart Playlists by Tag

To split playlists you need to tag them with an asterix *, followed by one of the following:

Tag	Meaning	Details
d	decade	create a playlist for every available decade
dx	x decades	decade with a limit of x decades
y	year	this will potentially create a lot of playlists!
yx	x years	create maximum x years back
g	grouping	create a playlists for each iTunes Grouping value
r	rating	create a playlists for each Rating
rx	x ratings	limit to top x ratings

A + can be added to dx or yx to add all older into the last bucket. See examples below.

In grouping multiple comma separated values are supported. E.g. “Indie, Folk, Acoustic”.

The tag can by anywhere within the playlist name. And it will be replaced by a description of the split value. See examples below.

If another asterix is added (**), it will keep the original playlist too.

Sorting can be applied too, see below.

Examples:

“Fav Rock *d3+:r” will create
- “Fav Rock d1:2010s:r”
- “Fav Rock d2:2000s:r”
- “Fav Rock d3:<2000:r”

”**y2 Bluegrass” will create:
- “Bluegrass”
- “y1:2017 Bluegrass”
- “y2:2016 Bluegrass”

“Indie **d2gr2 (pc)” will create:
- “Indie (pc)”
- “Indie d1:2010s (pc)”
- “Indie d2:2000s (pc)”
- “Indie g:Grouping 1 (pc)”
- “Indie g:Grouping 2 (pc)”
- “Indie g:Grouping 3 (pc)”
- “Indie r1:5* (pc)”
- “Indie r2:4* (pc)”

Sort Smart Playlists by Tag

iTunes does not save the order of smart playlists in a readable format. Therefore if you want your playlist in the way you ordered it, e.g. by date added, you need to select “Copy to Play Order” to have this order reflected on your device. This can be annoying as it can not be done automatically. Gazania offers you the option to add tags to your playlist names so that your tracks get ordered on your device.

Currently supported sort columns:

Tag	iTunes Column	Details
da	Date Added
lp	Last Played
pc	Plays	Play Count
r	Rating	Sort by number of stars
y	Year
ya	Year	Within a Year sort by Artist and Album
ar	Artist	Within an Artist sort by Album
al	Album
t	Name	Track Title

The tag has to be at the end of the playlist name. And a + or - can be added to indicate the sort direction. Default is descending.

The full regular expression pattern for tags is:

[ %#$:\[\(]([a-zA-Z]{1,2})([-+]?)[\]\)]?$

Explained:

Start with whitespace or one of %#$:([
Declare field column, one of da,lp,pc,r,y,ya,ar,al,t
Declare sort direction: - (can be omitted) or +
Optionally end with one of )]

Examples:

Best New 5* da
Indie & Folk #pc+
Recently Played (lp-)
Most Played [pc]
Recently Added :DA
Love Those (r)
Jazz by Age (y)

If you add one of those to your playlist name, Gazania will order the playlist accordingly. E.g. name a playlist: “5 Star Indie Music pc-” to get this playlist ordered by play count. The most played tracks will come first.

Sort Smart Playlists

Select an iTunes column to sort all smart playlists that have not been sorted by a tag. There is a preset of option to choose from.

Sort Smart Playlists Reverse Order

This will create smart playlists in reverse order. This can be helpful as iTunes adds newly added tracks to the end of the list. This option only applies to playlists that did not get sorted through one of the other sorting options.

Rename Duplicate Playlists

iTunes allows multiple playlists with the same name. But Gazania does not at the moment. If this setting is disabled Gazania will overwrite existing playlists with the same name. Thus the last wins. If renaming is enabled though, it will check for duplicates and rename subsequent playlists by adding a counter in brackets at the end. E.g. Classical Music, Classical Music (2) and Classical Music (3).

Playlist Creation Process

Gazania checks if the modification date of the iTunes Music Library.xml has changed. If not it finishes.
If it has been modified Gazania parses all the tracks and playlists from the xml file.
It then checks for every playlist if it has changed compared to the previous version of the playlist from the xml file.
It then checks for every playlist if it has changed compared to the version of the playlist in the media store.
If the playlist has not changed (same tracks in the same order) it skips it and marks it as exists.
If the playlist has changed it checks if the playlist already exists on the device. If it exists but has changed, it updates that playlist by first removing all tracks and then adding them fresh. If it does not exist it creates a new playlist.
If the playlist is empty or it cannot find any matching tracks on the device then it skips the playlist and marks it as skipped.
If the playlist cannot be created it gets marked as failed. E.g. if a playlist name clashes with a protected playlists.
In the end it deletes all playlists that it had created in a previous run but that are now either empty or do not exist anymore.

Known Limitations

Very large library files may take a while to parse
With Android 4.4 (KitKat) there are some color and layout issues.

Efficiency

For around 70GB music, including around 7000 tracks and 100 playlists, Gazania usually needs between 10 and 30 seconds to process multiple playlist changes.

Depending if smart playlist sorting is enabled it can take several seconds longer. If missing tracks scanning is enabled it can take much longer if there are a lot of tracks not in the android media store yet.

The background service only starts processing when the iTunes Music Library.xml has been modified. Processing itself is fast. Therefore the power consumption of Gazania is low. Memory consumption depends hugely on the size of the iTunes library but should be no issue on most devices.

FAQ

Q: My playlists are not up to date anymore and Gazania is not updating them. How can I tell it to recreate all playlists?
A: Launch Gazania and delete the playlists before either manually starting a process or letting the service recreate it at the next run.
Q: Gazania repeatedly scans files even though nothing has changed. What is wrong?
A: It is likely that those files fail to be added to the android media store due to having a wrong file format or content. Make sure the way you sync your files does not corrupt them.