All open/read/write/filter functions in :py:mod:`ffmpegio` accepts any FFmpeg options as their keyword arguments. Two rules apply to construct Python function argument:

1. Drop the - from FFmpeg option name, e.g., enter -ss 50 as (..., ss=50, ...); and
2. All the options are assumed output options by default. To specify input options, append _in to the option name. To apply -ss 50 to input url, enter (..., ss_in=50, ...). Global options are automatically identified.

The option values can be specified in any data type, but it must have a __str__ function defined to convert Python data to correct FFmpeg string expression.

FFmpeg's -s output option sets the output video frame size by using the scale video filter. However, it does not allow non-positive values for width and height which the scale filter accepts. :py:mod:`ffmpegio` alters this behavior by checking the s argument for <=0 width or height and convert to vf argument.

Note that passing both s with a non-positive value and vf will raise an exception.

The output option -map is the (only?) FFmpeg option, which could be specified multiple times in command line input. This goes against :py:mod:`ffmpegio`'s FFmpeg dict structure, and so map argument is handled differently from the others. First, map argument must be a non-str sequence, and each of its element is converted to -map option. Furthermore, each element could be a str or else a sequence which items are then stringified and joined together with ':'.

There are many video pixel formats that FFmpeg support, which you can obtain with :py:func:`caps.pix_fmts()` function. For the I/O purpose, :py:mod:`ffmpegio` video/image functions operate strictly with RGB or grayscale formats listed below.

Note that each video pixel format has a specific dtype (or dtype_in) str argument, which follows the NumPy array data type convention.

FFmpeg offers its audio channels in both interleaved and planar sample formats (sample_fmt, run :py:func:`caps.sample_fmts()` to list available formats). For the I/O purpose, :py:mod:`ffmpegio` audio functions always use the interleaved formats:

Like pix_fmt, sample_fmt also has concrete relationship to the dtype option

While the use of the vf or filter_complex option enables the full spectrum of FFmpeg's filtering capability (FFmpeg Documentation), :py:mod:`ffmpegio`'s video and image routines adds several convenience video options to perform simple video maninpulations without the need of setting up a filtergraph.

Note that the these operations are pre-wired to perform in a specific order:

.. blockdiag::
  :caption: Video Manipulation Order

  blockdiag {
    square_pixels -> crop -> flip -> transpose;
    crop -> flip [folded]
  }

Be aware of this ordering as these filters are non-commutative (i.e., a change in the order of operation alters the outcome). If your desired order of filters differs or need to use additional filters, use the vf option to specify your own filtergraph.

.. plot::

  IM = ffmpegio.image.read('ffmpeg-logo.png')
  plt.figure(figsize=(IM.shape[1]/96, IM.shape[0]/96), dpi=96)
  plt.imshow(IM)
  plt.gca().set_position((0, 0, 1, 1))
  plt.axis('off')

ffmpegio.image.read('ffmpeg-logo.png')

.. plot::

  IM = ffmpegio.image.read('ffmpeg-logo.png', crop=(100,100,0,0), transpose=0)
  plt.figure(figsize=(IM.shape[1]/96, IM.shape[0]/96), dpi=96)
  plt.imshow(IM)
  plt.gca().set_position((0, 0, 1, 1))
  plt.axis('off')

ffmpegio.image.read('ffmpeg-logo.png', crop=(100,100,0,0), transpose=0)

.. plot::

  IM = ffmpegio.image.read('ffmpeg-logo.png', crop=(100,100,0,0), flip='both', s=(200,50))
  plt.figure(figsize=(IM.shape[1]/96, IM.shape[0]/96), dpi=96)
  plt.imshow(IM)
  plt.gca().set_position((0, 0, 1, 1))
  plt.axis('off')

ffmpegio.image.read('ffmpeg-logo.png', crop=(100,100,0,0), flip='both', size=(200,-1))