mixing 0.0.77__tar.gz → 0.0.78__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. {mixing-0.0.77 → mixing-0.0.78}/.claude/CLAUDE.md +7 -5
  2. {mixing-0.0.77 → mixing-0.0.78}/PKG-INFO +1 -1
  3. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/audio_widget.py +24 -16
  4. {mixing-0.0.77 → mixing-0.0.78}/mixing/chapters.py +4 -7
  5. {mixing-0.0.77 → mixing-0.0.78}/mixing/dubbing/srt.py +4 -7
  6. {mixing-0.0.77 → mixing-0.0.78}/mixing/loudness.py +4 -6
  7. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_base_install.py +162 -23
  8. {mixing-0.0.77 → mixing-0.0.78}/mixing/util.py +65 -15
  9. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/genai.py +4 -3
  10. {mixing-0.0.77 → mixing-0.0.78}/pyproject.toml +1 -1
  11. {mixing-0.0.77 → mixing-0.0.78}/.claude/agents/mixing-dev.md +0 -0
  12. {mixing-0.0.77 → mixing-0.0.78}/.claude/agents/mixing-editor.md +0 -0
  13. {mixing-0.0.77 → mixing-0.0.78}/.claude/skills/mixing/SKILL.md +0 -0
  14. {mixing-0.0.77 → mixing-0.0.78}/.claude/skills/mixing-audio/SKILL.md +0 -0
  15. {mixing-0.0.77 → mixing-0.0.78}/.claude/skills/mixing-dubbing/SKILL.md +0 -0
  16. {mixing-0.0.77 → mixing-0.0.78}/.claude/skills/mixing-transcript/SKILL.md +0 -0
  17. {mixing-0.0.77 → mixing-0.0.78}/.claude/skills/mixing-video/SKILL.md +0 -0
  18. {mixing-0.0.77 → mixing-0.0.78}/.github/workflows/ci.yml +0 -0
  19. {mixing-0.0.77 → mixing-0.0.78}/.gitignore +0 -0
  20. {mixing-0.0.77 → mixing-0.0.78}/LICENSE +0 -0
  21. {mixing-0.0.77 → mixing-0.0.78}/README.md +0 -0
  22. {mixing-0.0.77 → mixing-0.0.78}/conftest.py +0 -0
  23. {mixing-0.0.77 → mixing-0.0.78}/misc/README_audio_widget.md +0 -0
  24. {mixing-0.0.77 → mixing-0.0.78}/misc/audio_widget_EXAMPLE_NOTEBOOK.md +0 -0
  25. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_bgremove_efficient.gif +0 -0
  26. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_bgremove_kodokan.gif +0 -0
  27. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_cartoon_C.gif +0 -0
  28. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_facexform_animegan.gif +0 -0
  29. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_facexform_sticker.gif +0 -0
  30. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_redact_blur.gif +0 -0
  31. {mixing-0.0.77 → mixing-0.0.78}/misc/discussion_media/video_editing/pair_stylize_B1.gif +0 -0
  32. {mixing-0.0.77 → mixing-0.0.78}/misc/examples/audio_offset_example.py +0 -0
  33. {mixing-0.0.77 → mixing-0.0.78}/misc/examples/demo_audio_widget.py +0 -0
  34. {mixing-0.0.77 → mixing-0.0.78}/mixing/__init__.py +0 -0
  35. {mixing-0.0.77 → mixing-0.0.78}/mixing/_cache.py +0 -0
  36. {mixing-0.0.77 → mixing-0.0.78}/mixing/_elevenlabs.py +0 -0
  37. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/__init__.py +0 -0
  38. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/_pcm.py +0 -0
  39. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/audio_ops.py +0 -0
  40. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/audio_util.py +0 -0
  41. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/beats.py +0 -0
  42. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/leveling.py +0 -0
  43. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/samples.py +0 -0
  44. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/segmentation.py +0 -0
  45. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/tagging.py +0 -0
  46. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/talk_edges.py +0 -0
  47. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/turns.py +0 -0
  48. {mixing-0.0.77 → mixing-0.0.78}/mixing/audio/voice.py +0 -0
  49. {mixing-0.0.77 → mixing-0.0.78}/mixing/decode.py +0 -0
  50. {mixing-0.0.77 → mixing-0.0.78}/mixing/dubbing/__init__.py +0 -0
  51. {mixing-0.0.77 → mixing-0.0.78}/mixing/dubbing/dub.py +0 -0
  52. {mixing-0.0.77 → mixing-0.0.78}/mixing/dubbing/tts.py +0 -0
  53. {mixing-0.0.77 → mixing-0.0.78}/mixing/egress.py +0 -0
  54. {mixing-0.0.77 → mixing-0.0.78}/mixing/errors.py +0 -0
  55. {mixing-0.0.77 → mixing-0.0.78}/mixing/filtergraph.py +0 -0
  56. {mixing-0.0.77 → mixing-0.0.78}/mixing/srt.py +0 -0
  57. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/data/talk_edges_labels.json +0 -0
  58. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_adaptive_window.py +0 -0
  59. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_aligned_spans.py +0 -0
  60. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_alignment_features.py +0 -0
  61. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_alignment_ingest.py +0 -0
  62. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_alignment_margin.py +0 -0
  63. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_ambient_bed.py +0 -0
  64. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_audio_alignment.py +0 -0
  65. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_audio_ops.py +0 -0
  66. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_audio_widget.py +0 -0
  67. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_beats.py +0 -0
  68. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_chapters.py +0 -0
  69. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_collision_detection.py +0 -0
  70. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_cutaways.py +0 -0
  71. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_dubbing.py +0 -0
  72. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_egress.py +0 -0
  73. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_filtergraph.py +0 -0
  74. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_gif_and_crop_box.py +0 -0
  75. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_audio_class.py +0 -0
  76. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_audio_ops_more.py +0 -0
  77. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_chapters_more.py +0 -0
  78. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_no_print.py +0 -0
  79. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_srt_and_persist.py +0 -0
  80. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_thumbnail.py +0 -0
  81. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_video_class.py +0 -0
  82. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_video_ops_more.py +0 -0
  83. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_guard_video_util.py +0 -0
  84. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_ken_burns.py +0 -0
  85. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_leveling.py +0 -0
  86. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_loudness.py +0 -0
  87. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_overlay_mix.py +0 -0
  88. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_scribe_cache.py +0 -0
  89. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_segmentation.py +0 -0
  90. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_segmentation_audioset.py +0 -0
  91. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_shots.py +0 -0
  92. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_srt_vtt.py +0 -0
  93. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_support_statistic.py +0 -0
  94. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_talk_edges.py +0 -0
  95. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_transcript.py +0 -0
  96. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_tts_api_key.py +0 -0
  97. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_tts_cache_status.py +0 -0
  98. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_util.py +0 -0
  99. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_video_audio_integration.py +0 -0
  100. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_video_transitions.py +0 -0
  101. {mixing-0.0.77 → mixing-0.0.78}/mixing/tests/test_voice.py +0 -0
  102. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/__init__.py +0 -0
  103. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/fillers.py +0 -0
  104. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/formats.py +0 -0
  105. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/media.py +0 -0
  106. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/persist.py +0 -0
  107. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/pipeline.py +0 -0
  108. {mixing-0.0.77 → mixing-0.0.78}/mixing/transcript/scribe.py +0 -0
  109. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/README.md +0 -0
  110. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/__init__.py +0 -0
  111. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/_helpers.py +0 -0
  112. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/cutaways.py +0 -0
  113. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/gif.py +0 -0
  114. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/shot_boundaries.py +0 -0
  115. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/thumbnail.py +0 -0
  116. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/video_concat.py +0 -0
  117. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/video_ops.py +0 -0
  118. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/video_subtitles.py +0 -0
  119. {mixing-0.0.77 → mixing-0.0.78}/mixing/video/video_util.py +0 -0
@@ -133,11 +133,13 @@ The base install carries only the pure modules (`srt`, `chapters`, `errors`,
133
133
  pydub, numpy, pillow, burns, looks); importing either without it raises an
134
134
  `ImportError` naming `pip install 'mixing[media]'` (`util.require_media_extra`,
135
135
  called at the top of both package `__init__`s). Tests install it via `testing`.
136
- `mixing.util.EXTRAS` is the one table of the extras mixing checks for (media,
137
- ml, beats, loudness → the import names each supplies): `require_extra(feature,
138
- extra)` and `require_package`'s install hint both read it, so such an extra is
139
- declared there and in `pyproject.toml` (a test checks every import name's
140
- distribution is in that extra).
136
+ `mixing.util.EXTRAS` is the one table of mixing's extras (every extra but
137
+ `dev`/`testing` → the import names it supplies): `require_extra(feature,
138
+ extra)` and `require_package`'s install hint both read it, so an extra is
139
+ declared there and in `pyproject.toml` (a test holds the two equal, both
140
+ directions). A module in several extras hints the first; a caller in a narrower
141
+ extra names it: `require_package("scipy.signal", extra=LOUDNESS_EXTRA)`. Never
142
+ hand-write a `pip install` hint for an optional dependency.
141
143
 
142
144
  `pip install mixing[<extra>]`: `media` (see above), `audio` (ffmpeg-python/soundfile, on top of `media`),
143
145
  `loudness` (numpy + scipy, for `mixing.loudness`), `widget` (Jupyter audio widget), `gen` (Veo/`google-genai`), `llm` (`aix`, for
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: mixing
3
- Version: 0.0.77
3
+ Version: 0.0.78
4
4
  Summary: Tools for video and audio editing
5
5
  Project-URL: Homepage, https://github.com/thorwhalen/mixing
6
6
  Author: Thor Whalen
@@ -6,11 +6,31 @@ import logging
6
6
  import numpy as np
7
7
  from pathlib import Path
8
8
  from typing import Union, Tuple, Optional
9
- from IPython.display import display, HTML
9
+
10
+ from ..util import WIDGET_EXTRA, install_hint
11
+
12
+ try:
13
+ from IPython.display import display, HTML
14
+ except ImportError as e:
15
+ raise ImportError(
16
+ f"The audio widget needs Jupyter: {install_hint(WIDGET_EXTRA)}", name=e.name
17
+ ) from e
10
18
 
11
19
  logger = logging.getLogger(__name__)
12
20
 
13
21
 
22
+ def _soundfile():
23
+ """``soundfile``, or an ``ImportError`` naming the ``widget`` extra."""
24
+ try:
25
+ import soundfile
26
+ except ImportError as e:
27
+ raise ImportError(
28
+ f"soundfile is required for the audio widget: {install_hint(WIDGET_EXTRA)}",
29
+ name="soundfile",
30
+ ) from e
31
+ return soundfile
32
+
33
+
14
34
  # Type aliases
15
35
  WaveformArray = (
16
36
  np.ndarray
@@ -49,13 +69,7 @@ def ensure_wfsr(audio_input: AudioInput) -> WfSr:
49
69
  >>> wf, sr = ensure_wfsr(audio_bytes) # doctest: +SKIP
50
70
  >>> wf, sr = ensure_wfsr((wf, sr)) # doctest: +SKIP
51
71
  """
52
- try:
53
- import soundfile as sf
54
- except ImportError:
55
- raise ImportError(
56
- "soundfile is required for audio processing. "
57
- "Install it with: pip install soundfile"
58
- )
72
+ sf = _soundfile()
59
73
 
60
74
  # Already in (wf, sr) format
61
75
  if isinstance(audio_input, tuple) and len(audio_input) == 2:
@@ -99,10 +113,7 @@ def wf_to_base64_wav(wf: WaveformArray, sr: SampleRate) -> str:
99
113
  Returns:
100
114
  Base64-encoded data URL string suitable for HTML audio element
101
115
  """
102
- try:
103
- import soundfile as sf
104
- except ImportError:
105
- raise ImportError("soundfile required for audio encoding")
116
+ sf = _soundfile()
106
117
 
107
118
  # Ensure wf is in proper format
108
119
  if wf.dtype != np.float32 and wf.dtype != np.float64:
@@ -653,10 +664,7 @@ __temp_sel_end = ${{sel.end}}
653
664
  filepath: Output file path
654
665
  format: Audio format (auto-detected from extension if None)
655
666
  """
656
- try:
657
- import soundfile as sf
658
- except ImportError:
659
- raise ImportError("soundfile required for saving audio")
667
+ sf = _soundfile()
660
668
 
661
669
  filepath = Path(filepath)
662
670
 
@@ -21,6 +21,7 @@ from dataclasses import dataclass
21
21
  from typing import Callable, Sequence
22
22
 
23
23
  from mixing.srt import parse_srt as _parse_srt
24
+ from mixing.util import require_llm_chat
24
25
 
25
26
  #: A segmenter maps (segments, target_count) -> [{"start": float, "title": str}].
26
27
  #: ``segments`` is a list of ``{"start", "end", "text"}`` sentence-ish units.
@@ -254,13 +255,9 @@ def default_segment_fn(
254
255
  boundaries as a JSON array of ``{"start", "title"}``. Pass your own
255
256
  ``segment_fn`` to :func:`detect_chapters` to avoid the ``aix`` dependency.
256
257
  """
257
- try:
258
- from aix import chat
259
- except ImportError as e: # pragma: no cover - environment dependent
260
- raise ImportError(
261
- "default_segment_fn needs the 'aix' package. Install it, or pass a "
262
- "custom segment_fn to detect_chapters()."
263
- ) from e
258
+ chat = require_llm_chat(
259
+ "default_segment_fn", alternative="segment_fn to detect_chapters()"
260
+ )
264
261
 
265
262
  lines = "\n".join(f"[{_fmt(s['start'])}] {s['text']}" for s in segments)
266
263
  prompt = (
@@ -16,6 +16,7 @@ from typing import Callable, Sequence
16
16
 
17
17
  # Canonical SRT primitives (re-exported for backward compatibility).
18
18
  from mixing.srt import Cue, dump_srt, parse_srt, srt_time_to_seconds
19
+ from mixing.util import require_llm_chat
19
20
 
20
21
  __all__ = [
21
22
  "Cue",
@@ -84,13 +85,9 @@ def default_translate_fn(
84
85
  one-to-one mapping with the input cues is preserved. Falls back to a clear
85
86
  error if ``aix`` is not importable — pass your own ``translate_fn`` then.
86
87
  """
87
- try:
88
- from aix import chat # provider-agnostic LLM interface
89
- except ImportError as e: # pragma: no cover - depends on environment
90
- raise ImportError(
91
- "default_translate_fn needs the 'aix' package for LLM translation. "
92
- "Install aix, or pass a custom translate_fn to translate_srt()."
93
- ) from e
88
+ chat = require_llm_chat(
89
+ "default_translate_fn", alternative="translate_fn to translate_srt()"
90
+ )
94
91
 
95
92
  import json as _json
96
93
 
@@ -35,7 +35,7 @@ from contextlib import closing
35
35
  from functools import lru_cache
36
36
  from typing import Callable, Iterable, Iterator, NamedTuple, Optional, Sequence, Union
37
37
 
38
- from mixing.util import LOUDNESS_EXTRA, ffmpeg_exe, install_hint
38
+ from mixing.util import LOUDNESS_EXTRA, ffmpeg_exe, install_hint, require_package
39
39
 
40
40
  try: # numpy only: scipy is imported where used, so the ffmpeg meter works without it
41
41
  import numpy as np
@@ -142,7 +142,7 @@ def _k_weighted_energies(chunks: Iterable[np.ndarray], fs: int) -> Iterator[np.n
142
142
  The filter state is carried across chunks, so the result is the same as
143
143
  filtering the whole signal while holding only a chunk at a time.
144
144
  """
145
- from scipy.signal import lfilter
145
+ lfilter = require_package("scipy.signal", extra=LOUDNESS_EXTRA).lfilter
146
146
 
147
147
  sections, states = _k_weighting_coefficients(fs), None
148
148
  for x in chunks:
@@ -344,8 +344,6 @@ def ebur128_lufs(data: np.ndarray, fs: int) -> float:
344
344
  def pyloudnorm_lufs(data: np.ndarray, fs: int) -> float:
345
345
  """Integrated loudness by ``pyloudnorm`` (needs it installed; >= 0.4 s of
346
346
  audio, at most 5 channels -- it raises otherwise)."""
347
- from mixing.util import require_package
348
-
349
347
  meter = require_package("pyloudnorm").Meter(fs)
350
348
  return float(meter.integrated_loudness(data))
351
349
 
@@ -381,7 +379,7 @@ def _interpolation_filter(factor: int) -> np.ndarray:
381
379
  ``resample_poly`` (which multiplies by ``factor``). Its every ``factor``-th
382
380
  tap is zero but the centre one, so the original samples pass unchanged and
383
381
  a true peak never reads below the sample peak. Read-only: it is cached."""
384
- from scipy.signal.windows import kaiser
382
+ kaiser = require_package("scipy.signal.windows", extra=LOUDNESS_EXTRA).kaiser
385
383
 
386
384
  half = TRUE_PEAK_FILTER_HALF_SAMPLES * factor
387
385
  n = np.arange(-half, half + 1)
@@ -409,7 +407,7 @@ def true_peak_envelope(
409
407
  looped. Chunked, with the filter's length of context shared between chunks,
410
408
  so the joins are exact.
411
409
  """
412
- from scipy.signal import resample_poly
410
+ resample_poly = require_package("scipy.signal", extra=LOUDNESS_EXTRA).resample_poly
413
411
 
414
412
  data = _as_2d(data)
415
413
  if oversampling is None:
@@ -22,16 +22,17 @@ import pytest
22
22
 
23
23
  from mixing.util import MEDIA_IMPORT_NAMES, MEDIA_INSTALL_HINT
24
24
 
25
- _PROLOGUE = f"""
25
+ _PROLOGUE = """
26
26
  import sys
27
- for _name in {list(MEDIA_IMPORT_NAMES)!r}:
27
+ for _name in {hidden!r}:
28
28
  sys.modules[_name] = None
29
29
  """
30
30
 
31
31
 
32
- def _run_hidden(body: str) -> dict:
33
- """Run ``body`` in a fresh interpreter with the media libs hidden; return its JSON."""
34
- code = _PROLOGUE + textwrap.dedent(body)
32
+ def _run_hidden(body: str, *, hidden=MEDIA_IMPORT_NAMES) -> dict:
33
+ """Run ``body`` in a fresh interpreter with ``hidden`` modules (default: the
34
+ media libs) made unimportable; return its JSON."""
35
+ code = _PROLOGUE.format(hidden=list(hidden)) + textwrap.dedent(body)
35
36
  proc = subprocess.run(
36
37
  [sys.executable, "-c", code], capture_output=True, text=True, timeout=120
37
38
  )
@@ -166,28 +167,48 @@ def test_loudness_without_numpy_names_the_missing_module():
166
167
  assert "mixing[loudness]" in out["message"]
167
168
 
168
169
 
169
- #: Import name -> distribution name, where they differ.
170
- _DISTRIBUTIONS = {"cv2": "opencv-contrib-python", "PIL": "pillow"}
170
+ #: Import name -> distribution name, where they differ. IPython's own
171
+ #: distribution is ``ipython``; the ``widget`` extra gets it from the ``jupyter``
172
+ #: metapackage it declares (which has no import name), so IPython stands for it.
173
+ _DISTRIBUTIONS = {
174
+ "cv2": "opencv-contrib-python",
175
+ "PIL": "pillow",
176
+ "ffmpeg": "ffmpeg-python",
177
+ "google.genai": "google-genai",
178
+ "IPython": "jupyter",
179
+ }
180
+ #: Extras that install tools and other extras, not modules mixing imports.
181
+ _NOT_IN_TABLE = {"dev", "testing"}
171
182
 
172
183
 
173
- def test_every_extra_in_the_table_is_declared_in_pyproject():
184
+ def _declared_extras() -> dict:
185
+ """``{extra: {distribution name}}`` from pyproject's optional-dependencies."""
174
186
  tomllib = pytest.importorskip("tomllib" if sys.version_info >= (3, 11) else "tomli")
175
187
  from pathlib import Path
176
188
 
177
- from mixing.util import EXTRAS
178
-
179
189
  path = Path(__file__).resolve().parents[2] / "pyproject.toml"
180
190
  if not path.exists():
181
191
  pytest.skip("pyproject.toml not available (installed distribution)")
182
192
  declared = tomllib.loads(path.read_text())["project"]["optional-dependencies"]
193
+ return {
194
+ extra: {re.split(r"[<>=!~\[ ;]", r, maxsplit=1)[0].lower() for r in reqs}
195
+ for extra, reqs in declared.items()
196
+ }
197
+
198
+
199
+ def test_the_table_and_pyproject_declare_the_same_extras():
200
+ """``EXTRAS`` is pyproject's extras read as import names: the same extras,
201
+ each with the same packages (both directions, so neither can drift)."""
202
+ from mixing.util import EXTRAS
203
+
204
+ declared = _declared_extras()
205
+ assert set(EXTRAS) == set(declared) - _NOT_IN_TABLE
183
206
  for extra, modules in EXTRAS.items():
184
- requirements = {
185
- re.split(r"[<>=!~\[ ;]", r, maxsplit=1)[0].lower() for r in declared[extra]
186
- }
187
- for module in modules:
188
- assert _DISTRIBUTIONS.get(module, module).lower() in requirements, (
189
- f"{module!r} is in EXTRAS[{extra!r}] but not in pyproject's {extra!r}"
190
- )
207
+ supplied = {_DISTRIBUTIONS.get(m, m).lower() for m in modules}
208
+ assert supplied == declared[extra], (
209
+ f"EXTRAS[{extra!r}] supplies {sorted(supplied)}, "
210
+ f"pyproject's {extra!r} declares {sorted(declared[extra])}"
211
+ )
191
212
 
192
213
 
193
214
  @pytest.mark.parametrize(
@@ -197,17 +218,15 @@ def test_every_extra_in_the_table_is_declared_in_pyproject():
197
218
  ("torch", "pip install 'mixing[ml]'"),
198
219
  ("librosa", "pip install 'mixing[beats]'"),
199
220
  ("numpy", "pip install 'mixing[media]'"),
221
+ ("aix", "pip install 'mixing[llm]'"),
222
+ ("google.genai.types", "pip install 'mixing[gen]'"),
223
+ ("pyclip", "pip install 'mixing[clipboard]'"),
200
224
  ],
201
225
  )
202
226
  def test_require_package_hints_the_extra_from_the_table(monkeypatch, module, hint):
203
- import importlib
204
-
205
227
  from mixing.util import require_package
206
228
 
207
- def deny(name, *a, **k):
208
- raise ImportError(name)
209
-
210
- monkeypatch.setattr(importlib, "import_module", deny)
229
+ _deny_imports(monkeypatch)
211
230
  with pytest.raises(ImportError, match=re.escape(hint)):
212
231
  require_package(module)
213
232
 
@@ -218,3 +237,123 @@ def test_unknown_extra_and_empty_module_list():
218
237
  with pytest.raises(ValueError, match="unknown extra"):
219
238
  install_hint("nope")
220
239
  require_extra("demo", "ml", modules=()) # nothing to check: no error
240
+
241
+
242
+ def _deny_imports(monkeypatch):
243
+ import importlib
244
+
245
+ def deny(name, *a, **k):
246
+ raise ImportError(name)
247
+
248
+ monkeypatch.setattr(importlib, "import_module", deny)
249
+
250
+
251
+ def test_require_package_names_the_callers_extra(monkeypatch):
252
+ from mixing.util import require_package
253
+
254
+ _deny_imports(monkeypatch)
255
+ with pytest.raises(ImportError, match=re.escape("mixing[loudness]")) as info:
256
+ require_package("scipy.signal", extra="loudness")
257
+ assert info.value.name == "scipy.signal"
258
+
259
+
260
+ def test_require_package_rejects_an_unknown_extra_even_when_installed():
261
+ from mixing.util import require_package
262
+
263
+ with pytest.raises(ValueError, match="unknown extra"):
264
+ require_package("math", extra="nope")
265
+
266
+
267
+ def test_loudness_without_scipy_names_the_loudness_extra():
268
+ """numpy installed, scipy not: the meter names ``mixing[loudness]`` (the
269
+ extra the user is on), not ``media``, and the ffmpeg meter's module loads."""
270
+ out = _run_hidden(
271
+ """
272
+ import json
273
+ import numpy as np
274
+ import mixing.loudness as L
275
+ x = np.sin(np.arange(8000) / 10.0)[:, None] * 0.1
276
+ ffmpeg = L.integrated_lufs(x, 8000, meter="ffmpeg_ebur128")
277
+ try:
278
+ L.integrated_lufs(x, 8000)
279
+ except ImportError as e:
280
+ print(json.dumps({"name": e.name, "message": str(e), "ffmpeg": ffmpeg}))
281
+ """,
282
+ hidden=("scipy",),
283
+ )
284
+ assert out["name"] == "scipy.signal"
285
+ assert "pip install 'mixing[loudness]'" in out["message"]
286
+ assert isinstance(out["ffmpeg"], float)
287
+
288
+
289
+ def test_llm_defaults_name_the_llm_extra_and_the_alternative():
290
+ out = _run_hidden(
291
+ """
292
+ import json
293
+ from mixing.chapters import default_segment_fn
294
+ from mixing.dubbing.srt import default_translate_fn
295
+ msgs = []
296
+ for call in (lambda: default_segment_fn([], 1),
297
+ lambda: default_translate_fn(["hi"], "fr")):
298
+ try:
299
+ call()
300
+ except ImportError as e:
301
+ msgs.append({"name": e.name, "message": str(e)})
302
+ print(json.dumps(msgs))
303
+ """,
304
+ hidden=("aix",),
305
+ )
306
+ assert [m["name"] for m in out] == ["aix", "aix"]
307
+ assert all("pip install 'mixing[llm]'" in m["message"] for m in out)
308
+ assert "segment_fn to detect_chapters()" in out[0]["message"]
309
+ assert "translate_fn to translate_srt()" in out[1]["message"]
310
+
311
+
312
+ def test_audio_widget_without_soundfile_names_the_widget_extra():
313
+ out = _run_hidden(
314
+ """
315
+ import json, sys, types
316
+ for _stub in ("IPython", "IPython.display"): # Jupyter is not installed in CI
317
+ sys.modules.setdefault(_stub, types.ModuleType(_stub))
318
+ sys.modules["IPython.display"].display = sys.modules["IPython.display"].HTML = None
319
+ from mixing.audio.audio_widget import ensure_wfsr
320
+ try:
321
+ ensure_wfsr("x.wav")
322
+ except ImportError as e:
323
+ print(json.dumps({"name": e.name, "message": str(e)}))
324
+ """,
325
+ hidden=("soundfile",),
326
+ )
327
+ assert out["name"] == "soundfile"
328
+ assert "pip install 'mixing[widget]'" in out["message"]
329
+
330
+
331
+ def test_audio_widget_without_jupyter_names_the_widget_extra():
332
+ out = _run_hidden(
333
+ """
334
+ import json
335
+ try:
336
+ import mixing.audio.audio_widget
337
+ except ImportError as e:
338
+ print(json.dumps({"name": e.name, "message": str(e)}))
339
+ """,
340
+ hidden=("IPython",),
341
+ )
342
+ assert out["name"].split(".")[0] == "IPython"
343
+ assert "pip install 'mixing[widget]'" in out["message"]
344
+
345
+
346
+ def test_require_package_does_not_blame_an_installed_package(monkeypatch):
347
+ """A package that is there but whose own import fails re-raises that error."""
348
+ import importlib
349
+
350
+ from mixing.util import require_package
351
+
352
+ def broken(name, *a, **k):
353
+ raise ModuleNotFoundError("No module named 'numba'", name="numba")
354
+
355
+ monkeypatch.setattr(importlib, "import_module", broken)
356
+ with pytest.raises(ModuleNotFoundError) as info:
357
+ require_package("librosa")
358
+ assert info.value.name == "numba"
359
+ assert "mixing[" not in str(info.value)
@@ -63,6 +63,11 @@ MEDIA_EXTRA = "media"
63
63
  ML_EXTRA = "ml"
64
64
  BEATS_EXTRA = "beats"
65
65
  LOUDNESS_EXTRA = "loudness"
66
+ AUDIO_EXTRA = "audio"
67
+ WIDGET_EXTRA = "widget"
68
+ GEN_EXTRA = "gen"
69
+ LLM_EXTRA = "llm"
70
+ CLIPBOARD_EXTRA = "clipboard"
66
71
 
67
72
  # Import names (top-level) that the ``media`` extra provides, per media area.
68
73
  AUDIO_IMPORT_NAMES = ("numpy", "pydub", "scipy")
@@ -74,15 +79,24 @@ ML_IMPORT_NAMES = ("torch", "transformers")
74
79
  BEATS_IMPORT_NAMES = ("librosa",)
75
80
  LOUDNESS_IMPORT_NAMES = ("numpy", "scipy")
76
81
 
77
- #: The one table of the extras mixing checks for: ``{extra: import names it
78
- #: supplies}``. A module in several extras (numpy) maps to the first, so the
79
- #: broadest install wins. ``extra_for`` / ``install_hint`` are public so a
80
- #: caller can map a missing module (``ImportError.name``) to its install line.
82
+ #: The one table of mixing's extras: ``{extra: import names it supplies}``,
83
+ #: each declared by the same-named extra in ``pyproject.toml`` (a test holds the
84
+ #: two equal). A name may be dotted (``google.genai``: ``google`` is a shared
85
+ #: namespace). A module in several extras (numpy) maps to the first, so the
86
+ #: broadest install wins; a caller that knows better names its extra
87
+ #: (``require_package("scipy.signal", extra=LOUDNESS_EXTRA)``). ``extra_for`` /
88
+ #: ``install_hint`` are public so a caller can map a missing module
89
+ #: (``ImportError.name``) to its install line.
81
90
  EXTRAS: dict[str, tuple[str, ...]] = {
82
91
  MEDIA_EXTRA: MEDIA_IMPORT_NAMES,
83
92
  ML_EXTRA: ML_IMPORT_NAMES,
84
93
  BEATS_EXTRA: BEATS_IMPORT_NAMES,
85
94
  LOUDNESS_EXTRA: LOUDNESS_IMPORT_NAMES,
95
+ AUDIO_EXTRA: ("pydub", "ffmpeg", "soundfile"),
96
+ WIDGET_EXTRA: ("ipywidgets", "soundfile", "IPython"),
97
+ GEN_EXTRA: ("google.genai",),
98
+ LLM_EXTRA: ("aix",),
99
+ CLIPBOARD_EXTRA: ("pyclip",),
86
100
  }
87
101
 
88
102
 
@@ -97,14 +111,27 @@ def install_hint(extra: str) -> str:
97
111
  return f"pip install 'mixing[{extra}]'"
98
112
 
99
113
 
114
+ def _supplies(name: str, module: str) -> bool:
115
+ """True if import name ``name`` is ``module`` or one of its parent packages."""
116
+ return module == name or module.startswith(name + ".")
117
+
118
+
100
119
  def extra_for(module: str) -> Optional[str]:
101
- """The extra that supplies ``module`` (dotted names by their top level), or ``None``.
120
+ """The extra that supplies ``module`` (or a parent package of it), or ``None``.
102
121
 
103
- >>> extra_for("scipy.signal"), extra_for("librosa"), extra_for("requests")
104
- ('media', 'beats', None)
122
+ >>> extra_for("scipy.signal"), extra_for("librosa"), extra_for("google.genai.types")
123
+ ('media', 'beats', 'gen')
124
+ >>> extra_for("requests"), extra_for("google.protobuf")
125
+ (None, None)
105
126
  """
106
- top = module.split(".")[0]
107
- return next((extra for extra, names in EXTRAS.items() if top in names), None)
127
+ return next(
128
+ (
129
+ extra
130
+ for extra, names in EXTRAS.items()
131
+ if any(_supplies(name, module) for name in names)
132
+ ),
133
+ None,
134
+ )
108
135
 
109
136
 
110
137
  MEDIA_INSTALL_HINT = install_hint(MEDIA_EXTRA)
@@ -113,7 +140,8 @@ BEATS_INSTALL_HINT = install_hint(BEATS_EXTRA)
113
140
 
114
141
 
115
142
  def _is_importable(name: str) -> bool:
116
- """True if top-level module ``name`` can be found, without importing it."""
143
+ """True if module ``name`` can be found, without importing it (a dotted
144
+ name's parent packages are imported, as ``find_spec`` must)."""
117
145
  try:
118
146
  return importlib.util.find_spec(name) is not None
119
147
  except (ImportError, ValueError):
@@ -163,30 +191,52 @@ def require_ml_extra(feature: str, *, modules: tuple[str, ...] = ML_IMPORT_NAMES
163
191
  require_extra(feature, ML_EXTRA, modules=modules)
164
192
 
165
193
 
166
- def require_package(package_name: str):
194
+ def require_package(package_name: str, *, extra: Optional[str] = None):
167
195
  """
168
196
  Import a package, raising an informative error if not installed.
169
197
 
170
- A package an extra supplies (see ``EXTRAS``) gets a hint naming that extra.
198
+ The hint names ``extra`` when given (the extra the caller belongs to: in
199
+ ``mixing.loudness``, scipy comes from ``loudness``, not ``media``), else the
200
+ extra ``EXTRAS`` maps ``package_name`` to, else ``pip install <package>``.
171
201
  The error's ``name`` is ``package_name``, so a caller can map it to its own
172
- install hint.
202
+ install hint. An installed package whose own imports fail re-raises that
203
+ error unchanged, rather than claiming the package is missing.
173
204
 
174
205
  >>> math = require_package('math') # doctest: +SKIP
175
206
  >>> math.pi # doctest: +SKIP
176
207
  3.141592653589793
177
208
  """
209
+ if extra is not None:
210
+ install_hint(extra) # an unknown extra is the caller's bug: fail now
178
211
  try:
179
212
  return importlib.import_module(package_name)
180
213
  except ImportError as e:
181
- extra = extra_for(package_name)
214
+ if e.name and not _supplies(e.name, package_name):
215
+ raise # the package is there; one of *its* imports failed
216
+ extra = extra or extra_for(package_name)
182
217
  hint = install_hint(extra) if extra else f"pip install {package_name}"
183
218
  raise ImportError(
184
219
  f"Package '{package_name}' is required for this functionality. "
185
- f"Please install it via '{hint}'.",
220
+ f"Install it with {hint}.",
186
221
  name=package_name,
187
222
  ) from e
188
223
 
189
224
 
225
+ def require_llm_chat(feature: str, *, alternative: str):
226
+ """``aix.chat``, the LLM call behind ``feature``, or an ``ImportError`` naming
227
+ the ``llm`` extra and the ``alternative`` that needs no LLM.
228
+
229
+ >>> require_llm_chat("demo", alternative="segment_fn") # doctest: +SKIP
230
+ """
231
+ try:
232
+ return require_package("aix", extra=LLM_EXTRA).chat
233
+ except ImportError as e:
234
+ raise ImportError(
235
+ f"{feature} needs an LLM. {e} Or pass your own {alternative}.",
236
+ name=e.name,
237
+ ) from e
238
+
239
+
190
240
  def to_seconds(value: float, *, unit: TimeUnit | AudioTimeUnit, rate: float) -> float:
191
241
  """
192
242
  Convert time value to seconds based on unit.
@@ -74,6 +74,7 @@ from collections.abc import Callable
74
74
 
75
75
  from dol import non_colliding_key
76
76
 
77
+ from ..util import require_package
77
78
  from ._helpers import _is_video_file
78
79
 
79
80
  logger = logging.getLogger(__name__)
@@ -140,7 +141,7 @@ def _setup_genai_client(
140
141
  service_account_file=None, project_id=None, location="us-central1"
141
142
  ):
142
143
  """Set up Google GenAI client with proper error handling."""
143
- from google import genai
144
+ genai = require_package("google.genai")
144
145
 
145
146
  try:
146
147
  if service_account_file:
@@ -661,8 +662,8 @@ def generate_video(
661
662
  Authentication errors with helpful setup instructions
662
663
  """
663
664
  # TODO: manage models better (when aix offers model routing tools)
664
- from google import genai
665
- from google.genai.types import GenerateVideosConfig, Image
665
+ types = require_package("google.genai.types")
666
+ GenerateVideosConfig, Image = types.GenerateVideosConfig, types.Image
666
667
  from mixing.egress import is_path_output, is_sink
667
668
 
668
669
  # Resolve ``output`` into an egress sink (a callable applied to the
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
6
6
 
7
7
  [project]
8
8
  name = "mixing"
9
- version = "0.0.77"
9
+ version = "0.0.78"
10
10
  description = "Tools for video and audio editing"
11
11
  readme = "README.md"
12
12
  requires-python = ">=3.10"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes