mixing 0.0.76__tar.gz → 0.0.78__tar.gz

{mixing-0.0.76 → mixing-0.0.78}/.claude/CLAUDE.md

@@ -33,7 +33,8 @@ Focused subpackages, each with a clear dependency footprint:
 
 | Module | Purpose | Heavy deps |
 |---|---|---|
-| `mixing.loudness` | array-only loudness: `integrated_lufs(meter=)` (numpy / ffmpeg_ebur128 / pyloudnorm / callable), `level_group`, `limit_peaks` (sample or true peak), `true_peak_db`; `mixing.audio.leveling` builds its `Audio` layer on it | `numpy`, `scipy` (extra `loudness`; no media stack) |
+| `mixing.loudness` | array-only loudness: `integrated_lufs(meter=)` (numpy / ffmpeg_ebur128 / pyloudnorm / callable), `stream_loudness`/`file_loudness` (I + LRA in bounded memory), `level_group`, `limit_peaks` (sample or true peak), `true_peak_db`; `mixing.audio.leveling` builds its `Audio` layer on it | `numpy`, `scipy` (extra `loudness`; no media stack) |
+| `mixing.decode` | `decode_float_chunks`: a file's audio as float chunks at its own rate/channels, through ffmpeg (feeds `mixing.loudness.file_loudness`, bounded memory) | `numpy` + an ffmpeg |
 | `mixing.audio` | `Audio`/`AudioSamples`, fades, crop, concat, overlay, `loop_audio`, `duck_audio`, `find_audio_offset`, segmentation | `pydub`, `numpy`, `scipy` |
 | `mixing.audio.beats` | `beat_grid`/`BeatGrid` — beat/downbeat/onset analysis | `librosa` (extra `beats`, lazy-imported) |
 | `mixing.audio.tagging` | `WindowProbabilities` + `ast_audioset_classifier`: the classifier seam behind `find_segments(strategy="audioset")` (songs vs jingles vs talk on radio shows) | `torch`, `transformers` (extra `ml`, lazy-imported) |
@@ -132,11 +133,13 @@ The base install carries only the pure modules (`srt`, `chapters`, `errors`,
 pydub, numpy, pillow, burns, looks); importing either without it raises an
 `ImportError` naming `pip install 'mixing[media]'` (`util.require_media_extra`,
 called at the top of both package `__init__`s). Tests install it via `testing`.
-`mixing.util.EXTRAS` is the one table of the extras mixing checks for (media,
-ml, beats, loudness → the import names each supplies): `require_extra(feature,
-extra)` and `require_package`'s install hint both read it, so such an extra is
-declared there and in `pyproject.toml` (a test checks every import name's
-distribution is in that extra).
+`mixing.util.EXTRAS` is the one table of mixing's extras (every extra but
+`dev`/`testing` → the import names it supplies): `require_extra(feature,
+extra)` and `require_package`'s install hint both read it, so an extra is
+declared there and in `pyproject.toml` (a test holds the two equal, both
+directions). A module in several extras hints the first; a caller in a narrower
+extra names it: `require_package("scipy.signal", extra=LOUDNESS_EXTRA)`. Never
+hand-write a `pip install` hint for an optional dependency.
 
 `pip install mixing[<extra>]`: `media` (see above), `audio` (ffmpeg-python/soundfile, on top of `media`),
 `loudness` (numpy + scipy, for `mixing.loudness`), `widget` (Jupyter audio widget), `gen` (Veo/`google-genai`), `llm` (`aix`, for

{mixing-0.0.76 → mixing-0.0.78}/.claude/skills/mixing-audio/SKILL.md

@@ -519,7 +519,7 @@ shift_pitch(
 )  # +2 semitones, same duration and loudness
 ```
 
-- `voice_profile`: `f0_hz` is the median f0 over voiced frames of `f0_tracker` (default `pyin_tracker()`, needs `mixing[beats]`; `f0=False` skips it). Configure pyin through the tracker, `f0_tracker=pyin_tracker(fmin=50, fmax=400, min_voiced_prob=0.2)` (the same arguments on `voice_profile` are deprecated). Default range 65-600 Hz; a voice above `fmax` reads as a subharmonic. Spans shorter than the tracker's `min_samples` (pyin: one 128 ms frame) give `f0_hz=None, voiced_fraction=None`. Any `(mono samples, rate) -> (f0 per frame, voiced flags)` callable is a tracker; it applies its own voicing threshold, e.g. over `denote`:
+- `voice_profile`: `f0_hz` is the median f0 over voiced frames of `f0_tracker` (default `pyin_tracker()`, needs `mixing[beats]`; `f0=False` skips it). Configure pyin through the tracker, `f0_tracker=pyin_tracker(fmin=50, fmax=400, min_voiced_prob=0.2)` (`voice_profile` itself no longer takes them). Default range 65-600 Hz; a voice above `fmax` reads as a subharmonic. Spans shorter than the tracker's `min_samples` (pyin: one 128 ms frame) give `f0_hz=None, voiced_fraction=None`. Any `(mono samples, rate) -> (f0 per frame, voiced flags)` callable is a tracker; it applies its own voicing threshold, e.g. over `denote`:
 
   ```python
   def denote_tracker(*, threshold=0.5, **kwargs):

{mixing-0.0.76 → mixing-0.0.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mixing
-Version: 0.0.76
+Version: 0.0.78
 Summary: Tools for video and audio editing
 Project-URL: Homepage, https://github.com/thorwhalen/mixing
 Author: Thor Whalen

{mixing-0.0.76 → mixing-0.0.78}/mixing/audio/audio_widget.py

@@ -6,11 +6,31 @@ import logging
 import numpy as np
 from pathlib import Path
 from typing import Union, Tuple, Optional
-from IPython.display import display, HTML
+
+from ..util import WIDGET_EXTRA, install_hint
+
+try:
+    from IPython.display import display, HTML
+except ImportError as e:
+    raise ImportError(
+        f"The audio widget needs Jupyter: {install_hint(WIDGET_EXTRA)}", name=e.name
+    ) from e
 
 logger = logging.getLogger(__name__)
 
 
+def _soundfile():
+    """``soundfile``, or an ``ImportError`` naming the ``widget`` extra."""
+    try:
+        import soundfile
+    except ImportError as e:
+        raise ImportError(
+            f"soundfile is required for the audio widget: {install_hint(WIDGET_EXTRA)}",
+            name="soundfile",
+        ) from e
+    return soundfile
+
+
 # Type aliases
 WaveformArray = (
     np.ndarray
@@ -49,13 +69,7 @@ def ensure_wfsr(audio_input: AudioInput) -> WfSr:
         >>> wf, sr = ensure_wfsr(audio_bytes)  # doctest: +SKIP
         >>> wf, sr = ensure_wfsr((wf, sr))  # doctest: +SKIP
     """
-    try:
-        import soundfile as sf
-    except ImportError:
-        raise ImportError(
-            "soundfile is required for audio processing. "
-            "Install it with: pip install soundfile"
-        )
+    sf = _soundfile()
 
     # Already in (wf, sr) format
     if isinstance(audio_input, tuple) and len(audio_input) == 2:
@@ -99,10 +113,7 @@ def wf_to_base64_wav(wf: WaveformArray, sr: SampleRate) -> str:
     Returns:
         Base64-encoded data URL string suitable for HTML audio element
     """
-    try:
-        import soundfile as sf
-    except ImportError:
-        raise ImportError("soundfile required for audio encoding")
+    sf = _soundfile()
 
     # Ensure wf is in proper format
     if wf.dtype != np.float32 and wf.dtype != np.float64:
@@ -653,10 +664,7 @@ __temp_sel_end = ${{sel.end}}
             filepath: Output file path
             format: Audio format (auto-detected from extension if None)
         """
-        try:
-            import soundfile as sf
-        except ImportError:
-            raise ImportError("soundfile required for saving audio")
+        sf = _soundfile()
 
         filepath = Path(filepath)
 

{mixing-0.0.76 → mixing-0.0.78}/mixing/audio/leveling.py

@@ -8,6 +8,10 @@ every speaker turn of a recording to the same loudness, which whole-track peak
 normalisation (:meth:`Audio.normalize`) cannot do. ``loudness_range`` (EBU
 Tech 3342 LRA) and ``true_peak_db`` (4x oversampled) sit beside it.
 
+This module is the :class:`Audio` layer. The array-level pieces (the BS.1770
+constants, ``numpy_lufs``, ``level_group``, ``limit_peaks``) live in
+:mod:`mixing.loudness` and are not re-exported here: import them from there.
+
 ``level_turns`` is :func:`mixing.audio.turns.process_turns` with a chain of
 stages per turn, all run on the turn padded by ``pad_s`` (so filters settle):
 the speaker's EQ -> pre-gain to a common level -> compressor -> gain to

{mixing-0.0.76 → mixing-0.0.78}/mixing/audio/voice.py

@@ -268,20 +268,6 @@ def _voiced_f0(
     return (float(np.median(values)) if len(values) else None), len(values) / n_frames
 
 
-def _deprecated_pyin_args(**kwargs) -> dict:
-    """The pyin arguments ``voice_profile`` was given (``None`` = not given),
-    with a ``DeprecationWarning`` when there are any."""
-    given = {k: v for k, v in kwargs.items() if v is not None}
-    if given:
-        warnings.warn(
-            f"voice_profile({', '.join(given)}=...) is deprecated and will be "
-            "removed (reeleehq/mixing#99); pass f0_tracker=pyin_tracker(...) instead",
-            DeprecationWarning,
-            stacklevel=3,
-        )
-    return given
-
-
 def voice_profile(
     audio: Union[str, Path, Audio],
     spans: Optional[Spans] = None,
@@ -291,10 +277,6 @@ def voice_profile(
     f0_sample_rate: int = DEFAULT_F0_SAMPLE_RATE,
     low_band: Span = DEFAULT_LOW_BAND_HZ,
     welch_nperseg: int = DEFAULT_WELCH_NPERSEG,
-    fmin: Optional[float] = None,
-    fmax: Optional[float] = None,
-    f0_frame_length: Optional[int] = None,
-    min_voiced_prob: Optional[float] = None,
 ) -> dict:
     """Pitch, loudness and timbre of each labelled part of ``audio``.
 
@@ -318,8 +300,6 @@ def voice_profile(
         f0_sample_rate: the rate spans are resampled to before tracking.
         low_band: ``(lo_hz, hi_hz)`` of the band reported by ``low_band_db``.
         welch_nperseg: Welch segment length for centroid and low-band ratio.
-        fmin, fmax, f0_frame_length, min_voiced_prob: deprecated; pass them to
-            :func:`pyin_tracker` as ``f0_tracker``.
 
     Returns:
         ``{label: {...}}`` of plain JSON-able dicts with keys
@@ -343,19 +323,8 @@ def voice_profile(
     fs = segment.frame_rate
     data = segment_samples(segment)
     grouped = _spans_by_label(spans, len(data) / fs)
-    pyin_args = _deprecated_pyin_args(
-        fmin=fmin,
-        fmax=fmax,
-        frame_length=f0_frame_length,
-        min_voiced_prob=min_voiced_prob,
-    )
     if f0_tracker is None:
-        f0_tracker = pyin_tracker(**pyin_args)
-    elif f0 and pyin_args:
-        raise ValueError(
-            "fmin, fmax, f0_frame_length and min_voiced_prob configure the default "
-            "pyin tracker only; pass them to pyin_tracker() as f0_tracker"
-        )
+        f0_tracker = pyin_tracker()
 
     def profile(ranges) -> dict:
         frames = [

{mixing-0.0.76 → mixing-0.0.78}/mixing/chapters.py

@@ -21,6 +21,7 @@ from dataclasses import dataclass
 from typing import Callable, Sequence
 
 from mixing.srt import parse_srt as _parse_srt
+from mixing.util import require_llm_chat
 
 #: A segmenter maps (segments, target_count) -> [{"start": float, "title": str}].
 #: ``segments`` is a list of ``{"start", "end", "text"}`` sentence-ish units.
@@ -254,13 +255,9 @@ def default_segment_fn(
     boundaries as a JSON array of ``{"start", "title"}``. Pass your own
     ``segment_fn`` to :func:`detect_chapters` to avoid the ``aix`` dependency.
     """
-    try:
-        from aix import chat
-    except ImportError as e:  # pragma: no cover - environment dependent
-        raise ImportError(
-            "default_segment_fn needs the 'aix' package. Install it, or pass a "
-            "custom segment_fn to detect_chapters()."
-        ) from e
+    chat = require_llm_chat(
+        "default_segment_fn", alternative="segment_fn to detect_chapters()"
+    )
 
     lines = "\n".join(f"[{_fmt(s['start'])}] {s['text']}" for s in segments)
     prompt = (

mixing-0.0.78/mixing/decode.py

@@ -0,0 +1,99 @@
+"""Decode a media file's audio as a stream of float chunks, through ffmpeg.
+
+:func:`decode_float_chunks` runs ffmpeg once and hands back the sample rate
+and an iterator of ``(k, channels)`` float32 arrays in [-1, 1], at the file's
+own rate and channel count (no resample, no downmix). Only a chunk is held
+at a time, so a consumer such as :func:`mixing.loudness.stream_loudness`
+works on an hour-long track in bounded memory. Needs numpy and an ffmpeg
+(:func:`mixing.util.ffmpeg_exe`), not the media stack.
+"""
+
+from __future__ import annotations
+
+import struct
+import subprocess
+import tempfile
+from typing import Iterator, Optional
+
+from mixing.util import LOUDNESS_EXTRA, ffmpeg_exe, install_hint
+
+try:
+    import numpy as np
+except ImportError as e:
+    raise ImportError(
+        f"mixing.decode needs numpy: {install_hint(LOUDNESS_EXTRA)}", name=e.name
+    ) from e
+
+#: Seconds of audio per chunk by default.
+DECODE_CHUNK_S = 5.0
+#: ffmpeg writes the stream as 32-bit float WAV (its header gives rate and
+#: channels).
+_WAV_CODEC = "pcm_f32le"
+_SAMPLE_BYTES = 4
+
+
+def _wav_format(stream) -> tuple[int, int]:
+    """``(channels, rate)`` from a streamed WAV header, read up to its ``data``
+    chunk (ffmpeg writes unknown sizes when piping, so they are not used)."""
+    header = stream.read(12)
+    if len(header) < 12 or header[:4] != b"RIFF" or header[8:12] != b"WAVE":
+        raise ValueError("not a WAV stream")
+    channels = rate = None
+    while True:
+        chunk = stream.read(8)
+        if len(chunk) < 8:
+            raise ValueError("WAV stream ended before its data chunk")
+        name, size = chunk[:4], struct.unpack("<I", chunk[4:])[0]
+        if name == b"data":
+            if channels is None:
+                raise ValueError("WAV stream has no fmt chunk")
+            return channels, rate
+        body = stream.read(size + size % 2)
+        if name == b"fmt ":
+            channels, rate = struct.unpack("<HI", body[2:8])
+
+
+def _decode(path, chunk_s: float, ffmpeg: Optional[str]):
+    """First ``(channels, rate)``, then the float chunks."""
+    cmd = [
+        ffmpeg or ffmpeg_exe(), "-nostdin", "-v", "error", "-i", str(path), "-vn",
+        "-map", "0:a:0", "-c:a", _WAV_CODEC, "-f", "wav", "-",
+    ]  # fmt: skip
+    # stderr to a file: a pipe nobody reads fills up and blocks ffmpeg
+    with tempfile.TemporaryFile() as errors:
+        with subprocess.Popen(
+            cmd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=errors
+        ) as proc:
+            try:
+                channels, rate = _wav_format(proc.stdout)
+            except ValueError:
+                channels = None
+            if channels is not None:
+                yield channels, rate
+                frame = _SAMPLE_BYTES * channels
+                step = max(1, int(round(chunk_s * rate))) * frame
+                while block := proc.stdout.read(step):
+                    usable = len(block) - len(block) % frame
+                    yield np.frombuffer(block[:usable], "<f4").reshape(-1, channels)
+        if proc.returncode != 0 or channels is None:
+            errors.seek(0)
+            message = errors.read().decode(errors="replace")
+            raise RuntimeError(
+                f"ffmpeg could not decode the audio of {path!s}: {message}"
+            )
+
+
+def decode_float_chunks(
+    path, *, chunk_s: float = DECODE_CHUNK_S, ffmpeg: Optional[str] = None
+) -> tuple[int, Iterator[np.ndarray]]:
+    """``(rate, chunks)``: the first audio stream of ``path`` as float32 chunks.
+
+    Each chunk is ``(k, channels)`` with ``k`` up to ``chunk_s * rate``. ffmpeg
+    (``ffmpeg``, default :func:`mixing.util.ffmpeg_exe`) starts at once; it is
+    stopped when the iterator is exhausted or closed. Raises ``RuntimeError``
+    (with ffmpeg's message) when the file has no decodable audio, here or,
+    for a stream that breaks partway, from the iterator.
+    """
+    chunks = _decode(path, chunk_s, ffmpeg)
+    _, rate = next(chunks)
+    return rate, chunks

{mixing-0.0.76 → mixing-0.0.78}/mixing/dubbing/srt.py

@@ -16,6 +16,7 @@ from typing import Callable, Sequence
 
 # Canonical SRT primitives (re-exported for backward compatibility).
 from mixing.srt import Cue, dump_srt, parse_srt, srt_time_to_seconds
+from mixing.util import require_llm_chat
 
 __all__ = [
     "Cue",
@@ -84,13 +85,9 @@ def default_translate_fn(
     one-to-one mapping with the input cues is preserved. Falls back to a clear
     error if ``aix`` is not importable — pass your own ``translate_fn`` then.
     """
-    try:
-        from aix import chat  # provider-agnostic LLM interface
-    except ImportError as e:  # pragma: no cover - depends on environment
-        raise ImportError(
-            "default_translate_fn needs the 'aix' package for LLM translation. "
-            "Install aix, or pass a custom translate_fn to translate_srt()."
-        ) from e
+    chat = require_llm_chat(
+        "default_translate_fn", alternative="translate_fn to translate_srt()"
+    )
 
     import json as _json