Mantis Music

Docs › Mantis site format 1.7

Mantis site format, version 1

Current version: 1.7 (24 Oct 2026). Major version 1, first published 18 Oct 2026. Mantis Music has made sites in this format since then, and other people's sites use it now, so version 1 only grows by addition: see Versioning. Every version's schemas: mantismusic.app/docs/#schemas. What each version added: Changelog.

A Mantis site is an artist's own website made only of static files. No code runs on the server. Everything an app, a directory, a search engine, an AI assistant or the fediverse needs is a file at a known address. This document says which files, where they are, and what's in them.

It's written for people building:

  • players and apps, which follow sites like podcast feeds and play them, offline too (the Mantis app is one);
  • directories, which list the sites that ask to be listed;
  • fediverse software, which looks an artist up as @handle@site and reads their songs;
  • search engines and AI assistants, which read pages and structured data without running JavaScript.

Quick start for readers

  1. Fetch mantis.json at the site's root (or follow the <link rel="alternate" type="application/json"> on any of its pages). It names the site, gives its permanent id, and links everything else.
  2. Fetch the catalogue it links to: the artist, every song (with audio, cover, lyrics, credits and more) and every release.
  3. Next time, compare updated in mantis.json with what you saw before, and fetch the catalogue again only if it changed. Send If-None-Match or If-Modified-Since with every request.
  4. Load a song's extras only when you need them: its lyric timings (mantis.lyricSync) and its cues (mantis.cues).

Three rules for every reader:

  • Follow links; don't build addresses. Apart from mantis.json itself, take every address from the files.
  • Ignore what you don't know. Unknown fields, unknown values and unknown files are normal: later versions add them.
  • Missing optional fields are absent, not errors.

Artists pay for their own servers, so be a good guest: name your app in a User-Agent with a link, fetch a site at most about once a day, download a song once rather than streaming it again and again, list a site only if its directories allows it, and link back to the artist's own site.

1. The files

Addresses are relative to the site's base URL, e.g. https://mantisaudiogram.music/. The base URL over HTTPS is the site's current address; its permanent identity is id in mantis.json.

Public: part of the format. Readers may rely on these.

Path What it is Since
mantis.json The manifest: identity, version, where everything is, listing, support links, vouches and flags (§2) 1.0
catalogue.json The artist, songs and releases as schema.org JSON-LD (§3) 1.0
theme.json The site's look as settings (§5) 1.1
site/sync/{slug}.json One song's lyric timings (§4) 1.5
site/cues/{slug}.json One song's cues: sections, moments, beats, parts (§4) 1.7
site/bands/{slug}.json One song's visualiser bands, in the player's own encoding (§4) 1.1
chorus.json The songs and releases in Chorus (§6) 1.2
canimus.json The same in Canimus, the older form of Chorus that Fairplayer reads (§6) 1.4
.well-known/webfinger, .well-known/nodeinfo, nodeinfo/2.1.json Fediverse discovery (§7) 1.0
activitypub/actor.json, activitypub/outbox.json, activitypub/works/{slug}.json The artist and their songs as read-only ActivityPub (§7) 1.0
site/feed.rss RSS 2.0 with iTunes tags (§8) 1.0
track/{slug}/, collection/{slug}/ A page per song and per release, readable without JavaScript (§9) 1.0
index.html, about/ The home and About pages (§9) 1.0
sitemap.xml, robots.txt, llms.txt For crawlers and AI assistants (§9) 1.0
Images and audio Covers (site/covers/), thumbnails (site/thumbs/), the profile picture (site/og-image.*), banner (site/banner.*), story images, MP3s and WAVs: always reached through an address in the files above, never built 1.0

Internal: the site's own player. These change whenever Mantis needs them to; don't read them: site/discography.json and .js, site/data-version.js, site/sync/*.js, site/cues/*.js, site/covers/600/, site/feed/*.html, site/js/, site/css/, site/fonts/, site/favicon.*, site/apple-touch-icon.jpg, and site/publish.json (the app's own record of the last publish, which hosts should keep private: see §10).

2. mantis.json: the manifest

{
  "mantis": 1,
  "formatVersion": "1.7",
  "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.1.1" },
  "catalogue": "https://mantisaudiogram.music/catalogue.json",
  "theme": "https://mantisaudiogram.music/theme.json",
  "feeds": {
    "rss": "https://mantisaudiogram.music/site/feed.rss",
    "chorus": "https://mantisaudiogram.music/chorus.json",
    "canimus": "https://mantisaudiogram.music/canimus.json"
  },
  "activitypub": {
    "actor": "https://mantisaudiogram.music/activitypub/actor.json",
    "handle": "@mantisaudiogram@mantisaudiogram.music"
  },
  "directories": ["*"],
  "support": [
    { "service": "ko-fi", "kind": "tip", "url": "https://ko-fi.com/…", "title": "Buy me a coffee", "name": "Buy me a coffee" }
  ],
  "vouches": [],
  "flags": [],
  "alsoKnownAs": []
}
Field Required Meaning Since
mantis yes The format's major version: 1. 1.0
formatVersion no The exact version the site was made with, "major.minor": the schemas to check it against. Sites from before 1.2 leave it out; treat them as 1.0 or 1.1. 1.2
id yes Permanent identity, urn:uuid:…, made once and kept even if the site moves to a new address (like a podcast's podcast:guid). 1.0
url yes The site's current base URL, ending in /. 1.0
name yes The artist's or site's name. 1.0
summary no One line about the site. 1.0
icon no A square picture: the artist's profile picture. 1.0
updated yes When the site was last built (ISO 8601, UTC). If it hasn't changed, nothing else has. 1.0
generator no The software that made the site: name (e.g. "Mantis Music"; other apps give their own) and, when known, version (that app's version, e.g. "1.1.1"). Mantis Music 1.0 and 1.1 always wrote "1.0". 1.0
catalogue yes The address of catalogue.json. 1.0
theme no The address of theme.json. 1.1
feeds no Other feeds: rss, chorus (1.2), canimus (1.4). 1.0
activitypub no actor, the actor's address, and handle, the fediverse handle. 1.0
directories no Which directories may list the site. Each entry is "*" (any directory) or a directory's host, e.g. "mantismusic.app" (a full address counts by its host). Missing or [] means none. 1.0
support no Where to support the artist, in their order (support links). 1.5
vouches no Base URLs of sites whose owner this artist vouches for: real people, publishing their own work. 1.0
flags no Sites this artist reports: [{ "site": url, "reason": "spam" \| "impersonation" \| "stolen" \| "abuse" }]. 1.0
alsoKnownAs no The site's earlier base URLs. When a site moves, its old address sets movedTo (a URL) and the new one lists the old in alsoKnownAs; a reader that sees both agree keeps following the site at its new address. 1.0

Listing, vouches and flags live on the sites themselves, so they're public and accountable, and every directory sees the same ones. Mantis Music 1.1.1 makes new sites with directories: ["*"] and asks the owners of older sites once; the artist can change it any time. It writes vouches, flags and alsoKnownAs as empty lists for now and never writes movedTo yet; readers should still honour them.

Places the artist already gets paid or supported. They're plain links out; Mantis never handles money.

{ "service": "patreon", "kind": "membership", "url": "https://www.patreon.com/…",
  "title": "Join on Patreon", "name": "Join on Patreon", "note": "Monthly · early demos" }
  • url: always https://.
  • service: worked out from the address: ko-fi, patreon, liberapay, open-collective, paypal, buy-me-a-coffee, bandcamp, mirlo, github-sponsors, stripe (payment links), venmo, cash-app, kickstarter, gofundme or other. Treat a value you don't know as other.
  • kind (1.6): what the link is for: membership, tip, store, crowdfunding or other (treat an unknown value as other). Mantis picks one from the service and the artist can change it. Useful for choosing an icon.
  • title (1.6): what to show: the artist's own words, else made from the service and kind ("Buy me a coffee").
  • name: the same text as title, for 1.5 readers.
  • note (1.6, optional): one short line shown under the title, at most 80 characters.

An artist may list any number of links, several on one service. The same list is in the catalogue (mantis.support), Chorus (rel: "support" links) and RSS (<podcast:funding>).

3. catalogue.json: songs and releases

One JSON-LD document using schema.org. The root is the artist; songs ("works") and releases hang off it, newest first. Plain-JSON readers can ignore @context. Data only Mantis has sits in a plain "mantis" object on any node; JSON-LD processors ignore it (it has no context mapping). The file is written compactly (no indentation): about 0.5 MB for 30 songs.

{
  "@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", "…": "works, newest first" } ],
  "album": [ { "@type": "MusicAlbum", "…": "releases, newest first" } ],
  "mantis": { "catalogue": 1, "updated": "2026-10-18T09:00:00Z", "support": [] }
}

The root's mantis object: catalogue, the catalogue's major version (1); updated, the same time as mantis.json's; support (1.5), the support links.

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?v=dcd7919ac7",
  "thumbnailUrl": "https://mantisaudiogram.music/site/thumbs/what-i-feel.jpg?v=dcd7919ac7",
  "audio": [
    { "@type": "AudioObject", "contentUrl": "https://…/what_i_feel.mp3", "encodingFormat": "audio/mpeg", "contentSize": 7965312 },
    { "@type": "AudioObject", "contentUrl": "https://…/what_i_feel.wav", "encodingFormat": "audio/wav", "contentSize": 35128044 }
  ],
  "lyrics": { "@type": "CreativeWork", "text": "Lyrics, as written ([Chorus] tags 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],
    "lyricSync": "https://mantisaudiogram.music/site/sync/what-i-feel.json",
    "cues": "https://mantisaudiogram.music/site/cues/what-i-feel.json",
    "visualiser": "v1:studio;sym=5"
  }
}

Only songs with an MP3 are works. Required: @type, @id, name, datePublished and audio with at least one audio/mpeg entry.

Field Meaning Since
@id, url The work's page on this site. It follows the song's title, so it changes if the song is renamed (the old address then forwards: §9). 1.0
identifier Permanent identity, urn:uuid:: a UUIDv5 of the site's id and the name the song's folder had first. It stays the same when the site moves or the song is renamed, so use it to remember songs (playlists, favourites). 1.0
datePublished YYYY-MM-DD, YYYY-MM (1.2) or YYYY. A song with no release date uses its MP3's file date; with neither, 1970. 1.0
duration ISO 8601 duration. 1.0
genre The artist's tags. 1.0
description Markdown. 1.0
image, thumbnailUrl The cover (up to 1024 px) and a 400 px thumbnail. Addresses may carry ?v= to change when the picture does. 1.0
audio AudioObjects: the MP3 first (320 kbps constant bitrate, so seeking is exact), then the WAV if the artist offers it. contentSize in bytes (1.2). 1.0
lyrics The lyrics as written, [Section] tags kept. 1.0
inAlbum The releases it's on. 1.0
discussionUrl The song's fediverse post: its replies are the song's comments. 1.0

The work's mantis object (every field optional):

Field Meaning Since
slug The page name, as in the work's address. 1.0
bpm, key, mood, credits Tempo, key, moods, and [{ role, names }] credits. 1.0
lyricTimes Lyric timings: see below. 1.0
lyricSync The address of the same timings on their own (§4). A reader that finds lyricSync but no lyricTimes should load it. 1.5
cues The address of the song's cues (§4). Only songs Mantis could analyse have one. 1.7
peaks The waveform: 480 numbers from 0 to 1, evenly spaced through the song. 1.1
palette The cover's colours, { "bg", "a", "b", "c", "d" }, each [r, g, b] from 0 to 1 (bg the dark background, a the main accent). 1.1
bands The address of the song's visualiser bands (§4). 1.1
visualiser The artist's look for the visualiser, a look string. Left out when the song uses the default look. 1.0
visualiserSections { "<section name>": "<look string>" }: the artist's look for each section with that name (look strings). 1.3
story The song's Visual story: see below. 1.3
buy Where the song can be bought or downloaded: { "service", "url", "name" }, name being the service's name (or the address's host for other). Mantis keeps publishing ones artists set before 1.6 but no longer asks for new ones: support links cover it. 1.5

Lyric timings (lyricTimes): one entry per sung line, the lyrics with blank lines and [Section] tags removed and each line trimmed. Each entry is null (not timed) or { "start", "end" } in seconds, optionally with words: one [start, end] or null per whitespace-separated word. A player showing 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).

Visual story (story): pictures the visualiser blends in at moments of the song: [{ "url", "times": [seconds…], "hold"?: seconds, "source"?: "generated" | "artist" }]. Each picture shows at each of its times for hold seconds (or until the next picture, at most 20 s), fading in and out over about a second. They are JPEGs, at most 1024 px. How they were made (prompts) isn't published. Credits are only those the artist wrote (versions of Mantis before 1.0 added "Visuals: Apple Image Playground" for generated pictures).

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/…" }],
  "mantis": { "palette": { "…": "as for a work" } }
}
  • Required: @type, @id (the release's page), name, track.
  • track: the works in running order, by @id. Only works are listed and numTracks counts them; a release with none isn't published.
  • albumReleaseType: EPRelease if the artist calls it an EP, SingleRelease if it has one work, otherwise AlbumRelease.
  • datePublished: only when the release has a date.
  • mantis (optional): palette (1.1) and buy (1.5), as for a work.
  • A release has no identifier in the catalogue: its @id changes if the release is renamed (the old address forwards). Its Chorus $id and Canimus uid are made from the name it had first, so they don't.

4. Per-song files

Each is linked from the work's mantis object. Load them only for the song being shown or played.

Lyric timings: site/sync/{slug}.json

{ "lyricTimes": […] }: exactly the work's mantis.lyricTimes, in a file of its own (1.5). Mantis sites carry both.

Visualiser bands: 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). Still published so existing players keep their visualiser; the part levels in a song's cues will replace them in a later version.

Song cues: site/cues/{slug}.json

What a listener hears in a song, as markers a visualiser (or anything else) can follow: where the verses and choruses are, the builds and drops, the solos, each beat and bar, each drum hit, and how loud each part is from moment to moment. Mantis works them out when it publishes (1.7). Schema: cues.schema.json.

{
  "cues": 1,
  "analysis": "full",
  "duration": 263.4,
  "tempo": { "bpm": 109, "meter": 4 },
  "beats": [0.42, 0.97],
  "bars": [0.42, 2.62],
  "sections": [
    { "start": 41.6, "end": 58.3, "kind": "verse", "number": 1, "tune": "A", "level": "mid", "lines": [0, 5] },
    { "start": 58.3, "end": 79.0, "kind": "chorus", "number": 1, "tune": "B", "level": "loud", "hook": true },
    { "start": 210.9, "end": 262.0, "kind": "chorus", "number": 3, "tune": "B", "level": "loud", "last": true }
  ],
  "moments": [
    { "at": 41.6, "kind": "enter", "part": "bass" },
    { "at": 54.0, "kind": "build", "end": 58.3 },
    { "at": 58.3, "kind": "drop" },
    { "at": 196.0, "kind": "solo", "end": 210.9 }
  ],
  "parts": {
    "drums": { "kick": [[0.42, 0.8]], "snare": [[0.97, 0.6]], "hat": [], "crash": [], "fills": [[56.1, 58.3]],
               "level": "v1:40:…" },
    "bass": { "notes": [[0.88, 0.33, 47]], "level": "v1:40:…" },
    "other": { "level": "v1:40:…" },
    "vocals": { "level": "v1:40:…" }
  },
  "feel": "v1:10:…"
}

Times are in seconds. Spans have start and end; single moments have at, and end when they last. Keys always come in the order shown.

  • cues: the file's version, 1.
  • analysis: full (from the song's separated parts and a model of song structure, helped by the lyrics) or basic (from the whole mix). A basic file has empty sections, beats and bars, bpm 0, no fills, crashes or bass notes, only enter and exit moments, and approximate hits and levels. Mantis makes basic cues on devices that can't do the full analysis, and always for songs over 20 minutes; a later publish from a capable device replaces a basic file with a full one (except for those long songs).
  • duration: the song's length. tempo: bpm (0 when unknown) and meter, beats to the bar.
  • beats, bars: the time of each beat, and of each bar's first beat.
  • sections, in order:
    • kind: intro, verse, chorus, bridge, instrumental, solo or outro;
    • number: which time round (the second verse is 2);
    • tune: the same letter means the same music coming back;
    • level: quiet, mid or loud, against the song's own range;
    • lines (optional): the first and last sung line in it, as indexes into the work's lyricTimes;
    • hook (optional): the hook (the repeated line with the title in it) is sung in it;
    • last (optional): the last chorus.
  • moments, in time order, by kind:
    • build: rising until end;
    • drop: a hit after a build, or out of a quiet stretch;
    • lift: a hit that isn't a drop;
    • breakdown: the song falls away;
    • stop: silence until end;
    • peak: the song's biggest stretch, until end;
    • solo: a wordless stretch where one part clearly leads, until end (which instrument isn't said);
    • enter / exit with part (drums, bass, other or vocals): a part coming in or dropping out.
  • parts: what each part does. Drum hits are [time, strength]; fills are [start, end], ending on the bar line they lead into; bass notes are [time, strength, pitch] (a MIDI note number). Strengths are 0–1 within the song. Each part's level is a curve at 40 frames a second.
  • feel: how big the song feels, 0–1, a curve at 10 frames a second.
  • Curves are strings, "v1:<frames a second>:<base64>": one byte per frame; the byte divided by 255 gives 0–1.

5. theme.json: the look

A theme is settings only, never code: enough for an app to draw a site the way the site itself looks. Readers fall back to the built-in Mantis theme for anything missing or unknown, and for any mantisTheme major version they don't know. Mantis Music writes the same theme for every site for now (the look of its built-in site); artists can't change it yet. 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 on Mantis sites) or fixed (always the fallback colours). Colours are #rrggbb.
  • fonts: a family and weight, with an optional font file (woff2 or ttf) on the site. Use the system font at the same weight if a font can't be loaded.
  • layout: named variants; version 1 has only stage: classic and lyrics: centred-poster.
  • visualiser.look: the look for songs without their own mantis.visualiser. "v1:studio" (the plain base look) means Mantis's default, Mantis mix (look strings).

Look strings

A look string describes a visualiser look: v1:<base look> followed by ;key=value settings that differ from the base, e.g. v1:studio;sym=5;mo=sections. Players that don't know a key ignore it. A song with no look, or the plain v1:studio, gets Mantis mix, where Mantis picks a look for each part of the song itself. The full list of keys is the site player's (site/js/viz-params.js); these are the ones that change how a look behaves through a song:

  • sc (1.3): the scene: flow, lines, grid, swarm or flame. scb: a second scene layered over it, the same choices or none (the default).
  • mo (1.3): motion through the song: auto, fixed, sections or drift.
    • fixed: the look stays as it is.
    • sections: the look changes at each lyric [Section] heading's first sung line, using the work's visualiserSections.
    • drift: the look wanders slowly.
    • auto (1.7, now the default when mo is missing; before 1.7 a missing mo meant fixed): the look follows the song's cues. Each section kind has its own look, a section with the same tune brings its look back, level and the last chorus set the intensity, a solo turns the scene to the lead, changes land on bars, builds ramp up and drops hit. visualiserSections names match a cue section's kind, ignoring case ("Chorus" for chorus). Without sections in the cues (none, or basic), auto follows the lyric [Section] headings instead, as sections does.
  • mix: 1 turns on Mantis mix.
  • mut: 1 changes the style every few seconds.
  • img, itr, imo, ibl (1.3): the Visual story layer's strength (0–1), treatment, motion and blend.
  • A setting may follow a sound in the song's cues: key=value@sound (1.7).

6. Chorus and Canimus

chorus.json

Chorus (spec 0.3.2; formerly Canimus) is an open JSON format for independent music, used by Mirlo, Sockpuppet and Song Fight! and read by Fairplayer. Mantis sites publish it (1.2) so Chorus players can follow a Mantis artist. It's made from the catalogue's works and releases, so the two always agree.

  • The collection holds one artist ($id = the site id; with summary, images (profile picture and banner) and links: the site's manifest, the RSS feed, each sameAs address as rel: "this", and each support link as rel: "support"), then its releases, newest first, then the works in no release. Releases with no works are left out.
  • A work is written in full where it first appears and as { "$ref": id } after that. Track $ids are the works' identifiers; release $ids are UUIDv5s of the site id and the release's page path (the one it had first, if it was renamed).
  • A track has duration (seconds), releaseDate (Chorus dates only releases; a work outside a release still has one), media (the MP3 as audio/mp3 with size, then 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 its fediverse post, a rel: "purchase" link for its buy link, and the catalogue's mantis object unchanged, which Chorus readers ignore.
  • Descriptions are HTML: paragraphs, line breaks and http(s) links; everything else escaped.
  • Every page links it as <link rel="alternate" type="application/Chorus+json" href="…/chorus.json">.

From Chorus, the catalogue took audio contentSize and YYYY-MM dates (1.2). Mantis has that Chorus doesn't (yet): word-level lyric timing, waveform, cover colours, cues and visualiser looks, comments, listing, vouches and flags, a permanent identity across moves, and a theme.

canimus.json

The site in Canimus, the older form of Chorus that Fairplayer reads (1.4): root → artist → albums (each with its tracks) and singles (works in no release), made from the same works and releases. Schema: canimus.schema.json.

  • Dates are full YYYY-MM-DD (a month-only date gets day 01, a year-only date 01-01).
  • Each track's first media entry is the MP3 (type: "audio/mp3").
  • Albums and tracks use the cover key for images; the artist has cover, thumb and photo.
  • Every page links it as <link rel="alternate" type="application/canimus+json" href="…/canimus.json">.
  • Fairplayer verification: when the artist sets a Fairplayer code, every page also carries <meta name="fairplayer-code" content="…">, which Fairplayer checks before listing a site.

7. Fediverse files (read-only)

These let fediverse software look the artist up and read their songs. A static site can't accept anything, so following isn't possible yet: later, directories will host the inbox for the sites they list. Until then the actor says so and takes no followers.

  • .well-known/webfinger: { "subject": "acct:handle@host", "aliases": [actor, site], "links": [self → actor (application/activity+json), profile-page → site] }. The handle is the artist's name (or the one set in the site's settings), lowercased, keeping only the letters a–z and digits; artist if nothing is left.
  • activitypub/actor.json: a Person with preferredUsername, name, summary, url, icon (the profile picture), image (the banner), published, inbox, outbox, publicKey (…#main-key; the private key never leaves the artist's devices), manuallyApprovesFollowers: true, and discoverable and indexable (FEP-5feb) set to true: the site is public, so fediverse search may show it. Being listed in directories is the separate choice in mantis.json.
  • Inbox: activitypub/inbox, which doesn't exist, so follow requests stay pending. A directory's inbox will replace it later; nothing else will change.
  • activitypub/outbox.json: an OrderedCollection of Create activities, one per work, newest first, each wrapping the work's Audio object.
  • activitypub/works/{slug}.json: an ActivityStreams Audio (which Mastodon shows as a title and link) with name, attributedTo (the actor), to (public), published, duration, content (the description, as HTML), url (links with mediaType: the page as text/html, then the audio files), image (the cover) and tag (hashtags from the genres, letters and digits only: "Funk Rock" → #FunkRock).
  • .well-known/nodeinfo → nodeinfo/2.1.json: software.name is "mantis" (with version, the app's, and homepage, the site's mantis.json), and metadata.mantis points at mantis.json. One request tells a crawler "this is a Mantis site".

When Mantis Music posts a new song to the artist's Mastodon account, the post's hashtags include #MantisMusic unless the artist turns it off, so anyone can follow the tag to find new music.

8. RSS: site/feed.rss

An RSS 2.0 feed of the artist's songs, newest first, that works both in feed readers and in podcast apps (Apple Podcasts, Overcast, Pocket Casts and others): each song is an episode, with its cover, its length and the MP3 to play. It uses the itunes, content and atom namespaces, and podcast (Podcasting 2.0) when the artist has support links. mantis.json links it as feeds.rss.

<channel>
  <title>Mantis Audiogram</title>
  <link>https://mantisaudiogram.music</link>
  <description>The first 500 characters of the artist's bio</description>
  <language>en</language>
  <lastBuildDate>Mon, 09 Nov 2026 13:36:23 +0800</lastBuildDate>
  <atom:link href="https://mantisaudiogram.music/site/feed.rss" rel="self" type="application/rss+xml" />
  <itunes:image href="https://mantisaudiogram.music/site/og-image.jpg" />
  <image><url>https://mantisaudiogram.music/site/og-image.jpg</url><title>Mantis Audiogram</title><link>https://mantisaudiogram.music</link></image>
  <podcast:funding url="https://ko-fi.com/…">Buy me a coffee</podcast:funding>
  <item>
    <title>What I feel</title>
    <link>https://mantisaudiogram.music/site/feed/what-i-feel.html</link>
    <guid isPermaLink="true">https://mantisaudiogram.music/site/feed/what-i-feel.html</guid>
    <description>The song's description.</description>
    <content:encoded><![CDATA[cover, description, lyrics, a link to the song's page]]></content:encoded>
    <pubDate>Fri, 02 Oct 2026 00:00:00 +0800</pubDate>
    <enclosure url="https://mantisaudiogram.music/tracks/what_i_feel/what_i_feel.mp3" type="audio/mpeg" length="8071829" />
    <itunes:image href="https://mantisaudiogram.music/tracks/what_i_feel/what_i_feel.png" />
    <itunes:duration>3:19</itunes:duration>
  </item>
</channel>

The channel is the artist: their name, site, bio and picture.

  • itunes:image and <image> (Mantis Music 1.1.1): the artist's profile picture, which podcast apps show for the feed (itunes:image) and feed readers use (<image>). Left out when the artist has no profile picture.
  • lastBuildDate changes only when the feed's contents do, so building again without changes writes the same file.
  • podcast:funding (1.5): one per support link, its title cut to 128 characters, so podcast apps that show funding links (Podcasting 2.0) can show them. The podcast namespace is declared only when there are any.

Each item is one work: a song with an MP3 whose release date has come (a song dated later is added by the first publish on or after its date).

  • enclosure (Mantis Music 1.1.1): the song's MP3, audio/mpeg, with its size in bytes. This is what podcast apps play and download.
  • itunes:image (1.1.1): the song's cover, shown for the episode.
  • itunes:duration: the song's length, e.g. 3:19.
  • pubDate: the song's release date, when it's a full date; podcast apps sort and show episodes by it.
  • guid: the address of the song's feed page, site/feed/{slug}.html. A renamed song keeps the guid of its first name (isPermaLink="false", since that page has gone), so podcast apps see the same episode, not a new one.
  • link: the song's feed page, a small readable page for feed readers (internal). content:encoded carries the cover, description and lyrics (left out for an instrumental) and a link to the song's page on the site; description is the plain description.

Older feeds. Feeds made by Mantis Music before 1.1.1 have the song's cover as the enclosure (length="0") and no channel picture, so podcast apps list the songs but can't play them. Use the catalogue for audio.

Not there yet: what Apple's podcast directory asks for before listing a podcast (itunes:category, itunes:explicit, itunes:author, an owner's email, a picture of at least 1400 px). Podcast apps play the feed without them when someone adds it by its address.

9. Pages

Every page (home, About, each work's and release's) carries in <head>:

<link rel="canonical" href="https://site/track/what-i-feel">
<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">
<link rel="alternate" type="application/canimus+json" title="Canimus" href="https://site/canimus.json">

canonical (1.5) is the page's own address (a work's is its @id).

Readable without JavaScript. Each work's and release's page carries its MusicRecording or MusicAlbum as <script type="application/ld+json"> (a work's without its mantis object; a release's with it), and its content inside <main>: title, artist, date, length, cover, description, lyrics, credits, release and links. The site's player replaces it when JavaScript runs; a one-line script in <head> marks JavaScript as present, so the static content never flashes. The home and About pages carry the MusicGroup (without track) and a list of every work, linking to its page.

Renamed songs and releases. A song's or release's address follows its title. When it changes, the old address (track/{old}/, collection/{old}/) keeps a small forwarding page: a meta refresh and a link to the new page, rel="canonical" pointing there, <meta name="robots" content="noindex"> and <meta name="mantis-moved" content="1">. Forwarding pages carry none of the links above, aren't in the sitemap, and give way to a real page if a new song takes the old name.

For crawlers.

  • sitemap.xml lists the home page, the About page and every work's and release's page. Home and About have the build date as <lastmod>; works and releases have their date when it's a full YYYY-MM-DD.
  • robots.txt allows everything and names the sitemap.
  • llms.txt describes the site, links mantis.json, catalogue.json, the RSS feed and the sitemap, and lists every work with its date.

10. Hosting

Any web server that serves static files over HTTPS will do. For fediverse software and browser-based players to read a site, the server should:

  • serve activitypub/* as application/activity+json and .well-known/webfinger as application/jrd+json;
  • send Access-Control-Allow-Origin: * with the site's data (.json, .js, .rss, .xml, .txt, .vtt), audio, pictures and fonts, so other sites' players can read them;
  • let data be cached only briefly (a minute or so), so a new publish shows up straight away;
  • refuse site/publish.json (Mantis's record of the last publish: only the app reads it, through its upload login), any config*.json, hidden files (except .well-known/) and half-uploaded *.mantis-part files.

What Mantis's own server set-up (mantismusic.app/server.sh) installs for nginx:

# never served: hidden files, half-uploaded ones, Mantis's own settings and its publish record
location ~ /\.(?!well-known/) { return 404; }
location ~ \.mantis-part$ { return 404; }
location ~ (^|/)config[^/]*\.json$ { return 404; }
location = /site/publish.json { return 404; }

# pages and data: checked again after a minute; songs, covers and fonts change address (?v=) when they change
location / { try_files $uri $uri/ =404; expires 1m; }
location ~* \.(json|js|css|rss|xml|txt|vtt)$ { add_header Access-Control-Allow-Origin *; expires 1m; }
location ~* \.(mp3|m4a|ogg|opus|wav|jpg|jpeg|png|webp|gif|woff2)$ { add_header Access-Control-Allow-Origin *; expires 1d; }

# the fediverse: proper types, readable from anywhere
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 *; }

On bunny.net, Mantis adds an edge rule that keeps the publish record private.

11. Versioning

  • mantis.json's mantis and the catalogue's mantis.catalogue are major versions. This document is 1.
  • Within a major version, changes only add things: new optional fields, new optional files, new values where a list of values says unknown ones are allowed. Readers ignore what they don't know.
  • A breaking change would raise the major version: the site would serve the new format at the same addresses with the new number, and readers that don't know it would 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 the sites it builds against them.
  • Every minor version's schemas stay at a fixed address that never changes: https://mantismusic.app/docs/schemas/{version}/{file}.schema.json (e.g. …/schemas/1.2/catalogue.schema.json). https://mantismusic.app/docs/schemas/{file}.schema.json is always the newest. This document as it was for a given version is at https://mantismusic.app/docs/site-format/{version}/.

12. Changelog

Every version so far only added optional things, so a reader written for an earlier version keeps working with later sites; it just doesn't see what was added. The sections above describe the current version, and each field there says which version it arrived in. Each version's own copy of this document is at https://mantismusic.app/docs/site-format/{version}/, and its schemas at …/docs/schemas/{version}/.

1.7 (24 Oct 2026): song cues. Each song Mantis can analyse gets site/cues/{slug}.json, linked from the work's mantis.cues: its sections, builds, drops and solos, beats and bars, drum hits and how loud each part is (§4). Visualisers can now follow the music itself, not only the lyrics: the look motion mo=auto follows the cues and became the default (a look string written before 1.7 with no mo meant fixed), and a setting can follow one sound (key=value@sound).

1.6 (22 Oct 2026): richer support links. Each support link gained kind (membership, tip, store, crowdfunding or other), title (the artist's own words) and an optional one-line note, and service gained github-sponsors, stripe, venmo, cash-app, kickstarter and gofundme. name carries the title for 1.5 readers. New buy links stopped being offered (support links cover them); existing ones are still published.

1.5 (22 Oct 2026): support links, and lighter lyric timings. mantis.json → support (also the catalogue's mantis.support, Chorus rel: "support" links and RSS <podcast:funding>) lists where to support the artist; works and releases gained a buy link (Chorus rel: "purchase"). Each song's lyric timings were also published on their own, site/sync/{slug}.json via the work's lyricSync, so a player can load them only for the song it plays. Every page gained rel="canonical".

1.4 (20 Oct 2026): Fairplayer. canimus.json, the older form of Chorus that Fairplayer reads, with feeds.canimus and a link on every page (§6), and the fairplayer-code tag that lets an artist verify their site on Fairplayer.

1.3 (20 Oct 2026): visualiser looks through the song, and Visual stories. A work's visualiserSections gives each lyric section its own look, and story lists pictures the visualiser blends in at moments of the song. Look strings gained scenes (sc, scb), motion through the song (mo) and the picture layer (img, itr, imo, ibl).

1.2 (20 Oct 2026): Chorus. chorus.json and feeds.chorus (§6), so Chorus players can follow Mantis artists. Two Chorus ideas came into the catalogue: audio contentSize and YYYY-MM dates. mantis.json gained formatVersion, so readers know which schemas a site was made against.

1.1 (18 Oct 2026): what the Mantis app needs to draw a site. theme.json (with mantis.json → theme), and on each work its waveform (peaks), cover colours (palette) and visualiser bands (bands); releases gained palette. The catalogue started being written compactly.

1.0 (18 Oct 2026): the first version. mantis.json, catalogue.json, the read-only fediverse files, the RSS feed, pages readable without JavaScript, sitemap.xml, robots.txt and llms.txt.

Changes in Mantis Music that kept the format the same

  • Mantis Music 1.1.1: generator gives the app's real name and version (1.0 and 1.1 always wrote "1.0"). Decimals are written in their shortest form (0.827, not 0.82699999999999996): the same numbers, about half the size. A renamed song or release gets a new address, with a forwarding page at the old one; a song keeps its identifier, and a release its Chorus and Canimus ids. The RSS enclosure is the song's MP3 (it was the cover), each item has its cover as itunes:image, and the channel the artist's picture: the feed now plays in podcast apps (§8). New sites allow directories to list them (directories: ["*"]), and the owners of older sites are asked once.