From 20e0e3a0595b52dd5595638e4cb28bb9916a1bae Mon Sep 17 00:00:00 2001
From: Salt <rehashedsalt@cock.li>
Date: Fri, 6 Mar 2020 17:40:50 -0600
Subject: [PATCH] Add README

---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2eb3d8e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# 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.
+
+## 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.