AudioAnalysisResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/freqblog-com/json-schema/freqblog-com-audio-analysis-response-schema.json",
  "title": "AudioAnalysisResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/freqblog-com-openapi.json#/components/schemas/AudioAnalysisResponse",
  "properties": {
    "bpm": {
      "type": "number",
      "maximum": 300.0,
      "minimum": 20.0,
      "title": "Bpm",
      "description": "Tempo in beats per minute. Same field name/role as `tempo` in Spotify's response shape."
    },
    "bpm_alt": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bpm Alt",
      "description": "Half-time corrected alternative BPM (twice the detected `bpm`), when our heuristic is fairly confident the detector locked onto half the beat grid. Only offered for tracks detected at 70-88 BPM; null otherwise. Never replaces `bpm`. Drum & bass is the one exception: a track detected at 108-122 BPM gets 1.5x the detected `bpm` (e.g. 115 -> 172.5), because the detector often reads a 174 BPM break at two-thirds speed."
    },
    "bpm_confidence": {
      "type": "number",
      "title": "Bpm Confidence",
      "description": "Beat-strength score from Essentia's RhythmExtractor2013. Higher = stronger rhythmic pulse. Range about 0–5.3, catalogue median ~2.9. Values below 1.0 indicate weak or absent rhythm (ambient, spoken word)."
    },
    "key": {
      "type": "string",
      "title": "Key",
      "description": "Musical key and scale as a human-readable string, e.g. `A-Minor` or `F#-Major`. Combines Spotify's integer `key` + `mode` fields into one readable value."
    },
    "key_confidence": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Key Confidence",
      "description": "Key detection confidence [0–1]. Below 0.4 indicates atonal, modal, or harmonically ambiguous content."
    },
    "mode": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Mode",
      "description": "Musical mode as a Spotify-compatible integer: `0` = minor, `1` = major. Direct drop-in for Spotify's deprecated `mode` field."
    },
    "key_int": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 11.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Key Int",
      "description": "Pitch-class integer for the key, Spotify-compatible: `0` = C, `1` = C♯/D♭, `2` = D, … `11` = B. `null` when the key is undetected/atonal (Spotify used `-1`)."
    },
    "camelot": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Camelot",
      "description": "Camelot wheel notation for harmonic mixing, e.g. `8A` (A-Minor) or `5B` (D-Major). Used by DJs to find harmonically compatible tracks. A = minor keys, B = major keys. Numbers 1–12."
    },
    "open_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Open Key",
      "description": "Open Key notation for harmonic mixing, e.g. `1m` (A-Minor) or `1d` (C-Major). Alternative to Camelot — used by Serato DJ and Mixed In Key. d = major (dominant), m = minor. Numbers 1–12."
    },
    "acousticness": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Acousticness",
      "description": "Acousticness [0–1]. Where the recording has AcousticBrainz features we serve their trained-classifier value. Otherwise, a model that listens to the preview (PANNs embeddings, CC BY 4.0, trained on AcousticBrainz's CC0 labels) as each track is re-analysed since 2026-09-27, most-requested first; tracks not yet reached carry our spectral-flatness estimate rescaled onto the same distribution, which is a sorting signal rather than a verdict on one track."
    },
    "danceability": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Danceability",
      "description": "How suitable the track is for dancing [0–1], on AcousticBrainz's scale: its own classifier value where the recording has AcousticBrainz features, otherwise a model that listens to the preview (PANNs embeddings, CC BY 4.0, trained on AcousticBrainz's CC0 labels). Rolling out since 2026-09-27, most-requested first; tracks not yet reached carry our earlier tempo/beat-strength estimate. Re-derive thresholds rather than copying them from another service."
    },
    "instrumentalness": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Instrumentalness",
      "description": "Likelihood the 30-second preview contains no vocals [0–1] (above 0.5 = likely instrumental), from a PANNs-based model trained on the vocal/no-vocal labels of the MUSAN corpus (Snyder et al. 2015, CC BY 4.0). Describes the preview, not the whole track. Null where a track has not been through the model yet."
    },
    "liveness": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Liveness",
      "description": "Likelihood the track was performed live [0–1]. **Null for tracks from our own audio analysis**: our signal-based estimate was not reliable enough to serve (it read most studio recordings as live), so we return null rather than a misleading value. Populated where an external source supplies it."
    },
    "speechiness": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Speechiness",
      "description": "Presence of spoken words [0–1] (above ~0.33 = rap or mixed speech, above ~0.66 = mostly spoken). **Null for tracks from our own audio analysis**: our signal-based estimate was not reliable enough to serve, so we return null rather than a misleading value. Populated where an external source supplies it."
    },
    "valence": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Valence",
      "description": "Musical positiveness [0–1]. High = happy/euphoric, low = sad/dark. Estimated from scale, tempo, brightness and energy — a coarse signal; treat it as a sorting aid rather than a per-track verdict."
    },
    "mood": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mood",
      "description": "MIREX-style mood category derived from valence and energy. One of: happy, calm, sad, tense, energetic, melancholic, neutral. Maps the four-quadrant mood model: high valence + high energy = happy; low valence + high energy = tense; etc."
    },
    "representative_segment_start": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Representative Segment Start",
      "description": "Start time in seconds of the highest-energy 30-second window. Identifies the most sonically representative (e.g. chorus or drop) segment. Useful for sync licensing, preview generation, and waveform thumbnails. 0.0 for tracks ≤ 30 s."
    },
    "rms_energy": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Rms Energy",
      "description": "Perceptual intensity [0–1] from RMS loudness, on our own scale (loud masters sit near the top of it). Computed over the same 30-second window as BPM and key."
    },
    "loudness_db": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Loudness Db",
      "description": "Integrated loudness in dBFS (decibels relative to full scale). Same field role as `loudness` in Spotify's response shape. Typical mastered pop/electronic: -10 to -5 dBFS. Quiet/acoustic: -20 to -15."
    },
    "time_signature": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Time Signature",
      "description": "Beats per bar. ASSUMED 4 (4/4) for every analysed track, not measured: no meter estimator we have tested beats a constant 4 on a mostly 4/4 catalogue. Same field role as `time_signature` in Spotify's response shape, kept for compatibility; do not filter or branch on it."
    },
    "mood_vector": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "number"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mood Vector",
      "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise. Use these for fine-grained mood filtering beyond the single-label `mood` field."
    },
    "cached": {
      "type": "boolean",
      "title": "Cached",
      "description": "True if this result was served from the server-side cache. Cached responses are < 100 ms. The underlying analysis is identical to a fresh result.",
      "default": false
    },
    "bpm_snapped": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bpm Snapped",
      "description": "`bpm` rounded to a whole number — the grid tempo, in the form every DJ tool reports. Traktor, Serato and Rekordbox return clean integers because they derive a BEAT GRID, and a grid has exactly one tempo by construction; our `bpm` is a *measurement* of the audio, so it carries a decimal. For grid-produced music the true tempo is almost certainly the whole number and the decimal is our error — `bpm_confidence` correlates with how close we land to an integer, which is the evidence for that. **Always populated, never null.** Use `bpm` when you want the measurement (beatmatching by ear, where 127.89 vs 128.00 is the point) and `bpm_confidence` to judge how far to trust either.",
      "readOnly": true
    }
  },
  "type": "object",
  "required": [
    "bpm",
    "bpm_confidence",
    "key",
    "key_confidence",
    "rms_energy",
    "bpm_snapped"
  ]
}