Composition-At-Once (CAO) FAQ

1.0 Are there any limits on what CAO can be run against?

Yes. CAO will only work on FLAC audio files.

It can also only merge a maximum of 99 FLAC files, because cue sheets are only allowed to list that many number of 'index marks' (virtual tracks). If you run CAO in a folder full of more than that number, it will warn you and quit. You options at that point really come down to physically splitting your FLACs into smaller collections (and, in consequence, re-tagging them a little) before running CAO against each of the new,. smaller collections.

2.0 Is CAO truly non-destructive?

Almost! If you run cao against a bunch of FLACs, and then cao --asunder against the resulting super-FLAC, you will get back to a place that is almost exactly where you started from... but not quite!

Part of the merging and splitting process involves re-encoding your FLACs, and CAO may use a different compression level than the original files were using -therefore, the end-result file sizes may be slightly different from what you started with.

Additionally, for technical reasons, if your original files contained two or three dots and/or single quotes, those are altered. The two/three dots are turned into proper ellipses (…) in both the physical file name and the TITLE metadata tag. An ellipsis looks like three dots but is actually a single character that happens to have the form of three dots -and, crucially, it doesn't break the ffmpeg audio conversion utility in the way that two or three consecutive but separate full-stop characters do. The single quotes are stripped from the physical file name (but not the metadata). This means that if you do a subsequent 'asunder' split of the super-FLAC resulting after these changes, the files will not be 100% identically named or tagged to those that 'went in' to the super-FLAC in the first place.

And finally, if you merged tracks 77, 78 and 79 into a super-FLAC, and then asundered the super-FLAC back to individual tracks, they will now be numbered tracks 1, 2 and 3.

So in these three respects, CAO does alter your music permanently. However, other than in these three respects, CAO is completely reversible and does not damage your music signal at all. It also preserves all album art and metadata tags (except for the loss of apostrophes and ellipses, of course).

3.0 CAO has scrambled the order of my tracks!

This will only ever happen if your tracks are not correctly numbered in the first place. I'll give you an example:

Here, I have tracks from a CD collection of Monteverdi madrigals. Notice they start at track 76, with a song entitled Io, che nell'otio nacqui. That should therefore be the first track in a super-FLAC created from these files. But this is what we actually see after running CAO:

Here, we now have a song called Non partir, ritrosetta as the first playable track. So yes, CAO does appear to have scrambled the order of tracks -but that's because my file names began with two digit numbers and the list went on to three-digit numbers:

And can you see now that the first track originally numbered with three digits (i.e., source track number 100) is the same one that CAO has put first in the new super-FLAC?

It's because you think as a human and not as a computer that you don't see that the starting list of tracks was not properly sequentially numbered! They look sequential: 76, 77, 78 and so on. But to a computer confronted with a shift from 2-digit numbers to 3-digit ones, it will see the 2-digit ones as starting with a space, and spaces always sort last. That is, when confronted with 98, 99 and 100, the computer will sort them 100, 98, 99, because the 1 in the 3-digit number is being compared to 'nothing' in the other two 2-digit ones..

So CAO will scramble things if your track numbering is not spot-on and consistent before you start. That means consistently using 2-digit track numbers (with leading zeroes for the ones numbered less than 10); or -if your track numbers do go up to the hundreds- consistently using 3-digit track numbers, with the first 9 tracks being double-zero padded (so, 001, 002 and so on) and the tracks from 10 to 99 being single-zero padded (010, 011, 012 and so on). Hopefully, you don't have tracks running into the thousands (!), but if your did, you'd have to pad everything to be a consistent 4 digit number (so, 0001, 0002, 0003 and so on).

If your track numbers are consistent numbers of digits long, then CAO cannot scramble the order of your tracks.

4.0 CAO sometimes produces an empty 'super-FLAC' sized at 0 bytes and unplayable. What's wrong?

First of all, make sure you are using CAO Version 1.01 or later: code additions in that version should mean this doesn't happen any more, though unfortunately it cannot guarantee that it will never happen again. It seems that there's a bug (or feature: opinion is divided on the subject!) in ffmpeg, whereby only a certain amount of memory is allocated to dealing with graphics elements stored in audio files, and a large piece of album art will exhaust that memory. CAO has now bumped that memory amount up very substantially, but there can be no guarantee that a particularly large piece of album art will not exceed even the new allowance.

Therefore, the workaround is to use a graphical tag editor (such as Kid3) to export the album art from the source FLACs and them delete it from all the source FLACs. Run CAO at this point and it should run without a problem and create a playable super-FLAC. Use the graphical tag editor to then add back the album art you previously saved. An alternative is to re-tag the source FLACs (using Kid3 or even CCDT) with new artwork that is significantly small than the original (say, 500x500 rather than 4000x4000!). Either approach means you ask much less of the album art handling capabilities of ffmpeg, CAO's underlying merge engine.

5.0 Why do I see a message about "CAO is already running"?

Only one running instance of CAO is allowed at a time -for the simple reason that CAO keeps track of what it's doing by writing out to temporary files. A second instance of CAO would over-write those files and thus potentially scramble what the first one was doing.

It is possible, however, that a running instance of CAO crashed: that would leave the system thinking CAO is already running when it isn't. If you are absolutely certain that no 'real' instance of CAO is running in the background somewhere and that, therefore, the lock-out from running a fresh CAO instance is spurious, you can run CAO with the --removelock run-time switch. That simply means typing the command:

cao --removelock

Doing this will remove the lock file that prevents a second instance of CAO from being launched, and therefore you can re-run CAO normally thereafter. Be aware if you choose to remove the lock deliberately to permit more than one instance of CAO to run at a time, the results of each CAO run will at best be unpredictable and, at worst, will result in corrupt composition-at-once files. So, using the --removelock option is entirely at your own risk!

6.0 Can I get CAO to just delete the source FLACs automatically?

Yes, so long as you're running version 1.04 and above. If you launch CAO with the --autodelete run-time switch, then CAO will create the super-FLAC and then automatically delete the source FLACs for you. It's obviously quite a lethal option and is therefore not the default behaviour!  But once you are comfortable that CAO is doing what it's supposed to, then the autodelete switch means CAO is less interactive than before and thus a little more convenient to use.

cao --autodelete

...will do the deed. Without the switch, you will always be prompted to delete the source FLACs -which is your cue to check the super-FLAC that has been created and satisfy yourself that its cuesheet is correct, that it plays fine and so on. If you find over time that CAO works as you like, and you therefore get comfortable with the idea of auto-delete functionality, you can set up an alias in your .bashrc, making 'cao' equivalent to the 'cao --autodelete' command.

7.0 Can I just point CAO at my music collection and have it create super-FLACs automatically for all of it in one go?

Not really, no. It's not advisable to go around making those sorts of bulk-alteration to your music collection without being very careful and very aware of what's being done to it, so CAO is deliberately written to be run in a specific folder of music, one at a time.

But, of course, if you have run it that way 58 times and are happy with what it's doing and really do wish you could point it somewhere and let it do its thing automatically from that point on, then you can script the use of CAO. Here, for example, is a simple script that will do the deed:

shopt -s globstar

    for f in **/*.flac; do
      FOLDERNAME=$(dirname "$MUSICDIR/$f")
      cd "$FOLDERNAME"

      for g in *.flac; do
        COUNTFLACS=$(ls *.flac | wc -l)
        if [ $COUNTFLACS -ge 3 ] && [ $COUNTFLACS -lt 99 ]; then
          cao --autodelete    
exit 0

Save that -say, on your Desktop- as and make it executable (chmod +x $HOME/Desktop/ Now invoke the new script, passing it the root folder of your music collection. For example:

$HOME/Desktop/ /sourcedata/music/classical

Wrap the music directory in double-quotes if it contains spaces. Otherwise: when you submit that command, the script runs off to that directory, descends into every sub-folder (or sub-sub-sub-folder, and so on) and counts the number of FLAC files found. If it's between 3 and 99, it will invoke CAO on that sub-folder's FLACs and create a new super-FLAC for them, deleting the source.

I've specified a 'between 3 and 99', only because I think a work that consists of only 1 or 2 tracks isn't really worth converting into a super-FLAC. Works made up of 3 tracks will be, basically, every concerto you own -so that seems a reasonable starting point. You can't aggregate more than 99 tracks, because CAO won't let you: simply put, that's a hard limit imposed by the original designers of the cuesheet format, so CAO has to play by those rules. You could change the 3-to-99 rules to suit your own collection, though -remembering that 99 is a hard limit over which none of us have any control!