Mantis Music

Docs

A Mantis site is an artist's own website, made only of ordinary files. Alongside the pages people see, it publishes open formats, so apps, players, directories, search engines and the fediverse can all read the same music. Everything here is free to use and to build on.

The files · Specs · Schemas · Conventions · Hosting · For readers · Changelog

What every Mantis site publishes

Each file sits at a fixed place on the artist's site. Start from mantis.json: it says where everything else is. The examples are live, from mantisaudiogram.music.

FileWhat it isStandardExample
mantis.jsonThe site's manifest: who it is, where everything is, and whether directories may list itMantis site formatmantis.json
catalogue.jsonEvery song and release: audio, covers, lyrics with timings, credits, waveform, coloursschema.org JSON-LD, with Mantis extrascatalogue.json
theme.jsonHow the site looks: colours, fonts, layout, visualiserMantis themetheme.json
chorus.jsonThe same songs and releases, for players that speak ChorusChorus 0.3.2, how Mantis maps to itchorus.json
canimus.jsonThe same again in Canimus, the older form of Chorus that Fairplayer reads; with a Fairplayer code set, every page also carries its verification tagCanimus, how Mantis writes itcanimus.json
activitypub/The artist as a fediverse account, and each release as a post (read-only)ActivityPub, detailsactor, outbox
.well-known/webfingerFinds the artist as @name@their-siteWebFingerwebfinger
.well-known/nodeinfoTells crawlers "this is a Mantis site"NodeInfo 2.1nodeinfo
site/sync/…, site/cues/…Per song: its lyric timings, and its cues (sections, beats, drum hits, builds and drops) for visualisersPer-song filescues
site/feed.rssThe songs as a podcast: each song an episode with its cover, length and MP3, for podcast apps and feed readersRSS 2.0 with iTunes and Podcasting 2.0 tags, detailsfeed.rss
sitemap.xml, robots.txt, llms.txtFor search engines and AI assistantsSitemaps, llms.txtsitemap, llms.txt
track/…, collection/…A page per song and release, readable without JavaScript, with its data embedded as JSON-LDPagesa song

Specs

Schemas

JSON Schemas for the files, the machine-checkable part of the spec. Mantis Music's tests check the sites it builds against them. These always point at the current version:

Every version

Each version's schemas stay at their own address and never change, so a site built by an older Mantis can always be checked against the schemas it was built for. A site says its version in mantis.json → formatVersion. Versions within 1.x only add optional things: the changelog says what each one added.

Conventions

Listing is the artist's choice
A site is public, but being listed is up to the artist. directories in mantis.json names the directories that may list it (* for any); missing or empty means none. Mantis Music lets new sites be listed and the artist can turn it off. Directories should honour it.
#MantisMusic
When Mantis posts an artist's new song to the fediverse, it adds #MantisMusic (they can turn it off). Directories can follow the tag to find new music.
Comments
A song's comments are the replies to the artist's fediverse post about it (discussionUrl). A reply is shown only if the artist wrote it or liked it, so the artist decides what appears.
Identity
Every site has a permanent urn:uuid id, and every song one made from it. They survive a move to a new address (alsoKnownAs, movedTo), and a song keeps its id when it's renamed.
Versions
Within version 1, changes only add optional things. Readers ignore fields they don't know. More

Hosting a Mantis site

Any web server that serves static files over HTTPS will do; Mantis Music uploads the site for you. For fediverse software and browser-based players to read it, the server should give the fediverse files their proper types, let other sites read the site's data, audio and pictures (Access-Control-Allow-Origin: *), and keep Mantis's publish record (site/publish.json) private. Mantis's own server set-up does all of this; the spec has the nginx rules.

Mantis never uploads private settings, keys or original high-resolution files, and checks every file before it is sent.

For readers: be a good guest

Artists pay for their own servers. If you build something that reads Mantis sites:

  • Read mantis.json first and follow its links; don't guess paths.
  • Send a User-Agent that names your app and links to it.
  • Use If-None-Match / If-Modified-Since, and check updated in mantis.json before fetching the catalogue again. Once a day is plenty.
  • Download a song once and keep it, rather than streaming it again and again.
  • List a site in a directory only if its directories allows it.
  • Link back to the artist's own site, where people can support them.

Questions, or building something on Mantis sites? support at mantismusic dot app