Huanshere / Huanshere/VideoLingo

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

Open Beginner friendly
#561 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
18.5k
Forks
2k
Avg merge
7h 41m
Merged PRs (30d)
12

Description

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)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in install.py at check_ffmpeg(), then review the ffmpeg invocations in _7_sub_into_vid.py and _12_dub_to_vid.py. Verify the check distinguishes a missing subtitles filter and reports an actionable install message before the final merge step; test with an ffmpeg build that has and lacks libass support.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.