dam/README.md

# dam
### Digital Audio Manager 

&copy; 2017 Antoine Martin \<antoine.martin@protonmail.com\>, provided under GNU General Public License v3.0.

Utility used for deployment of music collection organized by CD images, delimited by CUE sheet files, 
tagged by JSON file based on MTAG specification and covered by JPG file.


## dam --help
Usage: dam [--help] [--info] [<options>] <command> </path/to/target> [<args>]

Options
   --git-dir=</path/to/git/dir>
      Defines path to git directory that contains the music collection. Defaults to current directory when not set.

Commands
   update
      Populates database present in target folder with new images.
   deploy
      Deploys tracks to target folder, with applies metadata and cover image
   exclude <condition> [<additional condition>]
      Exclude tracks based on conditions (see dam --help conditions for more information)
   include <condition> [<additional condition>]
      Include tracks based on conditions (see dam --help conditions for more information)

## dam --help condition
Conditions

Note
   Conditions are defined using the following format:
   <metadatafield>=<value>
   The metadta field can be anything that can be injected as metadta in a Vorbis tag.

Example
    You want to exclude everything from "GENRE" "Pop":
    dam exclude "GENRE=Pop"
    
    ...but want to keep Lady Gaga, just because
    dam include "ARTIST=Lady Gaga"

    ...but not THAT album
    dam exclude "ALBUM=THAT"

## A note on music library format
The music library (git directory) is organized by album images. When the audio is ripped from cd, the cuetools
image is kept as is. When the source is digital (i.e. Bandcamp), the album is conjoined into one .flac file to
be treated as if it was a CD image, with its own cue sheet, and accompanying files.

### Files
They are four mandatory files per image:
* a FLAC file (the image file compressed to FLAC)
* a CUE file (either generated from cuetools, or generated using import function from track files)
* a MTAG file (metadata set using the MTAG specification)
* a JPG file (480x480 resolution cover to be imported into the deployed FLAC files)
* (Optionally) a PNG file that contains a larger resolution version of the JPG cover file
* (Optionally ACCURIP and LOG file generated by cueripper.

### File name format
It is assumed that they are all named the same, only differentiated by their extension. The format used by
yours truly is the following:
SHA256-<ctdb id>-<sha256 sum of FLAC file>.<ext>

In the event that the source is not a CD, the ctdb id is then replaced with the source info. in my case, <FLAC>
means a lossless source and <MP3> means a lossy source. A few examples:

* The Alan Parsons Project's I Robot
SHA256-sGYFy0TxXWucFAm.WYiPeQCSuv8--edba73bda9a2dc829405f979956e6dbf748896b48f0604bee2a5249e9dfb7eb0.<ext>

* Antoine Corriveau's Cette chose qui cognait au creux de sa poitrine sans vouloir s'arreter
SHA256-FLAC--0f25f26caa8b321dfc8e84d068f7a1225d1c7893f66f225b8e04bb51bbaf56e9.<ext>

### Git annex
The music collection is handled using git annex, which is why this was done (more on this later). 
The version used is v6, which allows some files to be locked and serviced by git annex, and other files
to be serviced by git directory. In my case, I wanted the metadata to be services directly by git, and thus
the CUE file, MTAG file and JPG file are imported directly in the branch, while the FLAC file, PNg file are 
handled by git-annex as they are larger.

Thus, when one clones the music repository, the metadata is downloaded without the data, allowing the management
of a really large collection to be much easier. It is then as easy as doing "git annex get <file>.flac to download
the image from the server. If a change is made (i.e., an image gets added, or metadata changed), the changes can get
propagated. 

# Why?
One thing I wanted to do was use git-annex to manage my large music collection (1194 albums, 11914 tracks, ~400 GB).
What really sucks with metadata is how its embeded in the audio file. Thus, when a small metadata change occurs, it
was necessary to reupload (and redownload) the whole FLAC file. Not ideal. 

Thus, came the idea of using CUE sheet files as a way to decouple metadata from data. Unfortunately, the CUE sheet
specification is very limited. I have too many classical discs to accept such a thing. Thus, I went searching and 
found the MTAG specification that basically sets the metadata using a JSON text file. Unfortunately, nothing supports 
this specification except foobar2000. 

No matter, when nothing supports it, just code a program that splits the image files in seperate tracks using the 
cue sheet, then apply the metadata by parsing the MTAG file, then copy the file to a target directory (i.e DAP), 
then keep track of where everything is using a database file. 

In the event of a small metadata change, the program is smart enough to apply the new metadata without having to
retransfer the same data.

# Why bash?
Because I was lazy and didn't feel like teaching myself Python. God knows I should've. Hell, I will probably port
this script to python as a way to get out of my comfort zone, and a way to have this be more portable. I would 
definitely enjoy an ncurse interface for this. Alas, for when life gives me more time to waste on my OCD and 
music collection.

Hope someone finds inspiration in my perfectionism..