# Content Type: Audio

Changes to how this Type behaves are requested through a GitHub Issue and implemented, together with this reference page, through the repository's normal workflow. See /_docs/posts for how Content Types, Roles, and Rank work in general, and docs/Internal/type-doc-templates.md for the Content Type Doc template this file follows.

An audio clip attached to a Post — a field recording, a voice note, a podcast excerpt. Same shape and behavior as Image and Video.

## Where it comes from

Ingested one of three ways — see /_docs/media for the full mechanics:

- **Upload** — a file, drag-dropped, pasted, or chosen from a file picker. Local Upload/Fetch by URL is restricted to **MP3 and M4A** — the file's actual contents are verified, not just its name/extension.
- **Fetch by URL** — paste a URL and the server downloads and stores the file itself. Same MP3/M4A restriction as Upload.
- **Embed** — a hand-provided embed snippet (e.g. a Spotify embed code), keeping the audio off-site entirely. An embedded Audio clip has no local file at all, and isn't subject to the MP3/M4A restriction.

## Fields

- **The audio itself** (mandatory) — a locally-stored file (Upload/Fetch by URL) or an embed snippet (Embed). Stored and served verbatim — no transcoding to a different format yet (see /_docs/roadmap). Immutable once created, same as every Content Type.
- **Caption / label** (key optional) — text shown alongside the clip.
- **Descriptive metadata** (optional) — a label, description, alt text, creator/attribution, rights, source label, and source URL, the same field set Image has. The **description** and **creator** fields feed directly into the public caption shown below every inline player; the **source label**/**source URL** pair (Via-link) is a plain editable field pair here — not a real, health-checked managed Link — see "Semantic HTML and accessibility" below for why.
- **Technical metadata** (specialist) — for a locally-stored Audio clip only: duration, container/codec, sample rate, channel count, bit rate, and embedded title/artist/album tags where present. Extracted automatically after upload, best-effort — never blocks or invalidates the upload, and never overwrites Caption/Role/Reference; embedded tags are descriptive only, never treated as authoritative editorial metadata. Shown read-only on the element's metadata page and in Admin diagnostics.

## Semantic HTML and accessibility

Renders as a native `<audio controls>` (`MediaElement.tsx`) for a locally-stored Audio clip, or the admin-provided embed snippet verbatim for an Embed row. No transcript is generated or attached — a visitor relies on the Caption/Description field's plain visible text, not a synced or downloadable transcript.

A composed caption — "Description *(Credit: Creator, via Source)*," each part omitted when absent — renders directly below every inline player, as ordinary visible text, when there's anything to show. Immediately below that (or below the bare player) is an **Info** link/control to this Audio clip's own standalone metadata page: a right-aligned text link below the player, since this codebase's native `<audio controls>` has no reliable, accessible way to add a custom icon into its own browser-drawn control bar.

In the Additional Information Media group specifically (see "Rendering contexts" below), an Audio clip's Description is shown as hover text (a `title` attribute) *and* as a real, non-hover accessible name (`aria-label`) reachable by keyboard/touch/assistive technology — never hover-only. When Description is empty, a concise generic fallback label is used instead, so an Audio tile is never blank or unlabeled.

**Compact tile information control:** wherever an Audio clip is shown as a compact grid/matrix tile — Additional Information's Media group, Gallery's own matrix, and the social Post Types' inline Media grid (see "Rendering contexts" below) — the tile is wrapped in the same hover overlay Image's own tile uses, exposing a small "i" **Audio information** control on pointer hover, on keyboard focus, and permanently on touch devices (no hover state there to reveal it) — same position, size, and contrast as Image's own overlay control, reusing its exact styling. It's a separate, independently-labeled control alongside the tile's own link, not nested inside it, so activating it never interferes with selecting the tile itself; both currently lead to the same standalone metadata page, since a compact Audio tile has no separate in-place preview to distinguish them from.

## Role, Rank, and Reference

A Post can hold several Audio clips at once, each with its own Role, or several sharing the same Role, distinguished by Rank — see /_docs/posts. Every Audio clip also has an optional **Reference** — a separate, Post-unique name for addressing it inline instead of by Role/Rank — see /_docs/posts's "Reference: inline addressing" for the full detail.

## Editing

In the admin Post editor, the Audio section holds one block per clip, with the same Upload / Fetch by URL / Embed controls, Role field, Position (Rank) field, caption field, and Metadata section (Description/Author/Via-link) as Images and Videos. Every Post Type's editor shows the same Audio section regardless of which Type is active.

## Rendering contexts

### Inline

A single-Role Audio clip can be inline-embedded from markdown the same way as an Image, e.g. `{{field-recording}}` — see /_docs/markdown for the full content reference syntax. The composed Description/Author/Via-link caption and the Info link (see "Semantic HTML and accessibility," above) both render here too, exactly as they do everywhere else this Type appears.

### Additional Information "Media" group

Every Post Type's shared Additional Information container has one combined **Media** mini-gallery holding every eligible Image, Video, and Audio together, in Rank-then-stable-order. An Audio clip's own tile is a recognizable, compact Audio icon — no waveform, artwork, or embedded player here, and no separate "Audio" section of its own. Selecting it opens the clip's own standalone metadata page, where it can actually be played; the same tile also exposes the hover/focus/touch "i" information control described above, to the same destination. Audio keeps the ordinary "shown once" rule — no duplication exception.

### Post metadata-page traversal

Every Audio clip the Post has ever held (current Version, or full history via `/metadata/history`) is enumerated with its caption, descriptive metadata, and URL as JSON-LD/native JSON — see /_docs/posts's Metadata page section.

### Standalone Content Element page

`/_element/audio/:id` shows the clip itself, its composed Description/Author/Via-link caption (Description always shown as ordinary visible text here, not just hover text), and its available normalized technical metadata (duration, sample rate, codec, channel count, embedded tags, and so on — absent fields simply omitted), gated exactly like the owning Post's own page.