Make Animation._repr_html_ more useful by default

QuLogic · QuLogic · commit 690f7d35cab6 · 2026-04-18T04:30:43.000-04:00
While `Animation` does define `_repr_html_`, it does nothing by default
since `animation.html` is 'none'. The 'html5' option is the best, but it
requires FFmpeg to be installed. So introduce a new 'auto' option that
picks either one depending on what's available, and make it the default.
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -1274,7 +1274,7 @@ def _end_redraw(self, event):
         self._resize_id = self._fig.canvas.mpl_connect('resize_event',
                                                        self._on_resize)
 
-    def to_html5_video(self, embed_limit=None):
+    def to_html5_video(self, embed_limit=None, _writer_cls=None):
         """
         Convert the animation to an HTML5 ``<video>`` tag.
 
@@ -1317,10 +1317,11 @@ def to_html5_video(self, embed_limit=None):
                 path = Path(tmpdir, "temp.m4v")
                 # We create a writer manually so that we can get the
                 # appropriate size for the tag
-                Writer = writers[mpl.rcParams['animation.writer']]
-                writer = Writer(codec='h264',
-                                bitrate=mpl.rcParams['animation.bitrate'],
-                                fps=1000. / self._interval)
+                if _writer_cls is None:
+                    _writer_cls = writers[mpl.rcParams['animation.writer']]
+                writer = _writer_cls(codec='h264',
+                                     bitrate=mpl.rcParams['animation.bitrate'],
+                                     fps=1000. / self._interval)
                 self.save(str(path), writer=writer)
                 # Now open and base64 encode.
                 vid64 = base64.encodebytes(path.read_bytes())
@@ -1399,10 +1400,19 @@ def to_jshtml(self, fps=None, embed_frames=True, default_mode=None):
     def _repr_html_(self):
         """IPython display hook for rendering."""
         fmt = mpl.rcParams['animation.html']
+        if fmt == 'none':
+            return
+        kwargs = {}
+        if fmt == 'auto':
+            if writers.is_available('ffmpeg'):
+                fmt = 'html5'
+                kwargs['_writer_cls'] = writers['ffmpeg']
+            else:
+                fmt = 'jshtml'
         if fmt == 'html5':
-            return self.to_html5_video()
+            return self.to_html5_video(**kwargs)
         elif fmt == 'jshtml':
-            return self.to_jshtml()
+            return self.to_jshtml(**kwargs)
 
     def pause(self):
         """Pause the animation."""
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -825,10 +825,11 @@
 ## ***************************************************************************
 ## * ANIMATION                                                               *
 ## ***************************************************************************
-#animation.html: none  # How to display the animation as HTML in
-                       # the IPython notebook:
-                       #     - 'html5' uses HTML5 video tag
-                       #     - 'jshtml' creates a JavaScript animation
+#animation.html: auto  # How to display the animation as HTML in the IPython notebook:
+                       #   - 'none' displays nothing
+                       #   - 'html5' uses HTML5 video tag
+                       #   - 'jshtml' creates a JavaScript animation
+                       #   - 'auto' picks the best available option
 #animation.writer:  ffmpeg        # MovieWriter 'backend' to use
 #animation.codec:   h264          # Codec to use for writing movie
 #animation.bitrate: -1            # Controls size/quality trade-off for movie.
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1448,7 +1448,7 @@ def _convert_validator_spec(key, conv):
     "keymap.copy":       validate_stringlist,
 
     # Animation settings
-    "animation.html":         ["html5", "jshtml", "none"],
+    "animation.html":         ["auto", "html5", "jshtml", "none"],
     # Limit, in MB, of size of base64 encoded animation in HTML
     # (i.e. IPython notebook)
     "animation.embed_limit":  validate_float,
@@ -3354,11 +3354,13 @@ class _Subsection:
     _Section("Animation"),
     _Param(
         "animation.html",
-        default="none",
-        validator=["html5", "jshtml", "none"],
-        description="How to display the animation as HTML in the IPython notebook: "
-                    "- 'html5' uses HTML5 video tag "
-                    "- 'jshtml' creates a JavaScript animation"
+        default="auto",
+        validator=["auto", "html5", "jshtml", "none"],
+        description="How to display the animation as HTML in the IPython notebook:\n"
+                    "- 'auto' picks the best available option\n"
+                    "- 'html5' uses HTML5 video tag\n"
+                    "- 'jshtml' creates a JavaScript animation\n"
+                    "- 'none' displays nothing"
     ),
     _Param(
         "animation.writer",
