Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
backend: extract normalize_audio into services/audio_normalize
Nika Siradzea91ba735256b
diff --git a/backend/services/audio_normalize.py b/backend/services/audio_normalize.pynew file mode 100644index 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 datadiff --git a/backend/services/video_processor.py b/backend/services/video_processor.pyindex 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_audioimport 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.pynew file mode 100644index 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()