Add README

2020-03-06 17:40:50 -06:00 · 2020-03-06 17:40:50 -06:00 · 20e0e3a059
commit 20e0e3a059
parent 0bb342ffec
1 changed files with 90 additions and 0 deletions
--- a/README.md
+++ 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.