joshuaboniface/c3dbdl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add support for filtering on instrument parts

Browse Source
This commit is contained in:
Joshua Boniface
2023-04-07 05:22:57 -04:00
parent cb1a5c5d58
commit 61b4d0e429
2 changed files with 282 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@ -105,28 +105,37 @@ guaranteed to be smaller than the total number listed on the C3DB website.
## Searching & Downloading
Once a database has been built, you can start searching for downloading songs.
Once a database has been built, you can start searching for and 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.
song(s) would be downloaded by a given filter, along with their basic information, without actually triggering
a download. Once you have a valid 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.
See the following sections for more details on the specifics of the filters and output formatting of the
`search` and `download` commands.
By default, when downloading a given song, all possible download links (`dl_links`) will be downloaded; this
can be limited by using the `-i`/`--download-id` and `-d`/`--download-descr` options to pick and choose specific
files.
files. A specific example usecase would be to specify `--download-descr 360` to only download Xbox 360 RBCONs.
Once a song has been downloaded, assuming that the file structure doesn't change, subsequent `download` runs will
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.
Filtering out the songs in the database is a key part of this tool. You might want to be able to grab only songs
with certain genres, artists, instruments, etc. or by certain authors, to make your custom song packs.
`c3dbdl` is able to filter by several key categories:
If multiple filters are specified, they are treated as a logical AND, i.e. *all* of the give filters must apply
to a 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 +144,68 @@ 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 `--filter instrument <instrument>` options to your `c3dbdl search` or
`download` command. An instrument filter option begins with the literal `--filter instrument`, 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 `--filter instrument no-keys` would
only match songs *without* a keys part.
For example, to find all songs by Rush which have a keys part but no vocal part:
```
c3dbdl search --filter artist Rush --filter instrument keys --filter instrument no-vocals
Found 19562 songs from JSON database file 'Downloads/c3db.json'
Found 1 matching songs:
> Song: "Rush - La Villa Strangiato" from "Hemispheres (1978)" by DoNotPassGo
Instruments: guitar [6], bass [5], drums [6], vocals [None], keys [1]
Available downloads:
* Rock Band 3 Xbox 360
* Rock Band 3 Wii
* Rock Band 3 PS3
* Phase Shift
* Rock Band 3 Xbox 360 (Alternate Version)
```
In this case, one song matched; applying the same filter to a `download` would thus download only the single song.
### Output Format