Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

backend: extract normalize_audio into services/audio_normalize

Nika Siradzea91ba735256b
diff --git a/backend/services/audio_normalize.py b/backend/services/audio_normalize.py
new file mode 100644
index 0000000..7b10750
--- /dev/null
+++ b/backend/services/audio_normalize.py
@@ -0,0 +1,92 @@
+"""Two-pass audio loudness normalization via ffmpeg loudnorm filter.
+
+Extracted from video_processor.py. Takes a rendered clip and brings
+its audio to the target LUFS (−14 by default, which is the TikTok /
+YouTube Shorts standard).
+"""
+
+from __future__ import annotations
+
+import json
+
+from services.media_probe import FFMPEG_TIMEOUT
+from utils.proc import run as proc_run
+
+
+def normalize_audio(
+ input_path: str,
+ output_path: str,
+ target_lufs: float = -14.0,
+) -> str:
+ """Normalize audio to target LUFS.
+
+ Uses a two-pass loudnorm filter when possible: first pass measures
+ the clip's loudness stats, second pass applies linear correction.
+ Falls back to a single-pass loudnorm when measurement is missing
+ or returns −inf (silent / very short clips).
+ """
+ # First pass: measure current loudness.
+ measure_cmd = [
+ "ffmpeg", "-y",
+ "-i", input_path,
+ "-af", f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11:print_format=json",
+ "-f", "null", "-",
+ ]
+ result = proc_run(measure_cmd, timeout=FFMPEG_TIMEOUT, check=False)
+
+ loudnorm_data = _parse_loudnorm_stats(result.stderr)
+
+ if loudnorm_data:
+ # Second pass: apply measured correction.
+ af_filter = (
+ f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11:"
+ f"measured_I={loudnorm_data.get('input_i', '-24')}:"
+ f"measured_TP={loudnorm_data.get('input_tp', '-1')}:"
+ f"measured_LRA={loudnorm_data.get('input_lra', '7')}:"
+ f"measured_thresh={loudnorm_data.get('input_thresh', '-34')}:"
+ f"offset={loudnorm_data.get('target_offset', '0')}:"
+ f"linear=true"
+ )
+ else:
+ # Single-pass fallback.
+ af_filter = f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11"
+
+ cmd = [
+ "ffmpeg", "-y",
+ "-i", input_path,
+ "-af", af_filter,
+ "-c:v", "copy",
+ "-c:a", "aac",
+ "-b:a", "192k",
+ "-ar", "44100",
+ "-movflags", "+faststart",
+ output_path,
+ ]
+ result = proc_run(cmd, timeout=FFMPEG_TIMEOUT, check=False)
+ if result.returncode != 0:
+ raise RuntimeError(f"FFmpeg normalize failed: {result.stderr[-500:]}")
+ return output_path
+
+
+def _parse_loudnorm_stats(stderr: str) -> dict | None:
+ """Extract the loudnorm JSON block from ffmpeg stderr.
+
+ Returns None if the block is missing, unparseable, or contains
+ -inf input_i (which signals silence / a too-short clip where the
+ two-pass correction isn't meaningful).
+ """
+ if not stderr:
+ return None
+ try:
+ json_start = stderr.rfind("{")
+ json_end = stderr.rfind("}") + 1
+ if json_start < 0 or json_end <= json_start:
+ return None
+ data = json.loads(stderr[json_start:json_end])
+ except (json.JSONDecodeError, ValueError):
+ return None
+
+ measured_i = str(data.get("input_i", ""))
+ if "inf" in measured_i.lower() or measured_i == "":
+ return None
+ return data
diff --git a/backend/services/video_processor.py b/backend/services/video_processor.py
index 95d512e..99dc964 100644
--- a/backend/services/video_processor.py
+++ b/backend/services/video_processor.py
@@ -25,6 +25,7 @@ from services.media_probe import (
parse_duration_seconds as _parse_duration_seconds,
run_ffmpeg_with_fallback as _run_ffmpeg_with_fallback,
)
+from services.audio_normalize import normalize_audio
import sys
@@ -3074,74 +3075,7 @@ def concat_outro(
os.remove(tmp)
-def normalize_audio(
- input_path: str,
- output_path: str,
- target_lufs: float = -14.0,
-) -> str:
- """
- Normalize audio to target LUFS (loudness units).
- TikTok/YouTube Shorts standard is around -14 LUFS.
- """
- # First pass: measure current loudness
- measure_cmd = [
- "ffmpeg", "-y",
- "-i", input_path,
- "-af", f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11:print_format=json",
- "-f", "null", "-",
- ]
- result = proc_run(measure_cmd, timeout=_FFMPEG_TIMEOUT, check=False)
-
- # Try to parse loudnorm output from stderr
- stderr = result.stderr
- try:
- # Find the JSON block in stderr
- json_start = stderr.rfind("{")
- json_end = stderr.rfind("}") + 1
- if json_start >= 0 and json_end > json_start:
- loudnorm_data = json.loads(stderr[json_start:json_end])
- else:
- # Fallback: simple normalization without two-pass
- loudnorm_data = None
- except (json.JSONDecodeError, ValueError):
- loudnorm_data = None
-
- # Check for invalid measurements (e.g., -inf from silence/very short clips)
- if loudnorm_data:
- measured_i = str(loudnorm_data.get("input_i", ""))
- if "inf" in measured_i.lower() or measured_i == "":
- loudnorm_data = None
-
- if loudnorm_data:
- # Second pass: apply measured correction
- af_filter = (
- f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11:"
- f"measured_I={loudnorm_data.get('input_i', '-24')}:"
- f"measured_TP={loudnorm_data.get('input_tp', '-1')}:"
- f"measured_LRA={loudnorm_data.get('input_lra', '7')}:"
- f"measured_thresh={loudnorm_data.get('input_thresh', '-34')}:"
- f"offset={loudnorm_data.get('target_offset', '0')}:"
- f"linear=true"
- )
- else:
- # Single-pass fallback
- af_filter = f"loudnorm=I={target_lufs}:TP=-1.5:LRA=11"
-
- cmd = [
- "ffmpeg", "-y",
- "-i", input_path,
- "-af", af_filter,
- "-c:v", "copy",
- "-c:a", "aac",
- "-b:a", "192k",
- "-ar", "44100",
- "-movflags", "+faststart",
- output_path,
- ]
- result = proc_run(cmd, timeout=_FFMPEG_TIMEOUT, check=False)
- if result.returncode != 0:
- raise RuntimeError(f"FFmpeg normalize failed: {result.stderr[-500:]}")
- return output_path
+# normalize_audio is now in services.audio_normalize; re-exported below.
def _detect_face_y(
diff --git a/tests/test_audio_normalize.py b/tests/test_audio_normalize.py
new file mode 100644
index 0000000..ab6550a
--- /dev/null
+++ b/tests/test_audio_normalize.py
@@ -0,0 +1,135 @@
+"""Tests for backend.services.audio_normalize.
+
+Tests the pure helpers and the two-pass orchestration by mocking
+proc_run so no actual ffmpeg process is spawned.
+"""
+
+import os
+import sys
+import unittest
+from unittest import mock
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+BACKEND_ROOT = os.path.join(ROOT, "backend")
+if BACKEND_ROOT not in sys.path:
+ sys.path.insert(0, BACKEND_ROOT)
+
+from services import audio_normalize as an
+
+
+class ParseLoudnormStatsTests(unittest.TestCase):
+ def test_empty_stderr_returns_none(self):
+ self.assertIsNone(an._parse_loudnorm_stats(""))
+ self.assertIsNone(an._parse_loudnorm_stats(None)) # type: ignore[arg-type]
+
+ def test_missing_json_block_returns_none(self):
+ self.assertIsNone(
+ an._parse_loudnorm_stats("no json here at all, just text")
+ )
+
+ def test_parses_valid_json_block(self):
+ stderr = (
+ "some ffmpeg noise\n"
+ '{"input_i": "-20.5", "input_tp": "-2.0", '
+ '"input_lra": "5.5", "input_thresh": "-30.0", '
+ '"target_offset": "-0.5"}\n'
+ "more noise\n"
+ )
+ data = an._parse_loudnorm_stats(stderr)
+ self.assertIsNotNone(data)
+ self.assertEqual(data["input_i"], "-20.5")
+ self.assertEqual(data["input_tp"], "-2.0")
+
+ def test_rejects_negative_infinity_input(self):
+ # -inf means silence / too-short clip — two-pass isn't meaningful
+ stderr = '{"input_i": "-inf", "input_tp": "-inf"}'
+ self.assertIsNone(an._parse_loudnorm_stats(stderr))
+
+ def test_rejects_positive_infinity_input(self):
+ stderr = '{"input_i": "inf", "input_tp": "0"}'
+ self.assertIsNone(an._parse_loudnorm_stats(stderr))
+
+ def test_rejects_empty_input_i(self):
+ stderr = '{"input_i": "", "input_tp": "0"}'
+ self.assertIsNone(an._parse_loudnorm_stats(stderr))
+
+ def test_rejects_malformed_json(self):
+ stderr = '{"input_i": "-20", ' # truncated
+ self.assertIsNone(an._parse_loudnorm_stats(stderr))
+
+
+class NormalizeAudioTests(unittest.TestCase):
+ def _ok(self, stderr: str = "") -> mock.Mock:
+ return mock.Mock(returncode=0, stdout="", stderr=stderr)
+
+ def test_two_pass_when_loudnorm_stats_available(self):
+ measure_stderr = (
+ '{"input_i": "-20.5", "input_tp": "-2.0", '
+ '"input_lra": "5.5", "input_thresh": "-30.0", '
+ '"target_offset": "-0.5"}'
+ )
+ with mock.patch.object(
+ an, "proc_run",
+ side_effect=[self._ok(stderr=measure_stderr), self._ok()],
+ ) as mocked:
+ result = an.normalize_audio("/in.mp4", "/out.mp4")
+ self.assertEqual(result, "/out.mp4")
+ self.assertEqual(mocked.call_count, 2)
+ # Second call (apply) should include the measured values
+ apply_cmd = mocked.call_args_list[1].args[0]
+ joined = " ".join(apply_cmd)
+ self.assertIn("measured_I=-20.5", joined)
+ self.assertIn("linear=true", joined)
+
+ def test_single_pass_fallback_on_missing_stats(self):
+ with mock.patch.object(
+ an, "proc_run",
+ side_effect=[self._ok(stderr="no stats here"), self._ok()],
+ ) as mocked:
+ result = an.normalize_audio("/in.mp4", "/out.mp4")
+ self.assertEqual(result, "/out.mp4")
+ apply_cmd = mocked.call_args_list[1].args[0]
+ joined = " ".join(apply_cmd)
+ # No measured_* values — single-pass filter
+ self.assertNotIn("measured_I", joined)
+ self.assertIn("loudnorm=I=-14.0", joined)
+
+ def test_single_pass_fallback_on_inf_measurement(self):
+ measure_stderr = '{"input_i": "-inf"}'
+ with mock.patch.object(
+ an, "proc_run",
+ side_effect=[self._ok(stderr=measure_stderr), self._ok()],
+ ) as mocked:
+ result = an.normalize_audio("/in.mp4", "/out.mp4")
+ apply_cmd = mocked.call_args_list[1].args[0]
+ joined = " ".join(apply_cmd)
+ self.assertNotIn("measured_I", joined)
+
+ def test_custom_target_lufs(self):
+ with mock.patch.object(
+ an, "proc_run",
+ side_effect=[self._ok(stderr=""), self._ok()],
+ ) as mocked:
+ an.normalize_audio("/in.mp4", "/out.mp4", target_lufs=-16.0)
+ apply_cmd = mocked.call_args_list[1].args[0]
+ joined = " ".join(apply_cmd)
+ self.assertIn("loudnorm=I=-16.0", joined)
+
+ def test_raises_on_apply_failure(self):
+ fail = mock.Mock(returncode=1, stdout="", stderr="broken")
+ with mock.patch.object(
+ an, "proc_run",
+ side_effect=[self._ok(stderr=""), fail],
+ ):
+ with self.assertRaises(RuntimeError):
+ an.normalize_audio("/in.mp4", "/out.mp4")
+
+
+class ReExportTests(unittest.TestCase):
+ def test_video_processor_still_exposes_normalize_audio(self):
+ from services import video_processor as vp
+ self.assertIs(vp.normalize_audio, an.normalize_audio)
+
+
+if __name__ == "__main__":
+ unittest.main()