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.
| File | What it is | Standard | Example |
|---|---|---|---|
mantis.json | The site's manifest: who it is, where everything is, and whether directories may list it | Mantis site format | mantis.json |
catalogue.json | Every song and release: audio, covers, lyrics with timings, credits, waveform, colours | schema.org JSON-LD, with Mantis extras | catalogue.json |
theme.json | How the site looks: colours, fonts, layout, visualiser | Mantis theme | theme.json |
chorus.json | The same songs and releases, for players that speak Chorus | Chorus 0.3.2, how Mantis maps to it | chorus.json |
canimus.json | The same again in Canimus, the older form of Chorus that Fairplayer reads; with a Fairplayer code set, every page also carries its verification tag | Canimus, how Mantis writes it | canimus.json |
activitypub/ | The artist as a fediverse account, and each release as a post (read-only) | ActivityPub, details | actor, outbox |
.well-known/webfinger | Finds the artist as @name@their-site | WebFinger | webfinger |
.well-known/nodeinfo | Tells crawlers "this is a Mantis site" | NodeInfo 2.1 | nodeinfo |
site/sync/…, site/cues/… | Per song: its lyric timings, and its cues (sections, beats, drum hits, builds and drops) for visualisers | Per-song files | cues |
site/feed.rss | The songs as a podcast: each song an episode with its cover, length and MP3, for podcast apps and feed readers | RSS 2.0 with iTunes and Podcasting 2.0 tags, details | feed.rss |
sitemap.xml, robots.txt, llms.txt | For search engines and AI assistants | Sitemaps, llms.txt | sitemap, llms.txt |
track/…, collection/… | A page per song and release, readable without JavaScript, with its data embedded as JSON-LD | Pages | a song |
Specs
Mantis site format
The full description of every file above: fields, meanings, examples, versioning. The one to read if you're building an app, a player or a directory.
Spec · part of the formatThemes
A site's look as settings, never code: what an app needs to draw a site the way the site itself looks.
InteropChorus
How Mantis sites appear in the Chorus format, and which Chorus ideas Mantis has taken on.
InteropFediverse
How an artist's site shows up on Mastodon and friends, and where comments on songs come from.
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:
- mantis.schema.json the manifest
- catalogue.schema.json songs and releases
- theme.schema.json the theme
- cues.schema.json a song's cues
- chorus.schema.json the parts of Chorus Mantis writes
- canimus.schema.json the Canimus Mantis writes
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.
directoriesinmantis.jsonnames 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:uuidid, 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.jsonfirst and follow its links; don't guess paths. - Send a
User-Agentthat names your app and links to it. - Use
If-None-Match/If-Modified-Since, and checkupdatedinmantis.jsonbefore 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
directoriesallows 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