badwitch/README.md

# badwitch

Bad Witch is a declarative music management system (and later, a streaming music player) based around Youtube-DL.

It's the natural evolution of **ptgdp**

## Syntax

The library is stored in a flat JSON file with a pretty simple syntax:

```json
{
	"Album Name": {
		"meta": {
			"genre": "Rock",
			"publisher": "Foobar Records",
			"release_date": "2020-03-06"
		},
		"Song Title": {
			"track": 1,
			"artist": "Salt",
			"source": "https://youtube-dl.parseable.link.to/song"
		}
	}
}
```

The entire "meta" entry for the album is optional, but recommended.

Some tags are automatically inferred. For example, the `album_artist` tag will be set to the artist of the album's songs OR "Various Artists" if there are several.

## Example

Here's an example library for, fittingly enough, Nine Inch Nails' 'Bad Witch':

```json
{
	"Bad Witch": {
		"meta": {
			"genre": "Industrial",
			"publisher": "The Null Corporation",
			"release_date": "2018-06-22"
		},
		"Shit Mirror": {
			"track": 1,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=yeqjz5mXrLQ"
		},
		"Ahead of Ourselves": {
			"track": 2,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=4Ab1O-i4ep4"
		},
		"Play the Goddamned Part": {
			"track": 3,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=85UgvBkMfr8"
		},
		"God Break Down the Door": {
			"track": 4,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=eeJ_DzRJUI4"
		},
		"I'm Not From This World": {
			"track": 5,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=9fjbcSUSt9w"
		},
		"Over and Out": {
			"track": 6,
			"artist": "Nine Inch Nails",
			"source": "https://www.youtube.com/watch?v=h-XlN3N2fis"
		}
	}
}
```

## Usage

The tool has flags to change the location of the lib.json file (defaults to `${XDG_DATA_HOME:~/.local/share}/badwitch/lib.json`) and increase verbosity. After that, it takes a subcommand:

* `list`: List entire contents of library. Good for ensuring library integrity.

* `download`: Downloads *and retags* all songs.

* `edit`: Starts an interactive prompt to add/edit albums and songs. It's pretty shitty, but it works and stops you from having to write a shitton of JSON.

* `playlist`: Starts an interactive prompt to import a playlist. It's less shitty and uses YouTube's built-in music tags where possible.

## Limitations

Currently it only supports URLs that youtube-dl can handle. This does, however, mean that you can give it a few cool things like SoundCloud links (or smut, I guess). However, if song files exist that match the nomenclature you laid out in the library file, it'll skip downloading them.