Mantis site format, version 1
Status: draft v1, first written 18 Oct 2026; additions in 1.1 (18 Oct) and 1.2 (20 Oct). Mantis Music has generated it since 18 Oct 2026. Until a second site exists this can still change; after that, only additively (see Versioning). Schemas: mantismusic.app/docs/schemas/.
A Mantis site is an artist's own website made only of static files. No server-side code runs on it. Everything an app, a directory, a search engine, an AI assistant or the fediverse needs is a file at a known path. This document says which files, at which paths, and what's in them.
Readers this format is for:
- The Mantis app: subscribes to sites like podcast feeds and plays them, offline too.
- Directories: crawl sites that ask to be listed; hold the listing, trust and search.
- The fediverse: looks the artist up as
@handle@siteand reads their releases. - Search engines and AI assistants: read pages and structured data without running JavaScript.
1. Files
All paths are relative to the site's base URL (e.g. https://mantisaudiogram.music/). The base URL over HTTPS is the site's address; the site's durable identity is id in mantis.json.
| Path | What | Stable API? |
|---|---|---|
mantis.json |
Site manifest: identity, format version, where everything is, listing opt-in, vouches, flags | Yes |
catalogue.json |
The works (tracks) and releases, as schema.org JSON-LD | Yes |
chorus.json |
The same works and releases in Chorus (§8), for Chorus players | Yes (Chorus 0.3) |
.well-known/webfinger |
WebFinger for acct:handle@host |
Yes (fediverse standard) |
.well-known/nodeinfo |
NodeInfo discovery (says "this is a Mantis site") | Yes (fediverse standard) |
nodeinfo/2.1.json |
NodeInfo 2.1 document | Yes |
activitypub/actor.json |
The site's ActivityPub actor | Yes (ActivityPub) |
activitypub/outbox.json |
The site's releases as Create activities |
Yes (ActivityPub) |
activitypub/works/{slug}.json |
Each work as an ActivityStreams Audio object |
Yes (ActivityPub) |
track/{slug}/ |
A work's page: readable without JavaScript, with JSON-LD | Yes (URLs are the works' @ids) |
collection/{slug}/ |
A release's page (album, EP, single) | Yes |
site/feed.rss |
RSS 2.0 + iTunes podcast tags (unchanged since the original app) | Yes |
sitemap.xml, robots.txt, llms.txt |
For crawlers and AI assistants | Yes |
site/discography.json/.js, site/bands/*, site/js/*, site/css/* |
The site's own player | No: internal, may change any time |
Rule for readers: read mantis.json first and follow its links; don't hard-code the other paths. Ignore any field you don't know. Treat missing optional fields as absent, not as errors.
Rule for pages: every HTML page links the manifest and catalogue:
<link rel="alternate" type="application/json" title="Mantis site" href="https://site/mantis.json">
<link rel="alternate" type="application/ld+json" title="Catalogue" href="https://site/catalogue.json">
<link rel="alternate" type="application/Chorus+json" title="Chorus" href="https://site/chorus.json">2. mantis.json
{
"mantis": 1,
"formatVersion": "1.2",
"id": "urn:uuid:1f0c6c1e-6a52-4c4e-9a5d-0f1d2c3b4a59",
"url": "https://mantisaudiogram.music/",
"name": "Mantis Audiogram",
"summary": "First line of the artist's bio",
"icon": "https://mantisaudiogram.music/site/og-image.png",
"updated": "2026-10-18T09:00:00Z",
"generator": { "name": "Mantis Music", "version": "1.0" },
"catalogue": "https://mantisaudiogram.music/catalogue.json",
"feeds": { "rss": "https://mantisaudiogram.music/site/feed.rss" },
"activitypub": {
"actor": "https://mantisaudiogram.music/activitypub/actor.json",
"handle": "@mantisaudiogram@mantisaudiogram.music"
},
"directories": [],
"vouches": [],
"flags": [],
"alsoKnownAs": []
}| Field | Required | Meaning |
|---|---|---|
mantis |
yes | Format major version. This document is 1. |
formatVersion |
no | The exact version the site was built with, major.minor (since 1.2): which schemas to check it against. |
id |
yes | Durable identity, urn:uuid:…, made once and kept forever, even if the site moves to a new address (like podcast:guid). |
url |
yes | The site's current base URL, ending in /. |
name |
yes | Artist or site name. |
summary, icon |
no | One line about the site; a square image. |
updated |
yes | When the site was last built (ISO 8601, UTC). Readers can skip re-fetching the catalogue if unchanged. |
generator |
no | The software that built the site. |
catalogue |
yes | URL of catalogue.json. |
feeds |
no | Other feeds; rss today. |
activitypub |
no | The actor URL and the fediverse handle. |
directories |
no | The listing opt-in. Directories that may list this site. Missing or [] means list me nowhere (the default). ["*"] means any directory may. |
vouches |
no | Base URLs of sites the operator vouches for: run by real people, publishing their own work. |
flags |
no | [{ "site": url, "reason": "spam" \| "impersonation" \| "stolen" \| "abuse" }] |
alsoKnownAs |
no | Previous base URLs (a moved site keeps its trust when both addresses confirm). movedTo (URL) is set on the old address when moving. |
Vouches, flags and listing live on the sites themselves: they are public and accountable, and every directory sees the same ones.
3. catalogue.json
One JSON-LD document using schema.org. The root is the artist; works and releases hang off it. Plain-JSON readers can ignore @context. Mantis-only data sits in a plain "mantis" object on each node, which JSON-LD processors ignore (it has no context mapping), so no namespace has to be invented yet.
{
"@context": "https://schema.org",
"@type": "MusicGroup",
"@id": "https://mantisaudiogram.music/#artist",
"identifier": "urn:uuid:1f0c6c1e-…",
"name": "Mantis Audiogram",
"url": "https://mantisaudiogram.music/",
"description": "The artist's bio (markdown).",
"image": "https://mantisaudiogram.music/site/og-image.png",
"sameAs": ["https://open.spotify.com/artist/…"],
"track": [ { "@type": "MusicRecording", "…": "newest first, see below" } ],
"album": [ { "@type": "MusicAlbum", "…": "newest first, see below" } ],
"mantis": { "catalogue": 1, "updated": "2026-10-18T09:00:00Z" }
}A work (MusicRecording)
{
"@type": "MusicRecording",
"@id": "https://mantisaudiogram.music/track/what-i-feel",
"url": "https://mantisaudiogram.music/track/what-i-feel",
"identifier": "urn:uuid:…",
"name": "What I feel",
"byArtist": { "@id": "https://mantisaudiogram.music/#artist", "name": "Mantis Audiogram" },
"datePublished": "2026-10-02",
"duration": "PT3M19S",
"genre": ["Rock", "AI", "Spiders"],
"description": "Markdown.",
"image": "https://mantisaudiogram.music/site/covers/what-i-feel.jpg",
"thumbnailUrl": "https://mantisaudiogram.music/site/thumbs/what-i-feel.jpg",
"audio": [
{ "@type": "AudioObject", "contentUrl": "https://…/what_i_feel.mp3", "encodingFormat": "audio/mpeg" },
{ "@type": "AudioObject", "contentUrl": "https://…/what_i_feel.wav", "encodingFormat": "audio/wav" }
],
"lyrics": { "@type": "CreativeWork", "text": "Lyrics, as written (section tags like [Chorus] kept)." },
"inAlbum": [{ "@id": "https://mantisaudiogram.music/collection/love-songs-1", "name": "Love Songs 1" }],
"discussionUrl": "https://openedtech.social/@mantisaudiogram/117366760157891397",
"mantis": {
"slug": "what-i-feel",
"bpm": 118,
"key": "E minor",
"mood": ["Dark"],
"credits": [{ "role": "Writing", "names": ["Yue2", "Martin Dougiamas"] }],
"lyricTimes": [{ "start": 43.2, "end": 45.68, "words": [[43.2, 43.52], null] }, null],
"visualiser": "v1:studio;sym=5;…"
}
}- Required:
@type,@id(the work's page on this site),name,datePublished(YYYY-MM-DD, orYYYY; works with no release date use their MP3's file date),audiowith at least oneaudio/mpegentry. Only tracks with an MP3 are works; releases list only works. identifier: durableurn:uuid:, a UUIDv5 of the siteidand the work's folder name, so it survives a move.genre: the artist's tags.discussionUrl: where comments live (the release's fediverse post).- MP3s are 320 kbps constant bitrate (seeking in variable-bitrate MP3s is approximate in browsers).
mantis.lyricTimes: one entry per sung line (the lyrics with blank lines and[Section]tags removed, each line trimmed). Each isnull(not timed) or{start, end}in seconds, optionally withwords: one[start, end]ornullper whitespace-separated word. Readers that show synced lyrics should treat a gap of more than 4 s inside a line as a mismatch and may estimate untimed lines (Mantis's own player does both).mantis.visualiser: the artist's chosen look for the site's visualiser (a string Mantis's player understands).
A release (MusicAlbum)
{
"@type": "MusicAlbum",
"@id": "https://mantisaudiogram.music/collection/love-songs-1",
"name": "Love Songs 1",
"datePublished": "2026-02-14",
"albumReleaseType": "https://schema.org/AlbumRelease",
"image": "https://…/site/covers/release-love-songs-1.jpg",
"description": "Markdown.",
"numTracks": 5,
"track": [{ "@id": "https://mantisaudiogram.music/track/…" }]
}albumReleaseType is AlbumRelease, EPRelease or SingleRelease. track is in running order and refers to works by @id, which may be on another site (a cross-site playlist later uses the same shape with @type: MusicPlaylist).
4. Fediverse files (read-only)
These let fediverse software look the artist up and read their releases. The site can't accept anything, because it's static: followable sites will come from directories hosting the inbox for the sites they list. Until then the actor says so and doesn't take followers.
.well-known/webfinger:{ subject: "acct:handle@host", aliases: [actor], links: [self → actor (application/activity+json), profile-page → site] }. The handle is the artist name lowercased with only letters and digits, unless set in the site's settings.activitypub/actor.json: aPersonwithpreferredUsername,name,summary,url,icon,image(banner),inbox(see below),outbox,publicKey(the build makes an RSA key once; the private half never leaves the artist's computer),manuallyApprovesFollowers: true, anddiscoverableandindexable(FEP-5feb) set totrue: the site is public, so fediverse search may show it. Being listed by Mantis directories is the separate opt-in inmantis.json.- Inbox, v1: the actor's
inboxisactivitypub/inboxon the site, which does nothing. Follow requests stay pending. Later, a directory's inbox URL replaces it; nothing else changes. activitypub/outbox.json: anOrderedCollectionofCreateactivities, newest first, one per work. Each wraps the work'sAudioobject.activitypub/works/{slug}.json: ActivityStreamsAudio(core vocabulary, which Mastodon shows as a title and link):name,attributedTo(the actor),published,duration,content(description),url(Links withmediaType: the pagetext/html, then the audio files),image(cover),tag(hashtags from genre)..well-known/nodeinfo→nodeinfo/2.1.jsonwithsoftware.name: "mantis"andmetadata.mantispointing atmantis.json. One request tells a crawler "this is a Mantis site".
Server note (the only one): static hosts serve files by extension. For fediverse software to accept them, activitypub/*.json should be served as application/activity+json and .well-known/webfinger as application/jrd+json, with Access-Control-Allow-Origin: *. For nginx:
# ^~ so these win over any regex rule for .json files; short caching so apps see new releases soon
location ^~ /activitypub/ { types { } default_type application/activity+json; add_header Access-Control-Allow-Origin *; expires 5m; }
location = /.well-known/webfinger { types { } default_type application/jrd+json; add_header Access-Control-Allow-Origin *; expires 5m; }
location = /.well-known/nodeinfo { types { } default_type application/json; add_header Access-Control-Allow-Origin *; }
location ~ ^/(mantis|catalogue|chorus)\.json$ { add_header Access-Control-Allow-Origin *; expires 5m; }
5. Pages without JavaScript
Each work's and release's page carries:
- its
MusicRecording/MusicAlbumas<script type="application/ld+json">, withbyArtistfilled in; - the readable content inside
<main>: title, artist, date, duration, cover, description, lyrics, credits, release and links. The player replaces it when JavaScript runs. A one-line script in<head>marks JavaScript as present, so the static content is hidden and never flashes.
The home page carries the MusicGroup (without track) and a list of every work linking to its page. sitemap.xml lists the home page, the about page and every work and release page with <lastmod>. robots.txt allows everything and names the sitemap. llms.txt describes the site and points at mantis.json, catalogue.json and the RSS feed.
6. Versioning
mantis.json'smantisand the catalogue'smantis.catalogueare major versions.- Within a major version, changes are only additive: new optional fields, new optional files. Readers ignore what they don't know.
- A breaking change raises the major version. The site then serves the new format at the same paths with the new number, and readers that don't know it fall back to the RSS feed. (Nothing breaking is planned.)
- The schemas are the machine-checkable part of this document; Mantis Music's tests check every build against them.
- Every minor version's schemas are published at a fixed address that never changes:
https://mantismusic.app/docs/schemas/{version}/{file}.schema.json(for example…/schemas/1.2/catalogue.schema.json);https://mantismusic.app/docs/schemas/{file}.schema.jsonis always the newest. A site names its version inmantis.json→formatVersion(sites from before 1.2 don't: treat them as 1.0 or 1.1). This page for a given version is athttps://mantismusic.app/docs/site-format/{version}/.
7. Version 1.1 additions (18 Oct 2026, optional)
Added for the Mantis app. All optional, so v1 readers are unaffected.
mantis.json→"theme": URL of the site'stheme.json.- A work's
mantisobject →"peaks": the waveform, 480 numbers from 0 to 1, evenly spaced through the song;"palette": the cover's colours,{ "bg", "a", "b", "c", "d" }, each an[r, g, b]triple from 0 to 1 (bgis the dark background,athe main accent);"bands": URL ofsite/bands/{slug}.json,{ "bands": "v2:…" }, the visualiser's per-frame audio bands in the encoding the site's player uses (site/js/bands.jsdecodes it).
- A release →
"mantis": { "palette": … }. catalogue.jsonis written compactly (no indentation); it's about 0.5 MB for 30 songs.
theme.json
A theme is settings only, never code: what a site builder uses to make the site and an app uses to draw it. Readers fall back to the built-in Mantis theme for anything missing or unknown, and for any mantisTheme major version they don't know. Schema: theme.schema.json.
{
"mantisTheme": 1,
"id": "mantis",
"name": "Mantis",
"colours": { "mode": "cover", "fallback": { "bg": "#121410", "ink": "#f1ece6", "accent": "#9bd45a", "muted": "#9e9a95" } },
"fonts": {
"poster": { "family": "Big Shoulders Display", "weight": 800, "url": "https://site/site/fonts/big-shoulders-latin.woff2" },
"text": { "family": "Inter", "weight": 400, "url": "https://site/site/fonts/inter-latin.woff2" }
},
"shape": { "radius": 8, "coverRadius": 16 },
"layout": { "stage": "classic", "wallColumns": { "phone": 2, "wide": 5 }, "lyrics": "centred-poster" },
"visualiser": { "look": "v1:studio" }
}colours.mode:cover(each song'spalettecolours its page, as the Mantis site does) orfixed(always the fallback colours). Colours are#rrggbb.fonts: a family and weight, with an optional font file (woff2/ttf) on the site. Readers use the system font at the same weight if a font can't be loaded.layoutvalues are named variants; v1 has onlystage: classic,lyrics: centred-poster.visualiser.look: the default look for songs without their ownmantis.visualiser.
8. Version 1.2 additions (20 Oct 2026, optional): Chorus
Chorus (formerly Canimus, spec 0.3.2) is an open JSON format for independent music, used by Mirlo, Sockpuppet and Song Fight! and read by Fairplayer. Mantis sites publish it too, so those players can follow a Mantis artist, and v1.2 borrows the parts of Chorus that cost Mantis nothing.
chorus.json (listed in mantis.json → feeds.chorus, linked from every page) is made from catalogue.json's works and releases, so the two always agree:
- collection → one
artist($id= the siteid) → its releases, newest first, then the works in no release. A work is defined where it first appears and is a{"$ref": id}after that. Track$ids are the works'identifiers; release$ids are UUIDv5s of the siteidand the release's page path. - A track has
duration(seconds),media(MP3 asaudio/mp3, withsize; the WAV when offered),images,tags(genre and mood),credits(name → roles),lyrics(plain text: section tags removed, a new section starts a new verse),synchronizedLyrics(one per timed sung line:startTime,duration,text),markers(each[Section]tag as asectionmarker at its first timed line), adiscussionlink to the fediverse post, and its cataloguemantisobject unchanged (waveform, palette, bands, word timing…), which Chorus readers ignore. - Descriptions are HTML (paragraphs, line breaks, http(s) links; everything else escaped).
releaseDateis also set on tracks (Chorus dates only releases; a work outside a release still has a date).
Borrowed into the catalogue:
- Audio
contentSize(bytes) on eachAudioObject. - Dates may be
YYYY-MMas well asYYYY-MM-DDandYYYY.
Planned, in Chorus's terms so both formats stay alike: support and purchase links (Chorus link rel support and purchase; the payment-links work), a licence (license/licenseUrl), and voice on synced lines for duets.
Mantis has, Chorus doesn't (yet): word-level lyric timing, waveform, cover palette, visualiser data, a comments thread, the listing opt-in, vouches and flags, a durable identity across moves, and a theme.
9. Not in v1 (on purpose)
- A live inbox, followers, replies (later, via directories).
- Playlists across sites, podcast
remoteItem/podrolltags in RSS, licences (FEP-6757), a PWA manifest.