feat: auto-install animations with bundled ffmpeg

- Move manim, Pillow from optional [animations] to main dependencies
- Add imageio-ffmpeg for cross-platform ffmpeg bundling
- Add --no-animations CLI flag to skip animation processing (for CI)
- Update README to reflect animations are included by default
- Update sample slides with improved manim/animate DSL explanations
- Regenerate gallery screenshots for animation slides

Author: jeremymanning

.github/workflows/ci.yml

@@ -78,13 +78,13 @@ jobs:
         run: pip install -e .
 
       - name: Compile sample presentation (HTML)
-        run: cdl-slides compile examples/sample_presentation.md --format html
+        run: cdl-slides compile examples/sample_presentation.md --format html --no-animations
 
       - name: Verify HTML output exists
         run: test -f examples/sample_presentation.html
 
       - name: Compile sample presentation (PDF)
-        run: cdl-slides compile examples/sample_presentation.md --format pdf
+        run: cdl-slides compile examples/sample_presentation.md --format pdf --no-animations
 
       - name: Verify PDF output exists
         run: test -f examples/sample_presentation.pdf

README.md

@@ -32,7 +32,7 @@ Compile Markdown files into beautiful CDL-themed [Marp](https://marp.app/) prese
 - **Bundled theme**: Complete CDL/Dartmouth-branded theme with custom fonts, colors, and layouts
 - **Smart preprocessing**: Auto-splits long code blocks and tables across slides
 - **Flow diagrams**: Simple ```` ```flow ```` syntax for pipeline diagrams
-- **Manim animations**: Embed animated equations and visualizations with ```` ```manim ```` blocks (optional)
+- **Manim animations**: Embed animated equations and visualizations with ```` ```manim ```` blocks (included by default)
 - **Auto-scaling**: Automatically adjusts font size for dense slides
 - **Syntax highlighting**: Code blocks with line numbers via Pygments
 - **Math support**: KaTeX for inline and display equations
@@ -252,17 +252,11 @@ Use the ```` ```flow ```` syntax for simple pipeline diagrams:
 
 Available colors: `green`, `blue`, `navy`, `teal`, `orange`, `red`, `violet`, `yellow`, `gray`.
 
-### Manim Animations (Optional)
+### Manim Animations
 
 Embed animated math visualizations using [Manim Community](https://www.manim.community/). Animations are rendered to transparent GIFs and embedded in slides.
 
-**Installation:**
-
-```bash
-pip install cdl-slides[animations]
-```
-
-This installs `manim` and `Pillow`. You also need `ffmpeg` installed on your system.
+Animation support is included by default when you install `cdl-slides`. FFmpeg is bundled automatically via `imageio-ffmpeg` — no system installation required.
 
 **Usage:**
 
@@ -344,7 +338,7 @@ fade-in eq1
 
 **Available colors:** blue, red, green, yellow, orange, white, black
 
-Note: The animate DSL requires the same `cdl-slides[animations]` install as manim blocks.
+Note: The animate DSL is included by default with `cdl-slides` — no extra installation needed.
 
 ### Scale Directives
 

docs/screenshots/12-manim-animation.png

@@ -1102,22 +1102,24 @@ <h1 id="flow-diagrams">Flow diagrams</h1>
 </div>
 </section>
 </foreignObject></svg><svg data-marpit-svg="" viewBox="0 0 1280 720"><foreignObject width="1280" height="720"><section id="16" data-class="scale-85" data-theme="cdl-theme" lang="en-US" class="scale-85" style="--class:scale-85;--theme:cdl-theme;" data-transition-back="{&quot;name&quot;:&quot;fade&quot;,&quot;duration&quot;:&quot;0.25s&quot;,&quot;builtinFallback&quot;:true}" data-transition="{&quot;name&quot;:&quot;fade&quot;,&quot;duration&quot;:&quot;0.25s&quot;,&quot;builtinFallback&quot;:true}">
-<h1 id="manim-animations-optional">Manim animations (optional)</h1>
+<h1 id="manim-animations">Manim animations</h1>
 <div style="display: flex; gap: 1.5em;">
 <div style="flex: 1;">
 <p><img src="animations/WaveAnimation_51150ee0.gif" alt="" style="height:380px;" /></p>
 </div>
 <div style="flex: 1;">
-<div class="note-box" data-title="Setup">
-<p><code>pip install cdl-slides[animations]</code></p>
+<div class="note-box" data-title="How it works">
+<p>CDL-slides automatically transpiles <code>```manim</code> blocks to Python, renders to MP4, and converts to transparent GIF. No manual steps needed!</p>
 </div>
-<div class="example-box" data-title="Markdown syntax">
-<pre style="margin: 0; font-size: 0.7em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;manim
+<div class="example-box" data-title="Markdown source">
+<pre style="margin: 0; font-size: 0.65em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;manim
 # scene: WaveAnimation
 # height: 380
 class WaveAnimation(Scene):
     def construct(self):
-        ...
+        axes = Axes(...)
+        wave = axes.plot(np.sin)
+        self.play(Create(axes))
 &#96;&#96;&#96;</pre>
 </div>
 </div>
@@ -1130,15 +1132,15 @@ <h1 id="animate-dsl">Animate DSL</h1>
 <p><img src="animations/AnimateScene_c963e8d5.gif" alt="" style="height:380px;" /></p>
 </div>
 <div style="flex: 1;">
-<div class="tip-box" data-title="Simplified">
-<p>No Python needed! Transpiles to manim.</p>
+<div class="note-box" data-title="DSL features">
+<p>No Python needed! Also supports: <code>create circle/square/arrow</code>, <code>transform A -&gt; B</code>, positions like <code>above/below/left-of</code>. See <a href="https://github.com/ContextLab/cdl-slides#animate-dsl-simplified-animation-syntax">README</a>.</p>
 </div>
-<div class="example-box" data-title="Markdown syntax">
-<pre style="margin: 0; font-size: 0.7em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;animate
+<div class="example-box" data-title="Markdown source">
+<pre style="margin: 0; font-size: 0.65em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;animate
 height: 380
-write equation "E = mc^2" as eq
+write equation "..." as integral
 wait 0.5
-fade-in eq
+fade-in integral
 &#96;&#96;&#96;</pre>
 </div>
 </div>

docs/screenshots/13-animate-dsl.png

@@ -252,7 +252,7 @@ KaTeX is used for math rendering. Use `$...$` for inline and `$$...$$` for displ
 
 ---
 
-# Manim animations (optional)
+# Manim animations
 <!-- _class: scale-85 -->
 
 <div style="display: flex; gap: 1.5em;">
@@ -276,20 +276,22 @@ class WaveAnimation(Scene):
 </div>
 <div style="flex: 1;">
 
-<div class="note-box" data-title="Setup">
+<div class="note-box" data-title="How it works">
 
-`pip install cdl-slides[animations]`
+CDL-slides automatically transpiles ` ```manim ` blocks to Python, renders to MP4, and converts to transparent GIF. No manual steps needed!
 
 </div>
 
-<div class="example-box" data-title="Markdown syntax">
+<div class="example-box" data-title="Markdown source">
 
-<pre style="margin: 0; font-size: 0.7em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;manim
+<pre style="margin: 0; font-size: 0.65em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;manim
 # scene: WaveAnimation
 # height: 380
 class WaveAnimation(Scene):
     def construct(self):
-        ...
+        axes = Axes(...)
+        wave = axes.plot(np.sin)
+        self.play(Create(axes))
 &#96;&#96;&#96;</pre>
 
 </div>
@@ -316,19 +318,19 @@ fade-in integral
 </div>
 <div style="flex: 1;">
 
-<div class="tip-box" data-title="Simplified">
+<div class="note-box" data-title="DSL features">
 
-No Python needed! Transpiles to manim.
+No Python needed! Also supports: `create circle/square/arrow`, `transform A -> B`, positions like `above/below/left-of`. See [README](https://github.com/ContextLab/cdl-slides#animate-dsl-simplified-animation-syntax).
 
 </div>
 
-<div class="example-box" data-title="Markdown syntax">
+<div class="example-box" data-title="Markdown source">
 
-<pre style="margin: 0; font-size: 0.7em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;animate
+<pre style="margin: 0; font-size: 0.65em; background: rgba(0,105,62,0.08); padding: 0.3em; border-radius: 4px; white-space: pre-wrap;">&#96;&#96;&#96;animate
 height: 380
-write equation "E = mc^2" as eq
+write equation "..." as integral
 wait 0.5
-fade-in eq
+fade-in integral
 &#96;&#96;&#96;</pre>
 
 </div>

examples/sample_presentation.html

@@ -30,17 +30,19 @@ classifiers = [
 dependencies = [
     "click>=8.0",
     "pygments>=2.15",
+    # Animation support (included by default)
+    "manim>=0.18.0",
+    "Pillow>=9.0",
+    "imageio-ffmpeg>=0.5.1",  # Bundled ffmpeg binary
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
     "ruff>=0.4",
 ]
-animations = [
-    "manim>=0.18.0",
-    "Pillow>=9.0",
-]
+# Kept for backwards compatibility - animations now included by default
+animations = []
 
 [project.urls]
 Homepage = "https://www.context-lab.com"

examples/sample_presentation.md

@@ -93,6 +93,12 @@ def main() -> None:
     default=None,
     help="Custom theme directory.",
 )
+@click.option(
+    "--no-animations",
+    is_flag=True,
+    default=False,
+    help="Skip processing of manim and animate blocks (useful for CI).",
+)
 def compile(
     input_file: Path,
     output: Optional[Path],
@@ -102,6 +108,7 @@ def compile(
     no_split: bool,
     keep_temp: bool,
     theme_dir: Optional[Path],
+    no_animations: bool,
 ) -> None:
     """Compile a Markdown file into a CDL-themed Marp presentation."""
     from cdl_slides.compiler import CompilationError, compile_presentation
@@ -118,6 +125,7 @@ def compile(
             no_split=no_split,
             keep_temp=keep_temp,
             theme_dir=theme_dir,
+            skip_animations=no_animations,
         )
     except FileNotFoundError as exc:
         click.echo(click.style(f"Error: {exc}", fg="red"), err=True)

pyproject.toml

@@ -91,6 +91,7 @@ def compile_presentation(
     no_split: bool = False,
     keep_temp: bool = False,
     theme_dir: Optional[Path] = None,
+    skip_animations: bool = False,
 ) -> dict:
     """Compile a Markdown file into a CDL-themed Marp presentation.
 
@@ -156,6 +157,7 @@ def compile_presentation(
             max_lines=max_lines,
             max_table_rows=max_table_rows,
             no_split=no_split,
+            skip_animations=skip_animations,
         )
 
         results: Dict[str, object] = {

src/cdl_slides/cli.py

@@ -45,8 +45,19 @@
 except ImportError:
     pass
 
-# Check for FFmpeg availability
-FFMPEG_AVAILABLE = shutil.which("ffmpeg") is not None
+# Check for FFmpeg availability via imageio-ffmpeg (bundled) or system PATH
+FFMPEG_PATH: Optional[str] = None
+FFMPEG_AVAILABLE = False
+try:
+    import imageio_ffmpeg
+
+    FFMPEG_PATH = imageio_ffmpeg.get_ffmpeg_exe()
+    FFMPEG_AVAILABLE = True
+except (ImportError, RuntimeError):
+    _system_ffmpeg = shutil.which("ffmpeg")
+    if _system_ffmpeg:
+        FFMPEG_PATH = _system_ffmpeg
+        FFMPEG_AVAILABLE = True
 
 
 def check_dependencies() -> Tuple[bool, list]:
@@ -59,7 +70,7 @@ def check_dependencies() -> Tuple[bool, list]:
     if not MANIM_AVAILABLE:
         missing.append("manim (pip install manim)")
     if not FFMPEG_AVAILABLE:
-        missing.append("ffmpeg (brew install ffmpeg / apt install ffmpeg)")
+        missing.append("ffmpeg (pip install imageio-ffmpeg)")
     if not PIL_AVAILABLE:
         missing.append("Pillow (pip install Pillow)")
     return len(missing) == 0, missing
@@ -293,10 +304,11 @@ def convert_mp4_to_gif(
     palette_path = gif_path.with_suffix(".palette.png")
 
     try:
+        ffmpeg_cmd = FFMPEG_PATH or "ffmpeg"
         # Step 1: Generate palette with transparency support
         vf_palette = f"fps={fps},scale={scale_width}:-1:flags=lanczos,palettegen=reserve_transparent=1:stats_mode=diff"
         subprocess.run(
-            ["ffmpeg", "-y", "-i", str(mp4_path), "-vf", vf_palette, str(palette_path)],
+            [ffmpeg_cmd, "-y", "-i", str(mp4_path), "-vf", vf_palette, str(palette_path)],
             capture_output=True,
             check=True,
         )
@@ -307,7 +319,7 @@ def convert_mp4_to_gif(
         )
         subprocess.run(
             [
-                "ffmpeg",
+                ffmpeg_cmd,
                 "-y",
                 "-i",
                 str(mp4_path),