Add support for filtering on instrument parts

README.md

@@ -109,7 +109,7 @@ Once a database has been built, you can start searching for downloading songs.
 
 To search for songs, use the `search` command. This command takes `--filter` arguments in order to show what
 song(s) would be downloaded by a given filter, without actually triggering the download. Once you have a valid
-filter from a search, you can use it to download.
+filter from a search, you can use it to `download` precisely the song(s) you want.
 
 To download songs, use the `download` command. See the following sections for more details on the specifics of
 the filters and output formatting of the `download` command.
@@ -124,9 +124,17 @@ not overwrite it and will simply skip downloading the file.
 ### Filtering
 
 Filtering out the songs in the database is a key part of this tool. You might want to be able to grab only select
-genres, artists, authors, etc. to make your custom song packs.
+genres, artists, authors, etc. to make your custom song packs, or songs with particular instruments.
 
-`c3dbdl` is able to filter by several key categories:
+If multiple filters, of either type, are specified, they are treated as a logical AND, i.e. all the listed
+filters, both information and instrument, must apply to a given song for it to be matched.
+
+Filtering is always done during the search/download stage; the JSON database will always contain all possible
+entries from the C3DB.
+
+#### Information Filters
+
+`c3dbdl` is able to filter songs by their general information in several key categories:
 
 * `genre`: The genre of the song.
 * `artist`: The artist of the song.
@@ -135,35 +143,58 @@ genres, artists, authors, etc. to make your custom song packs.
 * `year`: The year of the album/song.
 * `author`: The author of the file on C3DB.
 
-Note that we *cannot* filter - mostly for parsing difficulty reasons - by intrument type or difficulty, by song
-length, or by any other information not mentioned above.
+To use information filters, append one or more `--filter` options to your `c3dbdl search` or `download` command. An
+information filter option begins with the literal `--filter`, followed by the field (e.g. `genre` or `artist`), then
+finally the text value to filter on, for instance `Rock` or `Santana` or `2012`. The text must be quoted if it
+contains any whitespace.
 
-Filtering is always done during the search/download stage; the JSON database will always contain all possible entries.
+Information filter values are fuzzy. They are case insensitive, and use the `in` construct. So, for example, the
+filter string `--filter song "edmund fitzgerald"` would match the song title "The Wreck of the Edmund Fitzgerald".
 
-To use filters, append one or more `--filter` options to your `c3dbdl download` or `search` command. A filter option
-begins with the literal `--filter`, followed by the category (e.g. `genre` or `artist`), then finally the text to
-filter on, for instance `Rock` or `Santana` or `2012`. The text must be quoted if it contains whitespace.
-
-If more that one filter is specified, they are treated as a logical AND, i.e. all the listed filters must apply to
-a given song for it to be downloaded in that run.
-
-Filter values are fuzzy. They are case insensitive, and use the `in` construct. So, for example, the filter string
-`--filter song "edmund fitzgerald"` would match the song title "The Wreck of the Edmund Fitzgerald".
-
-Filters allow very specific download selections to be run. For example, let's look for all songs by Rush
-from the album Vapor Trails (the remixed version) authored by ejthedj:
+For example, to find all songs by Rush from the album Vapor Trails (the remixed version) authored by ejthedj:
 
 ```
-c3dbdl download --filter artist Rush --filter album "Vapor Trails [Remixed]" --author ejthedj
+c3dbdl search --filter artist Rush --filter album "Vapor Trails [Remixed]" --filter author ejthedj
 Found 19563 songs from JSON database file 'Downloads/c3db.json'
-Downloading 1 song files...
-> Downloading song "Rush - Sweet Miracle" by ejthedj...
-Downloading file "Rock Band 3 Xbox 360" from https://dl.c3universe.com/s/ejthedj/sweetMiracle...
-Successfully downloaded to ../Prog/ejthedj/Rush/Vapor Trails [Remixed]/Sweet Miracle [2002].sweetMiracle
+Found 1 matching songs:
+
+> Song: "Rush - Sweet Miracle" from "Vapor Trails [Remixed] (2002)" by ejthedj
+  Instruments: guitar [2], bass [3], drums [4], vocals [4], keys [None]
+    Available downloads:
+        * Rock Band 3 Xbox 360
 ```
 
-In this case, one song matched and was downloaded. Feel free to experiment with the various filters to find
-exactly what you're looking for.
+In this case, one song matched; applying the same filter to a `download` would thus download only the single song.
+
+#### Instrument Filters
+
+In addition to the information filters, `c3dbdl` can also filter by available instrument parts. There are 5 valid
+instruments that can be filtered on:
+
+* `guitar`
+* `bass`
+* `drums`
+* `vocals`
+* `keys`
+
+To use instrument filters, append one or more `--instrument-filter` options to your `c3dbdl search` or `download`
+command. An instrument filter option begins with the literal `--instrument-filter`, followed by the instrument
+you wish to filter on.
+
+If a part contains the instrument at any difficulty (from 0-6), it will match the filter; if the instrument part
+is missing, it will not match.
+
+You can also invert the match by adding `no-` to the instrument name. So `--instrument-filter no-keys` would
+only match songs *without* a keys part.
+
+For example, to find all songs by Rush which have a keys part:
+
+```
+
+```
+
+If this case, X songs matched (only one shown for simplicity); applying the same filter to a `download` would
+thus download all X songs.
 
 ### Output Format