Make Animation._repr_html_ more useful by default

QuLogic · QuLogic · commit cfeababfc127 · 2026-04-16T14:55:10.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
@@ -1399,6 +1399,13 @@ 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
+        if fmt == 'auto':
+            if writers.is_available(mpl.rcParams['animation.writer']):
+                fmt = 'html5'
+            else:
+                fmt = 'jshtml'
         if fmt == 'html5':
             return self.to_html5_video()
         elif fmt == 'jshtml':
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: html5  # 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",
