Skip to content

install.py should detect missing libass support in ffmpeg (Homebrew lite ffmpeg breaks subtitle burning) #561

Description

@wangliangliang2008

Problem

install.py checks that ffmpeg is installed but does not check whether the
binary was built with libass / libfreetype / fontconfig support.

On macOS, brew install ffmpeg installs a lite build with no
--enable-libass
, so the subtitles= filter is not compiled in:

$ ffmpeg -filters | grep subtitle
# (empty — subtitles filter is missing entirely)

The user only discovers this at the very last step of the pipeline — final
video merge — where _7_sub_into_vid.py or _12_dub_to_vid.py invokes
ffmpeg with a subtitles=...:force_style=... filter and gets the cryptic:

[AVFilterGraph] No option name near 'output/dub.srt:force_style=...'
Error parsing filterchain
Error opening output file ...
Error : Invalid argument

This is especially confusing because the error message looks like a quoting
/ escaping bug (it took me ~2 hours to figure out the filter literally doesn't
exist in the user's ffmpeg).

Reproduction

  1. Fresh macOS install
  2. brew install ffmpeg (the default lite formula)
  3. Run VideoLingo through to the dubbing-merge step
  4. → cryptic ffmpeg error, final video never produced

Suggested fix

In install.py / check_ffmpeg(), after confirming ffmpeg exists, also check
its filter list:

```python
def check_ffmpeg():
# ... existing check that ffmpeg is on PATH ...

# Verify libass support — subtitles filter requires it
result = subprocess.run(
    ['ffmpeg', '-hide_banner', '-filters'],
    capture_output=True, text=True, timeout=10
)
if 'subtitles' not in result.stdout:
    system = platform.system()
    if system == 'Darwin':
        fix_cmd = 'brew install ffmpeg-full && brew unlink ffmpeg && brew link --force --overwrite ffmpeg-full'
    elif system == 'Linux':
        fix_cmd = 'sudo apt install ffmpeg  # or build with --enable-libass'
    else:
        fix_cmd = 'Install ffmpeg with libass / libfreetype / fontconfig support'
    console.print(Panel.fit(
        '❌ Your ffmpeg lacks libass support (the subtitles= filter is missing).\n'
        \"VideoLingo's final subtitle/dubbing merge step will fail.\n\n\"
        f'🛠️  Install a full ffmpeg build:\n[bold cyan]{fix_cmd}[/bold cyan]',
        style='red'
    ))
    raise SystemExit('ffmpeg with libass is required.')

```

This shifts the failure from the last step (after hours of TTS work) to the
install step (seconds), and turns a confusing parse error into an actionable
message.

Environment

  • macOS 26.5 (arm64)
  • Python 3.10.20
  • ffmpeg 8.1.1 (Homebrew lite)
  • VideoLingo main @ dfbdc00

Happy to send a PR for this if interested.

Related: #560 (numpy 2.x fix)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions