Added `media_embed` config option to control whether media in Jupyter notebooks is embedded (#2442)

* feat: Added --embed option to %%manim ManimMagic.

* feat: Change to --embed and also embed Images

* Update manim/utils/ipython_magic.py

Co-authored-by: Benjamin Hackl <devel@benjamin-hackl.at>

* Initial attempt to make media_embed a general config option

* fixed issues raised in code review

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* remove unused import

* actually remove unused import

Co-authored-by: Benjamin Hackl <devel@benjamin-hackl.at>
Co-authored-by: Michael McNeil Forbes <michael.forbes+python@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

example_scenes/manim_jupyter_example.ipynb

@@ -32,6 +32,8 @@
     "\n",
     "# set the maximum width for video outputs to a predefined value\n",
     "config.media_width = \"20vw\"\n",
+    "# embed video\n",
+    "config.media_embed = True\n",
     "\n",
     "class HelloManim(Scene):\n",
     "    def construct(self):\n",

manim/_config/default.cfg

@@ -202,4 +202,5 @@ repr_number = green
 loglevel = ERROR
 
 [jupyter]
+media_embed =
 media_width = 60%%

manim/_config/utils.py

@@ -253,6 +253,7 @@ class ManimConfig(MutableMapping):
         "from_animation_number",
         "images_dir",
         "input_file",
+        "media_embed",
         "media_width",
         "webgl_renderer_path",
         "log_dir",
@@ -627,6 +628,12 @@ class ManimConfig(MutableMapping):
         if val:
             self.ffmpeg_loglevel = val
 
+        try:
+            val = parser["jupyter"].getboolean("media_embed")
+        except ValueError:
+            val = None
+        setattr(self, "media_embed", val)
+
         val = parser["jupyter"].get("media_width")
         if val:
             setattr(self, "media_width", val)
@@ -971,6 +978,12 @@ class ManimConfig(MutableMapping):
         doc="Verbosity level of ffmpeg (no flag).",
     )
 
+    media_embed = property(
+        lambda self: self._d["media_embed"],
+        lambda self, val: self._d.__setitem__("media_embed", val),
+        doc="Embed videos in Jupyter notebook",
+    )
+
     media_width = property(
         lambda self: self._d["media_width"],
         lambda self, val: self._d.__setitem__("media_width", val),

manim/utils/ipython_magic.py

@@ -78,6 +78,14 @@ else:
                 which is 25% of your current viewport width. To allow the output to become as large
                 as possible, set ``config.media_width = "100%"``.
 
+                The ``media_embed`` option will embed the image/video output in the notebook. This is
+                generally undesirable as it makes the notebooks very large, but is required on some
+                platforms (notably Google's CoLab, where it is automatically enabled unless suppressed
+                by ``config.embed = False``) and needed in cases when the notebook (or converted HTML
+                file) will be moved relative to the video locations. Use-cases include building
+                documentation with Sphinx and JupyterBook. See also the :mod:`manim directive for Sphinx
+                <manim.utils.docbuild.manim_directive>`.
+
             Examples
             --------
 
@@ -88,6 +96,7 @@ else:
                 %%manim -v WARNING --disable_caching -qm BannerExample
 
                 config.media_width = "75%"
+                config.media_embed = True
 
                 class BannerExample(Scene):
                     def construct(self):
@@ -112,6 +121,7 @@ else:
             if not len(args) or "-h" in args or "--help" in args or "--version" in args:
                 main(args, standalone_mode=False, prog_name="manim")
                 return
+
             modified_args = self.add_additional_args(args)
             args = main(modified_args, standalone_mode=False, prog_name="manim")
             with tempconfig(local_ns.get("config", {})):
@@ -163,20 +173,23 @@ else:
                 shutil.copy(local_path, tmpfile)
 
                 file_type = mimetypes.guess_type(config["output_file"])[0]
+                embed = config["media_embed"]
+                if embed is None:
+                    # videos need to be embedded when running in google colab.
+                    # do this automatically in case config.media_embed has not been
+                    # set explicitly.
+                    embed = "google.colab" in str(get_ipython())
+
                 if file_type.startswith("image"):
-                    display(Image(filename=config["output_file"]))
-                    return
-
-                # videos need to be embedded when running in google colab
-                video_embed = "google.colab" in str(get_ipython())
-
-                display(
-                    Video(
+                    result = Image(filename=config["output_file"], embed=embed)
+                else:
+                    result = Video(
                         tmpfile,
                         html_attributes=f'controls autoplay loop style="max-width: {config["media_width"]};"',
-                        embed=video_embed,
-                    ),
-                )
+                        embed=embed,
+                    )
+
+                display(result)
 
         def add_additional_args(self, args: list[str]) -> list[str]:
             additional_args = ["--jupyter"]