manim-headless-rendering

name	manim-headless-rendering
description	Guidelines for rendering Manim animations in a headless Linux environment (no GUI). Includes troubleshooting common errors, choosing correct renderer, managing long renders, and concatenating partial video files produced by Manim.
version	1.0.0

Overview

When to Use

Guidelines for rendering Manim animations in a headless Linux environment (no GUI). Includes troubleshooting common errors, choosing correct renderer, managing long renders, and concatenating partial video files produced by Manim.

Overview

This skill contains a reusable operational workflow. Follow the existing task-specific steps and examples in the sections below.

Pitfalls

• Do not hardcode credentials, tokens, or personal secrets.
• Verify external service URLs, paths, and permissions before making changes.
• Keep generated outputs reproducible and record input assumptions.

Verification

• Confirm required inputs and credentials are available.
• Run the smallest safe command or example before scaling up.
• Check produced files, API responses, or plots before reporting success.

When running Manim on a server or CI environment without a display, the default OpenGL renderer may fail or hang. Use the cairo renderer, which works without an X server.

manim -qh --renderer=cairo path/to/script.py SceneName

If the animation is long, run it in the background to avoid the 600 s foreground timeout:

manim -qh --renderer=cairo path/to/script.py SceneName \
    --media_dir /tmp/manim_media \
    &> /tmp/manim.log &

You can also use the built‑in background mode:

manim -qh path/to/script.py SceneName --background --notify_on_complete

Common Errors & Fixes

Symptom	Cause	Fix
NameError: ShowCreation is not defined	Script used ShowCreation which was removed in recent Manim versions.	Replace with Create (or Write/FadeIn).
Invalid value for --renderer: software	Wrong renderer name.	Use cairo or opengl.
Process times out after 600 s	Foreground render exceeded limit.	Run in background with notify_on_complete or split animation into smaller scenes.
ffmpeg concat file error: string required	Concatenation list file had empty lines or missing quotes.	Generate the list with: `ls *.mp4

Managing Partial Movies

Manim writes each animation chunk as a separate partial_movie_files MP4. To combine them:

1. Locate the directory, e.g. /home/hermes/media/videos/YourScene/480p15/partial_movie_files/YourScene/.
2. Create a concat list:

   find . -name "*.mp4" | sort | while read f; do echo "file '$PWD/$f'"; done > /tmp/concat.txt
   

3. Run ffmpeg:

   ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt -c copy output.mp4
   

   Ensure the concat.txt contains lines like file '/full/path/video.mp4' with no blank lines.

Tips for Quick Render

• Use low resolution (-ql) for drafts, high (-qh) for final.
• Keep scene length under a minute; split longer videos into multiple Scene classes.
• Avoid heavy vector graphics; raster images load faster.
• Pre‑define colours and fonts globally to reduce object creation overhead.

Example Minimal Script

from manim import *

class Demo(Scene):
    def construct(self):
        self.camera.background_color = "#0D1117"
        txt = Text("4MOST", font="DejaVu Sans Mono", color=WHITE)
        self.play(Write(txt))
        self.wait(1)

Render with:

manim -qh --renderer=cairo demo.py Demo

References

• Manim documentation: https://docs.manim.community/en/stable/
• Manim GitHub issues on headless rendering.
• FFmpeg concat demuxer docs.

---