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.