ModArchive

Modarchive is a decades old archive containing thousands of module files. It is maintained and operated by a team of volunteers, and is funded with donations. It contains a diversity of module file formats and music genres.

ModArchive tools

The ModArchive offers an application programming interface (API), for which the openmpt package offers several wrappers in R. For many of these functions you need an API key (see below)

If you know the module’s database ID, you can download it (without an API key) using

library(openmpt)

unreal <- modarchive_download(60395)
unreal
#> openmpt module 'UnreaL ][ / PM ' [Scream Tracker 3.00 (GUS)].

Using the module ID you can also obtain meta-information from ModArchive for that module.

if (modarchive_api() != "") {
  info <- modarchive_info(60395)
  info$genretext
}
#> Loading required namespace: httr2
#> Loading required namespace: xml2
#> [1] "Electronic - Techno"

If you don’t know the module ID, you can search the archive through different entry points:

• modarchive_search_mod(): search for texts in different fields and filter the results with specific criteria
• modarchive_search_genre(): browse modules for a specific genre and filter the results with specific criteria
• modarchive_search_hash(): search for a specific hash code
• modarchive_view_by(): create different views of lists of modules

ModArchive API key

In order to keep traffic to the ModArchive servers in fair bounds, an API key is needed to make use of the features offered by the ModArchive toolbox. These keys are handed out and maintained by the ModArchive crew. In order to apply for a key, you first need to register at the ModArchive Forums. Then follow the instructions provided in this topic on the forum.

Note that there are different access levels, where the access levels determine which features are available to you. If ModArchive features wrapped in the openmpt package don’t work, you might need a higher access level.

Most wrappers (like modarchive_search_mod()) have an argument named api. There you can pass your key directly as argument. You can also set it as an environmental variable: Sys.setenv(MODARCHIVE_API = "<your api key here>"). You can also set it as a session option: options(modarchive_api = "<your api key here>"). By setting it as either an option or an environmental variable, you don’t have to pass it as an argument with each call. It is automatically obtained with modarchive_api().

Each API key comes with a cap on the number of monthly requests you can make to the server. You can check how many requests you have and can make each month with your key with modarchive_requests(). Below you can how many requests where made with the key used for developing this package at the time this vignette was rendered (only if the machine rendering this vignette has registered an API key).

if (modarchive_api() != "")
  modarchive_requests()
#> $maximum
#> [1] 1000
#> 
#> $current
#> [1] 662

If you want to extract large quantities of files it is advised to use (torrent files)[http://modarchive.textfiles.com/], which distributes the traffic across multiple hosts.

Other online resources

Currently, the only alternative for ModArchive, supported by the openmpt package is modland. It offers less features compared to ModArchive, yet it has a large collection of over 400,000 files and counting. You can use modland_search() and modland_download() to search and download files on and from modland, respectively. The good news here is that you don’t need an API key.