A long-requested feature has been a way to decouple Amarok's collection scanning from its GUI. There are various use-cases for this. For one, it can actually help us with debugging, by allowing us to control the inputs into the scan parser. For another, many people have all of their music stored on a single machine, and would like to do the scanning locally where it's fast instead of on their e.g. laptop running Amarok, where it's over wireless and slow.
Yesterday and today (as of r933010) I put half of the solution into trunk. I say half, because full collection rescans are now supported in batch modes, but I am still working on the methodology for incremental scans (I have a few ideas, but have to sort out which is the most reasonable/doable/makes the most sense). Below, I'll explain how to do it. Keep in mind that this is designed to be (lightly) scripted, not done by hand...so it can be done by hand (which I did during testing) but it has some safeguards in place so that if you script it, and forget about it, Amarok still works normally. However, there are actually some interesting things you can do now if you script the scanner...
One important thing to note: the scanner requires various bits of Amarok code, mainly centering around the extra taglib plugins we support. So you're unlikely to have it work on a machine that doesn't have A2 installed, and certainly won't be able to compile it without the rest of the Amarok source, although you may be able to get it to work in a binary-only fashion with just kdelibs and taglib...YMMV.
So, here's the flow:
- Run amarokcollectionscanner with the -b or --batch option. Although this doesn't directly modify the output, it sets some internal flags (some for safety, some to enable other options). The output goes to stdout; save this output as amarokcollectionscanner_batchfullscan.xml (yes, it must be that specific filename). You'll probably want to use the -r flag too...check --help for more options.
- Cool feature: if your scan is of files that have a different mount point on the local machine than the machine that will be using the output, add the --rpath option and give it the mountpoint of the directory on the consuming machine. For instance, if on the local machine your music is at /opt/music, and this directory (music) is mounted as /mnt/music on the remote machine, run amarokcollectionscanner from /opt and use --batch --rpath /mnt/music.
- Cool feature: You can scan multiple directories and simply append the output to the end of the file from step #1. Yes, directly append, including the xml version/encoding header. Amarok's scan manager will detect and handle this. You can even scan directories that are not defined as collection directories in Amarok (these entries will work fine, but the next time you do a full rescan from within Amarok without using the saved output, they will be gone).
- Place the amarokcollectionscanner_batchfullscan.xml file in your Amarok data dir. Usually, this is ~/.kde4/share/apps/amarok.
- Trigger a full rescan from inside Amarok (in Settings->Collection). It should be super-fast. :-) Note that this step deletes the amarokcollectionscanner_batchfullscan.xml file. This is on purpose, so if you want to keep re-using it, you'll have to keep copying it over.
As you can see, it's designed for scripting, but it's not terribly complicated even to do by hand. I'll post more as I get incremental scanning working, and will at some point put a Wiki page up that has all of these instructions in a less transient form.
Continue reading "Amarok Power User Feature: Batch-mode collection scanning"
