Mantis Music

Docs › Mantis site format 1.2

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@site and 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, or YYYY; works with no release date use their MP3's file date), audio with at least one audio/mpeg entry. Only tracks with an MP3 are works; releases list only works.
  • identifier: durable urn:uuid:, a UUIDv5 of the site id and 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 is null (not timed) or {start, end} in seconds, optionally with words: one [start, end] or null per 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: a Person with preferredUsername, 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, and discoverable and indexable (FEP-5feb) set to true: the site is public, so fediverse search may show it. Being listed by Mantis directories is the separate opt-in in mantis.json.
  • Inbox, v1: the actor's inbox is activitypub/inbox on the site, which does nothing. Follow requests stay pending. Later, a directory's inbox URL replaces it; nothing else changes.
  • activitypub/outbox.json: an OrderedCollection of Create activities, newest first, one per work. Each wraps the work's Audio object.
  • activitypub/works/{slug}.json: ActivityStreams Audio (core vocabulary, which Mastodon shows as a title and link): name, attributedTo (the actor), published, duration, content (description), url (Links with mediaType: the page text/html, then the audio files), image (cover), tag (hashtags from genre).
  • .well-known/nodeinfo → nodeinfo/2.1.json with software.name: "mantis" and metadata.mantis pointing at mantis.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/MusicAlbum as <script type="application/ld+json">, with byArtist filled 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's mantis and the catalogue's mantis.catalogue are 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.json is always the newest. A site names its version in mantis.json → formatVersion (sites from before 1.2 don't: treat them as 1.0 or 1.1). This page for a given version is at https://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's theme.json.
  • A work's mantis object →
    • "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 (bg is the dark background, a the main accent);
    • "bands": URL of site/bands/{slug}.json, { "bands": "v2:…" }, the visualiser's per-frame audio bands in the encoding the site's player uses (site/js/bands.js decodes it).
  • A release → "mantis": { "palette": … }.
  • catalogue.json is 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's palette colours its page, as the Mantis site does) or fixed (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.
  • layout values are named variants; v1 has only stage: classic, lyrics: centred-poster.
  • visualiser.look: the default look for songs without their own mantis.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 site id) → 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 site id and the release's page path.
  • A track has duration (seconds), media (MP3 as audio/mp3, with size; 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 a section marker at its first timed line), a discussion link to the fediverse post, and its catalogue mantis object unchanged (waveform, palette, bands, word timing…), which Chorus readers ignore.
  • Descriptions are HTML (paragraphs, line breaks, http(s) links; everything else escaped).
  • releaseDate is 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 each AudioObject.
  • Dates may be YYYY-MM as well as YYYY-MM-DD and YYYY.

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/podroll tags in RSS, licences (FEP-6757), a PWA manifest.