Python API for vgmusic.com.
Project description
vgmusic.py
(unofficial) Python API for VGMusic. This project is in no way affiliated with or sponsered by Mike Newman or any of the staff at VGMusic.
Usage
Thoughout these examples, we will be using the API
object as the api:
import vgmusic
api = vgmusic.API()
It is recommended to close it once you are done:
# do something here...
api.close()
The best way is to use a context manager, a.k.a with
statement:
with vgmusic.API() as api:
# do something here
Note that the API is lazy: It will only retrieve data for a console/system the first time it is queried for it.
To override this behaviour, use force_cache
(see Module Documentation).
API Specification
// Any keys starting with '$' are variable.
{
// The system's name
"$system_name": {
// The system's url, i.e https://www.vgmusic.com/music/console/sony/ps4/
"url": ...,
// The section's name, i.e Sony
"section": ...,
// All the titles available for this system
"titles": {
// The game's name.
"$game_name": [
// The direct url to the song's MIDI file
"song_url": ...,
// The song's title
"song_title": ...,
// The song's file size, in bytes (as an int)
"file_size": ...,
// Who sequenced the midi
"sequenced_by": ...,
// url to comments
"comments_url": ...,
]
},
// When the system's page was last updated (as a Unix timestamp as int)
"last_updated": ...,
// Used to track page revisions
"_etag": ...,
// Version of the VGMusic indexer.
"indexer_version": ...
}
}
Backends
The API has two backends: dictionary-like (access from Python code) and a REST-based web interface (through Flask, from elsewhere) (WIP). You can also use it from the command-line.
Dictionary/Key
To query songs, you have to provide the name of the system/catagory and the game title:
songs = api["Sony PlayStation 4"]["titles"]["Persona 5"]
You can manipulate the API using standard dictionary methods:
# list all titles for a system
titles = list(api["Nintendo Switch"].keys()) # ['Sonic Mania'], as of 5/1/2021
# count how many songs in total
total = sum(len(songs) for songs in api["Nintendo Switch"]["titles"].values()) # 12, as of 5/1/2021
Anything you can do with a dictionary, it's basically possible with this API.
Search using regex:
(search_by_regex()
uses re.search()
.)
# Find all songs where system name has "Nintendo", game name has "Mario", and song name is any.
songs = api.search_by_regex("Nintendo", "Mario", "")
To use another key in song_info for the last regex, use song_info_key
:
# Find all songs authored by 'some_name'
songs = api.search_by_regex("", "", "^some_name$", song_info_key="sequenced_by")
For the keys that can be used, see API Specification.
More fine-grained search is also possible using search()
, supplied with a function:
def search_func(system, game, song):
if "Persona" in game:
return True
songs = api.search(search_func)
CLI
Install the CLI first:
$ pip install vgmusic[cli]
And then run with
$ vgmusic
On first run, it might take a while to initally cache all the systems. Maybe grab a cup of tea or two.
Once parsing is done, it will download all the MIDI files by default.
Any MIDI files already downloaded will be skipped. To force re-downloading all (not recommended), use the -f/--force
flag:
$ vgmusic -f
To fliter out songs using regex, use the -s/--search
option:
$ vgmusic -s "Sony PlayStation \d::Persona \d::.*"
This downloads all songs from the system Sony PlayStation \d
and the game Persona \d
which has any name.
-s/--search
maps directly to API.search_by_regex()
.
Help is always useful:
$ vgmusic --help
REST/fastapi
NOTE: This is WIP, it has not been finished yet. Make sure you have installed the REST extension:
$ pip install vgmusic[REST]
and then start the server with
$ python3 -m vgmusic.rest
Right now, there are two endpoints:
GET /systems
(array): all available systemsGET /system/{system}
(object): info for a systemGET /search?query=...&song_info_key=...
(array): songs matching the query (seeAPI.search_by_regex()
)
The data returned is in this format:
{
// the response data
"data": ...,
}
License
MIT.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for vgmusic-0.1.2b0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ce660a5e16499aee8bfebaa0a4b6d3228896c03f52cea74fc590a1e1d0823b2b |
|
MD5 | 7b141e9a18860424fc381f10e296afb4 |
|
BLAKE2b-256 | f2b22782c761ac42b5f95bbe67fe272f479610b4d9f781ace03c4a84544f0451 |