fix: Escape FFmpeg filter paths using single-quote wrapping (#212)

## 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 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.5 authored and GitHub committed 2026-01-06 03:50:24 +00:00
1 parent 2110d0f84b
commit 60af90de31
6 files changed
+161 -50

No files matched your search

+33
View File
@@ -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.
+9 -4
View File
@@ -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):
"""
@@ -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]:
@@ -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
+1 -1
View File
@@ -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 <andrew@beveridge.uk>"]
license = "MIT"
+34 -24
View File
@@ -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):