Mantis site format, version 1
Status: draft v1, first written 18 Oct 2026; additions in 1.1 (18 Oct), 1.2, 1.3 and 1.4 (20 Oct), and 1.5 and 1.6 (22 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/sync/{slug}.json |
A work's lyric timings on their own (1.5, linked from the catalogue) | Yes |
site/discography.json/.js, site/bands/*, site/sync/*.js, site/covers/600/*, 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. Version 1.3 additions (20 Oct 2026, optional): visualiser motion and Visual story
mantis.json→formatVersion:"1.3".- A work's
mantisobject →"visualiserSections":{ "<section name>": "<look string>" }, the artist's look for every lyric section with that name (used when the look'smosetting issections: the look then changes at each[Section]heading's first sung line);"story": the song's Visual story, images the visualiser blends in at moments of the song:[{ "url", "times": [seconds…], "hold"?: seconds, "source"?: "generated" | "artist" }]. Each image shows at each of its times forholdseconds (or until the next image, at most 20 s), fading in and out over about a second. The images are JPEGs, at most 1024 px (tracks/{folder}/story/{n}.jpg). How they were made (prompts) is not published. Credits are only the ones the artist wrote (versions of Mantis before 1.0 added "Visuals: Apple Image Playground" for generated images).
- Look strings (
mantis.visualiser) may use the new visualiser settings: scenes (sc,scb: flow, lines, grid, swarm, flame), motion through the song (mo: fixed, sections, drift) and the images layer (img,itr,imo,ibl). Readers that don't know a key ignore it.
10. Version 1.4 additions (20 Oct 2026, optional): Canimus for Fairplayer
canimus.jsonat the root: the site in Canimus, the older form of Chorus that Fairplayer reads:root→artist→albums (each with itstracks) and singles (tracks in no release). Made from the same works and releases ascatalogue.jsonandchorus.json. Dates are fullYYYY-MM-DD(a month-only date gets day 01), the MP3 is each track's firstmediaentry (type: "audio/mp3"), and images use thecoverkey. Schema:canimus.schema.json.- Every page carries
<link rel="alternate" type="application/canimus+json" title="Canimus" href="…/canimus.json">, andmantis.jsonfeeds.canimuspoints to it. - Fairplayer verification: when the artist sets a Fairplayer code (config
fairplayer_code), every page also carries<meta name="fairplayer-code" content="…">, which Fairplayer checks before listing a site.
Readers that don't know these simply ignore them; nothing else changed.
11. Version 1.5 additions (22 Oct 2026, optional): support links, buy links, lyric timings per song
Support and buy links. Places the artist already gets paid or supported. Mantis never handles money: these are plain links out, each { "service", "url", "name" }. url is always https://; service is worked out from the address: ko-fi, patreon, liberapay, open-collective, paypal, buy-me-a-coffee, bandcamp, mirlo or other (readers should treat a value they don't know as other); name is what to show (the artist's own name for the link, else the service's).
mantis.json→"support": [link…], in the artist's order, and the same list in the catalogue's rootmantisobject (mantis.support).- A work's and a release's
mantisobject →"buy": link, where the song or release can be bought or downloaded (Bandcamp, Mirlo, Faircamp…). A work without one may be bought through its release's. - Chorus: the artist's
linksgain onerel: "support"link per support link, and tracks and releases arel: "purchase"link (Chorus's own names for these). - RSS: one
<podcast:funding url="…">name</podcast:funding>(Podcasting 2.0) per support link in the channel, and thepodcastnamespace, only when there are any. - The site shows them on the About page (a "Support" card,
#support), on song pages (a Support button, and Buy or download links), each with the site it goes to. (1.6 replaced the song page's Support button: see §12.)
Lyric timings per song.
- A work's
mantisobject →"lyricSync": URL ofsite/sync/{slug}.json,{ "lyricTimes": […] }, the same timings asmantis.lyricTimes(same shape) in a file of their own, for readers that load them only for the song being played. Mantis sites still carrylyricTimesin the catalogue too; a reader that findslyricSyncbut nolyricTimesshould load the file. - Pages: every work's, release's, the home and the about page carry
<link rel="canonical" href="…">with the page's own address (a work's is its@id).
The site's own player changed too (internal, not part of the format): site/discography.json no longer carries the timings (it loads site/sync/{slug}.js when a song is shown or played), the stage uses 600px covers (site/covers/600/, JPEG and AVIF), and the favicon (64px) and home-screen icon (site/apple-touch-icon.jpg, 180px) are small copies of the profile picture.
Readers that don't know these simply ignore them; nothing else changed.
12. Version 1.6 additions (22 Oct 2026, optional): kinds, titles and notes for support links
Each support link (mantis.json → support, the catalogue's mantis.support, and the site's own data) gains three fields; service, url and name stay as in 1.5, so older readers keep working:
kind: what the link is for:membership(Patreon, Liberapay, GitHub Sponsors…),tip(Ko-fi, PayPal.me, Venmo…),store(Bandcamp, Mirlo, the artist's shop),crowdfunding(Kickstarter, GoFundMe) orother. Mantis works out a default from the address and the artist can change it. Readers may use it to pick an icon; treat a value you don't know asother.title: what to show, e.g. "Join on Patreon" or "Buy me a coffee" (the artist's own words, else made from the service and kind).namecarries the same text for 1.5 readers.note: optional, one short line (at most 80 characters) shown under the title, e.g. "Monthly · early demos".
An artist may list any number of links, several on the same service, in their own order. service may now also be github-sponsors, stripe (Stripe payment links), venmo, cash-app, kickstarter or gofundme.
A work's or release's buy link (1.5) is unchanged; Mantis keeps publishing ones artists already set but no longer offers a field for new ones: support links cover the same ground.
The site's own player (internal): a small "Support" button on every page opens the list; the About page's #support card lists them in full; the song page's Support button is gone.
Readers that don't know these simply ignore them; nothing else changed.
13. 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.