"""Audio features: beats & onsets (spec M10, lane E). STUB — lane E fills the body.

Contract (frozen at foundation2 merge — phase-5 contract #1):

:func:`run_features` loads the **reference** video's ingest WAV (16 kHz mono from
``config.AUDIO_DIR``; the reference timeline *is* ``t_global``), runs beat/tempo tracking
and onset-strength detection (librosa is already a dependency), and writes
``config.BEATS_JSON``::

    {"tempo_bpm": float | null,
     "beats_s": [float, ...],
     "onsets": [{"t_global_s": float, "strength": float 0..1}, ...],
     "generated_by": "festival4d.audio_features"}

All times are ``t_global`` seconds. Quiet / short / beatless audio must produce a
*valid, empty* result (``tempo_bpm: null``, empty lists) — never a crash. Returns a
small summary dict for the CLI log. ``GET /api/beats`` serves the written file.
"""

from __future__ import annotations


def run_features() -> dict:
    """Analyze the reference soundtrack and write ``data/work/beats.json`` (see module doc)."""
    raise NotImplementedError("audio features (lane E / M10)")