From 60af90de3176c0fb1a115f00da2cff831bb9f67c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Mon, 5 Jan 2026 22:50:24 -0500 Subject: [PATCH] fix: Escape FFmpeg filter paths using single-quote wrapping (#212) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Fix FFmpeg failing on paths with apostrophes (e.g., "I'm With You") - Use single-quote wrapping with `'\''` pattern for embedded quotes - Update both `video.py` and `video_background_processor.py` ## Test plan - [x] Unit tests updated and passing (1006 tests) - [x] E2E tests passing (68 tests) - [x] Manually tested with "Avril Lavigne - I'm With You" - video generates successfully ## Technical details FFmpeg filter syntax interprets apostrophes as special characters. Simple backslash escaping (`\'`) doesn't work because FFmpeg's filter parser consumes the backslash. The solution is to wrap paths in single quotes and escape embedded quotes using the `'\''` pattern (end quote, literal quote, start quote). Example: `I'm With You` becomes `'I'\''m With You'` @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.5 --- docs/LESSONS-LEARNED.md | 33 ++++++++ karaoke_gen/video_background_processor.py | 13 ++- .../lyrics_transcriber/output/video.py | 26 ++++-- .../tests/unit/output/test_video.py | 79 +++++++++++++++---- pyproject.toml | 2 +- tests/unit/test_video_background_processor.py | 58 ++++++++------ 6 files changed, 161 insertions(+), 50 deletions(-) diff --git a/docs/LESSONS-LEARNED.md b/docs/LESSONS-LEARNED.md index 89ae0cc9..302383ba 100644 --- a/docs/LESSONS-LEARNED.md +++ b/docs/LESSONS-LEARNED.md @@ -222,6 +222,39 @@ escaped = filename.replace("'", "\\'") query = f"name='{escaped}' and '{parent_id}' in parents" ``` +### FFmpeg Filter Path Escaping + +**Problem**: Song titles with apostrophes (e.g., "I'm With You") cause FFmpeg's ASS subtitle filter to fail because paths aren't escaped. + +```python +# BAD - FFmpeg strips the apostrophe, looks for wrong path +ass_filter = f"ass=./Avril Lavigne - I'm With You/cache/temp.ass" +# FFmpeg error: Could not create a libass track when reading file './Avril Lavigne - Im With You/cache/temp.ass' +``` + +FFmpeg filter syntax interprets `'`, `:`, and `\` as special characters. The path appears correct in logs but FFmpeg silently mangles it. + +**Wrong approach** (doesn't work): Simple backslash escaping like `\'` doesn't work because FFmpeg's filter parser consumes the backslash. + +**Solution**: Wrap paths in single quotes and escape embedded quotes using `'\''`: +```python +def _escape_ffmpeg_filter_path(path: str) -> str: + # Escape single quotes: ' becomes '\'' (end quote, \', start quote) + escaped = path.replace("'", "'\\''") + # Wrap entire path in single quotes + return f"'{escaped}'" + +# Result: "I'm With You" becomes "'I'\\''m With You'" +# FFmpeg sees: 'I' + literal ' + 'm With You' +``` + +**Symptoms**: +- Video generation fails with "Could not create a libass track" +- Error path is subtly different from the path in your code (missing apostrophe) +- Works fine for songs without special characters + +**Lesson**: Any path passed to FFmpeg filter expressions (`-vf`, `-af`) needs single-quote wrapping. The `'\''` pattern (end quote, escaped quote, start quote) handles embedded quotes correctly. + ### Duplicate Code Leads to Inconsistent Behavior **Problem**: Multiple endpoints computing the same defaults independently. `audio_search.py` had `effective_brand_prefix = body.brand_prefix or settings.default_brand_prefix` but `file_upload.py` was missing it for some endpoints. diff --git a/karaoke_gen/video_background_processor.py b/karaoke_gen/video_background_processor.py index ea302f3b..5356ea51 100644 --- a/karaoke_gen/video_background_processor.py +++ b/karaoke_gen/video_background_processor.py @@ -156,15 +156,20 @@ class VideoBackgroundProcessor: """ Escape a file path for use in ffmpeg filter expressions. + FFmpeg filter syntax uses single quotes to protect special characters + like spaces, colons, and semicolons. Single quotes within the path + are escaped using the '\\'' pattern (end quote, literal quote, start quote). + Args: path: File path to escape Returns: - str: Escaped path + str: Escaped path (wrapped in single quotes) """ - # Escape backslashes and colons for ffmpeg filter syntax - escaped = path.replace("\\", "\\\\").replace(":", "\\:") - return escaped + # Escape single quotes: ' becomes '\'' (end quote, \', start quote) + escaped = path.replace("'", "'\\''") + # Wrap entire path in single quotes + return f"'{escaped}'" def build_video_filter(self, ass_subtitles_path, darkness_percent, fonts_dir=None): """ diff --git a/lyrics_transcriber_temp/lyrics_transcriber/output/video.py b/lyrics_transcriber_temp/lyrics_transcriber/output/video.py index 23643bc7..2612fe7b 100644 --- a/lyrics_transcriber_temp/lyrics_transcriber/output/video.py +++ b/lyrics_transcriber_temp/lyrics_transcriber/output/video.py @@ -352,19 +352,35 @@ class VideoGenerator: self.logger.error(f"Failed to resize background image: {e.output}") raise + def _escape_ffmpeg_filter_path(self, path: str) -> str: + """Escape a path for FFmpeg filter expressions using single-quote wrapping. + + FFmpeg filter syntax uses single quotes to protect special characters + like spaces, colons, and semicolons. Single quotes within the path + are escaped using the '\'' pattern (end quote, literal quote, start quote). + + Example: "I'm With You" becomes "'I'\\''m With You'" + """ + # Escape single quotes: ' becomes '\'' (end quote, \', start quote) + escaped = path.replace("'", "'\\''") + # Wrap entire path in single quotes + return f"'{escaped}'" + def _build_ass_filter(self, ass_path: str) -> str: """Build ASS filter with font directory support.""" - ass_filter = f"ass={ass_path}" - + escaped_ass_path = self._escape_ffmpeg_filter_path(ass_path) + ass_filter = f"ass={escaped_ass_path}" + # Get font path from styles configuration karaoke_styles = self.styles.get("karaoke", {}) font_path = karaoke_styles.get("font_path") - + if font_path and os.path.isfile(font_path): font_dir = os.path.dirname(font_path) - ass_filter += f":fontsdir={font_dir}" + escaped_font_dir = self._escape_ffmpeg_filter_path(font_dir) + ass_filter += f":fontsdir={escaped_font_dir}" self.logger.info(f"Returning ASS filter with fonts dir: {ass_filter}") - + return ass_filter def _build_ffmpeg_command(self, ass_path: str, audio_path: str, output_path: str) -> List[str]: diff --git a/lyrics_transcriber_temp/tests/unit/output/test_video.py b/lyrics_transcriber_temp/tests/unit/output/test_video.py index d7a38546..4b1193e6 100644 --- a/lyrics_transcriber_temp/tests/unit/output/test_video.py +++ b/lyrics_transcriber_temp/tests/unit/output/test_video.py @@ -210,7 +210,7 @@ def test_build_ass_filter_no_font_path(video_generator): """Test _build_ass_filter with no font path configured.""" ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - assert result == "ass=test.ass" + assert result == "ass='test.ass'" def test_build_ass_filter_with_valid_font_path(video_generator, tmp_path): @@ -220,13 +220,14 @@ def test_build_ass_filter_with_valid_font_path(video_generator, tmp_path): font_dir.mkdir() font_file = font_dir / "test.ttf" font_file.touch() - + # Update styles to include font path video_generator.styles["karaoke"]["font_path"] = str(font_file) - + ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - expected = f"ass=test.ass:fontsdir={str(font_dir)}" + # Both paths should be wrapped in single quotes + expected = f"ass='test.ass':fontsdir='{str(font_dir)}'" assert result == expected @@ -234,30 +235,30 @@ def test_build_ass_filter_with_invalid_font_path(video_generator): """Test _build_ass_filter with invalid font path (file doesn't exist).""" # Set non-existent font path video_generator.styles["karaoke"]["font_path"] = "/nonexistent/font.ttf" - + ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - assert result == "ass=test.ass" + assert result == "ass='test.ass'" def test_build_ass_filter_with_empty_font_path(video_generator): """Test _build_ass_filter with empty font path.""" # Set empty font path video_generator.styles["karaoke"]["font_path"] = "" - + ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - assert result == "ass=test.ass" + assert result == "ass='test.ass'" def test_build_ass_filter_with_none_font_path(video_generator): """Test _build_ass_filter with None font path.""" # Set None font path video_generator.styles["karaoke"]["font_path"] = None - + ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - assert result == "ass=test.ass" + assert result == "ass='test.ass'" def test_build_ass_filter_no_karaoke_section(tmp_path): @@ -269,29 +270,75 @@ def test_build_ass_filter_no_karaoke_section(tmp_path): video_resolution=(1920, 1080), styles=styles, ) - + ass_path = "test.ass" result = generator._build_ass_filter(ass_path) - assert result == "ass=test.ass" + assert result == "ass='test.ass'" def test_build_ass_filter_logging(video_generator, tmp_path, caplog): """Test _build_ass_filter logging behavior.""" # Set log level to INFO to capture the logs caplog.set_level(logging.INFO) - + # Create a test font file font_dir = tmp_path / "fonts" font_dir.mkdir() font_file = font_dir / "test.ttf" font_file.touch() - + # Update styles to include font path video_generator.styles["karaoke"]["font_path"] = str(font_file) - + ass_path = "test.ass" result = video_generator._build_ass_filter(ass_path) - + # Check that info log was generated assert "Returning ASS filter with fonts dir:" in caplog.text assert str(font_dir) in caplog.text + + +def test_escape_ffmpeg_filter_path(video_generator): + """Test _escape_ffmpeg_filter_path uses single-quote wrapping correctly.""" + # Test simple path (wrapped in single quotes) + assert video_generator._escape_ffmpeg_filter_path("/path/to/file.ass") == "'/path/to/file.ass'" + + # Test apostrophe escaping (fixes paths like "I'm With You") + # Single quote becomes '\'' (end quote, escaped quote, start quote) + assert video_generator._escape_ffmpeg_filter_path("./Avril Lavigne - I'm With You/file.ass") == "'./Avril Lavigne - I'\\''m With You/file.ass'" + + # Test path with spaces (protected by single quotes) + assert video_generator._escape_ffmpeg_filter_path("/path/with spaces/file.ass") == "'/path/with spaces/file.ass'" + + # Test path with colons (protected by single quotes) + assert video_generator._escape_ffmpeg_filter_path("C:/path/file.ass") == "'C:/path/file.ass'" + + # Test multiple apostrophes + assert video_generator._escape_ffmpeg_filter_path("It's Bob's file.ass") == "'It'\\''s Bob'\\''s file.ass'" + + +def test_build_ass_filter_escapes_path_with_apostrophe(video_generator): + """Test _build_ass_filter properly escapes paths containing apostrophes.""" + ass_path = "./Avril Lavigne - I'm With You/cache/temp.ass" + result = video_generator._build_ass_filter(ass_path) + # Should wrap in single quotes and escape the apostrophe + assert result == "ass='./Avril Lavigne - I'\\''m With You/cache/temp.ass'" + + +def test_build_ass_filter_escapes_font_dir_with_special_chars(video_generator, tmp_path): + """Test _build_ass_filter properly escapes font directory with special characters.""" + # Create a font directory with special characters + font_dir = tmp_path / "It's a Font Dir" + font_dir.mkdir() + font_file = font_dir / "test.ttf" + font_file.touch() + + # Update styles to include font path + video_generator.styles["karaoke"]["font_path"] = str(font_file) + + ass_path = "test.ass" + result = video_generator._build_ass_filter(ass_path) + # Should have fontsdir with escaped path + assert "fontsdir=" in result + # Apostrophe should be escaped using '\'' pattern + assert "'\\''s" in result diff --git a/pyproject.toml b/pyproject.toml index 6575c3a3..5ae1f349 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "karaoke-gen" -version = "0.91.2" +version = "0.91.4" description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens." authors = ["Andrew Beveridge "] license = "MIT" diff --git a/tests/unit/test_video_background_processor.py b/tests/unit/test_video_background_processor.py index 9f0254e9..7ad0dd52 100644 --- a/tests/unit/test_video_background_processor.py +++ b/tests/unit/test_video_background_processor.py @@ -121,16 +121,25 @@ class TestVideoBackgroundProcessor: processor.get_audio_duration("/path/to/audio.wav") def test_escape_filter_path(self, processor): - """Test path escaping for ffmpeg filters.""" - # Test backslash escaping - assert processor.escape_filter_path("C:\\Users\\test\\file.ass") == "C\\:\\\\Users\\\\test\\\\file.ass" - - # Test colon escaping - assert processor.escape_filter_path("/path/to/file.ass") == "/path/to/file.ass" - assert processor.escape_filter_path("C:/path/file.ass") == "C\\:/path/file.ass" - - # Test combined escaping - assert processor.escape_filter_path("C:\\path:with:colons\\file.ass") == "C\\:\\\\path\\:with\\:colons\\\\file.ass" + """Test path escaping for ffmpeg filters using single-quote wrapping.""" + # Test simple path (wrapped in single quotes) + assert processor.escape_filter_path("/path/to/file.ass") == "'/path/to/file.ass'" + + # Test path with spaces (protected by single quotes) + assert processor.escape_filter_path("/path/with spaces/file.ass") == "'/path/with spaces/file.ass'" + + # Test apostrophe escaping (fixes paths like "I'm With You") + # Single quote becomes '\'' (end quote, escaped quote, start quote) + assert processor.escape_filter_path("./Avril Lavigne - I'm With You/file.ass") == "'./Avril Lavigne - I'\\''m With You/file.ass'" + + # Test path with colons (protected by single quotes) + assert processor.escape_filter_path("C:/path/file.ass") == "'C:/path/file.ass'" + + # Test Windows-style path (backslashes preserved, wrapped in quotes) + assert processor.escape_filter_path("C:\\Users\\test\\file.ass") == "'C:\\Users\\test\\file.ass'" + + # Test multiple apostrophes + assert processor.escape_filter_path("It's Bob's file.ass") == "'It'\\''s Bob'\\''s file.ass'" def test_build_video_filter_no_darkness(self, processor): """Test video filter building without darkness overlay.""" @@ -139,13 +148,13 @@ class TestVideoBackgroundProcessor: darkness_percent=0, fonts_dir=None ) - + # Should contain scale and crop assert "scale=w=3840:h=2160:force_original_aspect_ratio=increase,crop=3840:2160" in vf_filter - - # Should contain ASS filter - assert "ass=/path/to/subs.ass" in vf_filter - + + # Should contain ASS filter with single-quoted path + assert "ass='/path/to/subs.ass'" in vf_filter + # Should NOT contain darkening assert "drawbox" not in vf_filter @@ -156,10 +165,10 @@ class TestVideoBackgroundProcessor: darkness_percent=50, fonts_dir=None ) - + # Should contain darkening with correct alpha assert "drawbox=x=0:y=0:w=iw:h=ih:color=black@0.50:t=fill" in vf_filter - + # Should contain ASS filter after darkening assert vf_filter.index("drawbox") < vf_filter.index("ass=") @@ -171,20 +180,21 @@ class TestVideoBackgroundProcessor: darkness_percent=0, fonts_dir="/path/to/fonts" ) - - # Should contain fonts directory in ASS filter - assert "fontsdir=/path/to/fonts" in vf_filter + + # Should contain fonts directory in ASS filter (single-quoted) + assert "fontsdir='/path/to/fonts'" in vf_filter def test_build_video_filter_path_escaping(self, processor): """Test video filter building with special characters in paths.""" + # Test with apostrophe in path vf_filter = processor.build_video_filter( - ass_subtitles_path="C:\\Users\\test\\subs.ass", + ass_subtitles_path="./Avril Lavigne - I'm With You/subs.ass", darkness_percent=0, fonts_dir=None ) - - # Paths should be escaped - assert "C\\:\\\\Users\\\\test\\\\subs.ass" in vf_filter + + # Paths should be single-quoted with apostrophes escaped as '\'' + assert "'./Avril Lavigne - I'\\''m With You/subs.ass'" in vf_filter @patch('subprocess.run') def test_execute_command_with_fallback_gpu_success(self, mock_run, processor_with_nvenc, mock_logger):