Merge pull request matplotlib#7208 from efiring/h264_default

API: change dflt animation codec to h264

Author: tacaswell

doc/users/whats_new.rst

@@ -216,6 +216,18 @@ Support for HiDPI (Retina) displays in the NbAgg and WebAgg backends
 The NbAgg and WebAgg backends will now use the full resolution of your
 high-pixel-density display.
 
+Change in the default animation codec
+-------------------------------------
+
+The default animation codec has been changed from ``mpeg4`` to ``h264``,
+which is more efficient. It can be set via the ``animation.codec`` rcParam.
+
+Deprecated support for mencoder in animation
+--------------------------------------------
+
+The use of mencoder for writing video files with mpl is problematic;
+switching to ffmpeg is strongly advised. All support for mencoder
+will be removed in version 2.2.
 
 
 Previous Whats New

lib/matplotlib/animation.py

@@ -36,7 +36,7 @@
 import contextlib
 import tempfile
 import warnings
-from matplotlib.cbook import iterable, is_string_like
+from matplotlib.cbook import iterable, is_string_like, deprecated
 from matplotlib.compat import subprocess
 from matplotlib import verbose
 from matplotlib import rcParams, rcParamsDefault, rc_context
@@ -60,6 +60,12 @@
 # how-to-encode-series-of-images-into-h264-using-x264-api-c-c )
 
 
+def adjusted_figsize(w, h, dpi, n):
+ wnew = int(w * dpi / n) * n / dpi
+ hnew = int(h * dpi / n) * n / dpi
+ return wnew, hnew
+
+
 # A registry for available MovieWriter classes
 class MovieWriterRegistry(object):
  def __init__(self):
@@ -134,10 +140,6 @@ class MovieWriter(object):
  The format used in writing frame data, defaults to 'rgba'
  '''
 
- # Specifies whether the size of all frames need to be identical
- # i.e. whether we can use savefig.bbox = 'tight'
- frame_size_can_vary = False
-
  def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
  metadata=None):
  '''
@@ -189,8 +191,20 @@ def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
  @property
  def frame_size(self):
  'A tuple (width,height) in pixels of a movie frame.'
- width_inches, height_inches = self.fig.get_size_inches()
- return width_inches * self.dpi, height_inches * self.dpi
+ w, h = self.fig.get_size_inches()
+ return int(w * self.dpi), int(h * self.dpi)
+
+ def _adjust_frame_size(self):
+ if self.codec == 'h264':
+ wo, ho = self.fig.get_size_inches()
+ w, h = adjusted_figsize(wo, ho, self.dpi, 2)
+ if not (wo, ho) == (w, h):
+ self.fig.set_size_inches(w, h, forward=True)
+ verbose.report('figure size (inches) has been adjusted '
+ 'from %s x %s to %s x %s' % (wo, ho, w, h),
+ level='helpful')
+ verbose.report('frame size in pixels is %s x %s' % self.frame_size,
+ level='debug')
 
  def setup(self, fig, outfile, dpi):
  '''
@@ -207,6 +221,7 @@ def setup(self, fig, outfile, dpi):
  self.outfile = outfile
  self.fig = fig
  self.dpi = dpi
+ self._adjust_frame_size()
 
  # Run here so that grab_frame() can write the data to a pipe. This
  # eliminates the need for temp files.
@@ -316,10 +331,6 @@ def isAvailable(cls):
 class FileMovieWriter(MovieWriter):
  '`MovieWriter` subclass that handles writing to a file.'
 
- # In general, if frames are writen to files on disk, it's not important
- # that they all be identically sized
- frame_size_can_vary = True
-
  def __init__(self, *args, **kwargs):
  MovieWriter.__init__(self, *args, **kwargs)
  self.frame_format = rcParams['animation.frame_format']
@@ -345,6 +356,8 @@ def setup(self, fig, outfile, dpi, frame_prefix='_tmp', clear_temp=True):
  self.fig = fig
  self.outfile = outfile
  self.dpi = dpi
+ self._adjust_frame_size()
+
  self.clear_temp = clear_temp
  self.temp_prefix = frame_prefix
  self._frame_counter = 0 # used for generating sequential file names
@@ -500,7 +513,7 @@ class FFMpegFileWriter(FileMovieWriter, FFMpegBase):
  def _args(self):
  # Returns the command line parameters for subprocess to use
  # ffmpeg to create a movie using a collection of temp images
- return [self.bin_path(), '-r', str(self.fps),
+ return [self.bin_path(),  # -r option is not needed before -i option
  '-i', self._base_temp_name(),
  '-vframes', str(self._frame_counter),
  '-r', str(self.fps)] + self.output_args
@@ -560,9 +573,20 @@ def output_args(self):
  return args
 
 
-# Combine Mencoder options with pipe-based writing
+# The message must be a single line; internal newlines cause sphinx failure.
+mencoder_dep = ("Support for mencoder is only partially functional, "
+ "and will be removed entirely in 2.2. "
+ "Please use ffmpeg instead.")
+
+
 @writers.register('mencoder')
 class MencoderWriter(MovieWriter, MencoderBase):
+
+ @deprecated('2.0', message=mencoder_dep)
+ def __init__(self, *args, **kwargs):
+ with rc_context(rc={'animation.codec': 'mpeg4'}):
+ super(MencoderWriter, self).__init__(*args, **kwargs)
+
  def _args(self):
  # Returns the command line parameters for subprocess to use
  # mencoder to create a movie
@@ -577,6 +601,11 @@ def _args(self):
 class MencoderFileWriter(FileMovieWriter, MencoderBase):
  supported_formats = ['png', 'jpeg', 'tga', 'sgi']
 
+ @deprecated('2.0', message=mencoder_dep)
+ def __init__(self, *args, **kwargs):
+ with rc_context(rc={'animation.codec': 'mpeg4'}):
+ super(MencoderFileWriter, self).__init__(*args, **kwargs)
+
  def _args(self):
  # Returns the command line parameters for subprocess to use
  # mencoder to create a movie
@@ -788,7 +817,7 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
  elif (not is_string_like(writer) and
  any(arg is not None
  for arg in (fps, codec, bitrate, extra_args, metadata))):
- raise RuntimeError('Passing in values for arguments for arguments '
+ raise RuntimeError('Passing in values for arguments '
  'fps, codec, bitrate, extra_args, or metadata '
  'is not supported when writer is an existing '
  'MovieWriter instance. These should instead be '
@@ -844,26 +873,16 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
  metadata=metadata)
  except IndexError:
  raise ValueError("Cannot save animation: no writers are "
- "available. Please install mencoder or "
+ "available. Please install "
  "ffmpeg to save animations.")
 
  verbose.report('Animation.save using %s' % type(writer),
  level='helpful')
 
- # FIXME: Using 'bbox_inches' doesn't currently work with
- # writers that pipe the data to the command because this
- # requires a fixed frame size (see Ryan May's reply in this
- # thread: [1]). Thus we drop the 'bbox_inches' argument if it
- # exists in savefig_kwargs.
- #
- # [1] (http://matplotlib.1069221.n5.nabble.com/
- # Animation-class-let-save-accept-kwargs-which-
- # are-passed-on-to-savefig-td39627.html)
- #
- if 'bbox_inches' in savefig_kwargs and not writer.frame_size_can_vary:
+ if 'bbox_inches' in savefig_kwargs:
  warnings.warn("Warning: discarding the 'bbox_inches' argument in "
- "'savefig_kwargs' as it not supported by "
- "{0}).".format(writer.__class__.__name__))
+ "'savefig_kwargs' as it may cause frame size "
+ "to vary, which is inappropriate for animation.")
  savefig_kwargs.pop('bbox_inches')
 
  # Create a new sequence of frames for saved data. This is different
@@ -873,12 +892,10 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
  # since GUI widgets are gone. Either need to remove extra code to
  # allow for this non-existent use case or find a way to make it work.
  with rc_context():
- # See above about bbox_inches savefig kwarg
- if (not writer.frame_size_can_vary and
- rcParams['savefig.bbox'] == 'tight'):
- verbose.report("Disabling savefig.bbox = 'tight', as it is "
- "not supported by "
- "{0}.".format(writer.__class__.__name__),
+ if (rcParams['savefig.bbox'] == 'tight'):
+ verbose.report("Disabling savefig.bbox = 'tight', as it "
+ "may cause frame size to vary, which "
+ "is inappropriate for animation.",
  level='helpful')
  rcParams['savefig.bbox'] = None
  with writer.saving(self._fig, filename, dpi):

lib/matplotlib/rcsetup.py

@@ -1324,7 +1324,7 @@ def validate_animation_writer_path(p):
  # Animation settings
  'animation.html': ['none', validate_movie_html_fmt],
  'animation.writer': ['ffmpeg', validate_movie_writer],
- 'animation.codec': ['mpeg4', six.text_type],
+ 'animation.codec': ['h264', six.text_type],
  'animation.bitrate': [-1, validate_int],
  # Controls image format when frames are written to disk
  'animation.frame_format': ['png', validate_movie_frame_fmt],

matplotlibrc.template

@@ -597,7 +597,7 @@ backend : $TEMPLATE_BACKEND
  # the IPython notebook. 'html5' uses
  # HTML5 video tag.
 #animation.writer : ffmpeg # MovieWriter 'backend' to use
-#animation.codec : mpeg4 # Codec to use for writing movie
+#animation.codec : h264  # Codec to use for writing movie
 #animation.bitrate: -1 # Controls size/quality tradeoff for movie.
  # -1 implies let utility auto-determine
 #animation.frame_format: 'png' # Controls frame format used by temp files