Skip to content

FFdecoder API Parameters

source

This parameter defines the input source (-i) for decoding real-time frames.

FFdecoder API will throw Assertion if source provided is invalid or missing.

FFdecoder API checks for video bitrate or frame-size and framerate in video's metadata to ensure given input source has usable video stream available. Thereby, it will throw ValueError if it fails to find those parameters.

Multiple video inputs are not yet supported!

Data-Type: String.

Its valid input can be one of the following:

  • Filepath: Valid path of the video file, for e.g "/home/foo.mp4" as follows:

    # initialize and formulate the decoder with `foo.mp4` source
    decoder = FFdecoder('/home/foo.mp4').formulate()
    

    Related usage recipes can found here ➶

  • Image Sequence: Valid image sequence such as sequential('img%03d.png') or glob pattern('*.png') or single (looping) image as input:

    How to start with specific number image?

    You can use -start_number FFmpeg parameter if you want to start with specific number image:

    # define `-start_number` such as `5`
    ffparams = {"-ffprefixes":["-start_number", "5"]}
    
    # initialize and formulate the decoder with define parameters
    decoder = FFdecoder('img%03d.png', verbose=True, **ffparams).formulate()
    
    # initialize and formulate the decoder
    decoder = FFdecoder('img%03d.png').formulate()
    

    Bash-style globbing (* represents any number of any characters) is useful if your images are sequential but not necessarily in a numerically sequential order.

    The glob pattern is not available on Windows builds.

    # define `-pattern_type glob` for accepting glob pattern
    sourcer_params = {"-ffprefixes":["-pattern_type", "glob"]}
    
    # initialize and formulate the decoder with define parameters
    decoder = FFdecoder('img*.png', verbose=True, **sourcer_params).formulate()
    
    # define `-loop 1` for looping
    ffparams = {"-ffprefixes":["-loop", "1"]}
    
    # initialize and formulate the decoder with define parameters
    decoder = FFdecoder('img.jpg', verbose=True, **ffparams).formulate()
    

    Related usage recipes can found here ➶

  • Network Address: Valid (http(s), rtp, rstp, rtmp, mms, etc.) incoming network stream address such as 'rtsp://xx:yy@192.168.1.ee:fd/av0_0' as input:

    # define `rtsp_transport` or necessary parameters 
    ffparams = {"-ffprefixes":["-rtsp_transport", "tcp"]}
    
    # initialize and formulate the decoder with define parameters
    decoder = FFdecoder('rtsp://xx:yy@192.168.1.ee:fd/av0_0', verbose=True, **ffparams).formulate()
    

    Related usage recipes can found here ➶

  • Camera Device Index: Valid "device index" or "camera index" of the connected Camera Device. One can easily Capture desired Camera Device in FFdecoder API by specifying its matching index value (use Sourcer API's enumerate_devices to list them) either as integer or string of integer type to its source parameter. For example, for capturing "0" index device on Windows, we can do as follows in FFdecoder API:

    Requirement for Index based Camera Device Capturing in FFdecoder API
    • MUST have appropriate FFmpeg binaries, Drivers, and Softwares installed:

      Internally, DeFFcode APIs achieves Index based Camera Device Capturing by employing some specific FFmpeg demuxers on different platforms(OSes). These platform specific demuxers are as follows:

      Platform(OS) Demuxer
      Windows OS dshow (or DirectShow)
      Linux OS video4linux2 (or its alias v4l2)
      Mac OS avfoundation

      ⚠ Important: Kindly make sure your FFmpeg binaries support these platform specific demuxers as well as system have the appropriate video drivers and related softwares installed.

    • The source parameter value MUST be exactly the probed Camera Device index (use Sourcer API's enumerate_devices to list them).

    • The source_demuxer parameter value MUST be either None(also means empty) or "auto".
    Important Facts related to Camera Device Indexing
    • Camera Device indexes are 0-indexed. So the first device is at 0, second is at 1, so on. So if the there are n devices, the last device is at n-1.
    • Camera Device indexes can be of either integer (e.g. 0,1, etc.) or string of integer (e.g. "0","1", etc.) type.
    • Camera Device indexes can be negative (e.g. -1,-2, etc.), this means you can also start indexing from the end.
      • For example, If there are three devices:
        {0: 'Integrated Camera', 1: 'USB2.0 Camera', 2: 'DroidCam Source'}
        
      • Then, You can specify Positive Indexes and its Equivalent Negative Indexes as follows:

        Positive Indexes Equivalent Negative Indexes
        FFdecoder("0").formulate() FFdecoder("-3").formulate()
        FFdecoder("1").formulate() FFdecoder("-2").formulate()
        FFdecoder("2").formulate() FFdecoder("-1").formulate()

    Out of Index Camera Device index values will raise ValueError in FFdecoder API

    # initialize and formulate the decoder with "0" index source for BGR24 output
    decoder = FFdecoder("0", frame_format="bgr24", verbose=True).formulate()
    

    Related usage recipes can found here ➶

  • Video Capture Device Name/Path: Valid video capture device's name (e.g. "USB2.0 Camera") or its path (e.g. "/dev/video0" on linux) or its index (e.g. "0") as input w.r.t source_demuxer parameter value in use. For example, for capturing "USB2.0 Camera" named device with dshow source demuxer on Windows, we can do as follows in FFdecoder API:

    Identifying and Specifying Device name/path/index and suitable Demuxer on different OSes

    Windows OS users can use the dshow (DirectShow) to list video input device which is the preferred option for Windows users. You can refer following steps to identify and specify your input video device's name:

    • Identify Video Devices: You can locate your video device's name (already connected to your system) using dshow as follows:

      c:\> ffmpeg.exe -list_devices true -f dshow -i dummy
      
      ffmpeg version N-45279-g6b86dd5... --enable-runtime-cpudetect
        libavutil      51. 74.100 / 51. 74.100
        libavcodec     54. 65.100 / 54. 65.100
        libavformat    54. 31.100 / 54. 31.100
        libavdevice    54.  3.100 / 54.  3.100
        libavfilter     3. 19.102 /  3. 19.102
        libswscale      2.  1.101 /  2.  1.101
        libswresample   0. 16.100 /  0. 16.100
      [dshow @ 03ACF580] DirectShow video devices
      [dshow @ 03ACF580]  "Integrated Camera"
      [dshow @ 03ACF580]  "USB2.0 Camera"
      [dshow @ 03ACF580] DirectShow audio devices
      [dshow @ 03ACF580]  "Microphone (Realtek High Definition Audio)"
      [dshow @ 03ACF580]  "Microphone (USB2.0 Camera)"
      dummy: Immediate exit requested
      
    • Specify Video Device's name: Then, you can specify and initialize your located Video device's name in FFdecoder API as follows:

      # initialize and formulate the decoder with "USB2.0 Camera" source for BGR24 output
      decoder = FFdecoder("USB2.0 Camera", source_demuxer="dshow", frame_format="bgr24", verbose=True).formulate()
      
    • [OPTIONAL] Specify Video Device's index along with name: If there are multiple Video devices with similar name, then you can use -video_device_number parameter to specify the arbitrary index of the particular device. For instance, to open second video device with name "Camera" you can do as follows:

      # define video_device_number as 1 (numbering start from 0)
      ffparams = {"-ffprefixes":["-video_device_number", "1"]}
      
      # initialize and formulate the decoder with "Camera" source for BGR24 output
      decoder = FFdecoder("Camera", source_demuxer="dshow", frame_format="bgr24", verbose=True, **ffparams).formulate()
      

    Linux OS users can use the video4linux2 (or its alias v4l2) to list to all capture video devices such as from an USB webcam. You can refer following steps to identify and specify your capture video device's path:

    • Identify Video Devices: Linux systems tend to automatically create file device node/path when the device (e.g. an USB webcam) is plugged into the system, and has a name of the kind '/dev/videoN', where N is a index associated to the device. To get the list of all available file device node/path on your Linux machine, you can use the v4l-ctl command.

      You can use sudo apt install v4l-utils APT command to install v4l-ctl tool on Debian-based Linux distros.

      $ v4l2-ctl --list-devices
      
      USB2.0 PC CAMERA (usb-0000:00:1d.7-1):
              /dev/video1
      
      UVC Camera (046d:0819) (usb-0000:00:1d.7-2):
              /dev/video0
      
    • Specify Video Device's path: Then, you can specify and initialize your located Video device's path in FFdecoder API as follows:

      # initialize and formulate the decoder with "/dev/video0" source for BGR24 output
      decoder = FFdecoder("/dev/video0", source_demuxer="v4l2", frame_format="bgr24", verbose=True).formulate()
      
    • [OPTIONAL] Specify Video Device's additional specifications: You can also specify additional specifications (such as pixel format(s), video format(s), framerate, and frame dimensions) supported by your Video Device as follows:

      You can use ffmpeg -f v4l2 -list_formats all -i /dev/video0 terminal command to list available specifications.

      # define video device specifications
      ffparams = {"-ffprefixes":["-framerate", "25", "-video_size", "640x480"]}
      
      # initialize and formulate the decoder with "/dev/video0" source for BGR24 output
      decoder = FFdecoder("/dev/video0", source_demuxer="v4l2", frame_format="bgr24", verbose=True, **ffparams).formulate()
      

    MacOS users can use the AVFoundation to list input devices and is the currently recommended framework by Apple for streamgrabbing on Mac OSX-10.7 (Lion) and later as well as on iOS. You can refer following steps to identify and specify your capture video device's name or index on MacOS/OSX machines:

    QTKit is also available for streamgrabbing on Mac OS X 10.4 (Tiger) and later, but has been marked deprecated since OS X 10.7 (Lion) and may not be available on future releases.

    • Identify Video Devices: Then, You can locate your Video device's name and index using avfoundation as follows:

      $ ffmpeg -f avfoundation -list_devices true -i ""
      
      ffmpeg version N-45279-g6b86dd5... --enable-runtime-cpudetect
        libavutil      51. 74.100 / 51. 74.100
        libavcodec     54. 65.100 / 54. 65.100
        libavformat    54. 31.100 / 54. 31.100
        libavdevice    54.  3.100 / 54.  3.100
        libavfilter     3. 19.102 /  3. 19.102
        libswscale      2.  1.101 /  2.  1.101
        libswresample   0. 16.100 /  0. 16.100
      [AVFoundation input device @ 0x7f8e2540ef20] AVFoundation video devices:
      [AVFoundation input device @ 0x7f8e2540ef20] [0] FaceTime HD camera (built-in)
      [AVFoundation input device @ 0x7f8e2540ef20] [1] Capture screen 0
      [AVFoundation input device @ 0x7f8e2540ef20] AVFoundation audio devices:
      [AVFoundation input device @ 0x7f8e2540ef20] [0] Blackmagic Audio
      [AVFoundation input device @ 0x7f8e2540ef20] [1] Built-in Microphone
      
    • Specify Video Device's name or index: Then, you can specify and initialize your located Video device in FFdecoder API using its either the name or the index shown in the device listing:

      # initialize and formulate the decoder with `1` index source for BGR24 output
      decoder = FFdecoder("1", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
      

      When specifying device's name, abbreviations using just the beginning of the device name are possible. Thus, to capture from a device named "Integrated iSight-camera" just "Integrated" is sufficient:

      # initialize and formulate the decoder with "Integrated iSight-camera" source for BGR24 output
      decoder = FFdecoder("Integrated", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
      
    • [OPTIONAL] Specify Default Video device: You can also use the default device which is usually the first device in the listing by using "default" as source:

      # initialize and formulate the decoder with "default" source for BGR24 output
      decoder = FFdecoder("default", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
      

    If these steps doesn't work for you then reach us out on Gitter ➶ Community channel

    # initialize and formulate the decoder with "USB2.0 Camera" source for BGR24 output
    decoder = FFdecoder("USB2.0 Camera", source_demuxer="dshow", frame_format="bgr24", verbose=True).formulate()
    

    Related usage recipe can found here ➶

  • Screen Capturing/Recording: Valid screen capture device's name (e.g. "desktop") or its index (e.g. ":0.0") as input w.r.t source_demuxer parameter value in use. You can also specify additional specifications (such as limiting capture area to a region, setting capturing coordinates, whether to capture mouse pointer and clicks etc.). For example, for capturing "0:" indexed device with avfoundation source demuxer on MacOS along with mouse pointer and clicks, we can do as follows in FFdecoder API:

    Specifying suitable Parameter(s) and Demuxer for Capturing your Desktop on different OSes

    Windows OS users can use the gdigrab to grab video from the Windows screen. You can refer following steps to specify source for capturing different regions of your display:

    For Windows OS users dshow is also available for grabbing frames from your desktop. But it is highly unreliable and don't works most of the times.

    • Capturing entire desktop: For capturing all your displays as one big contiguous display, you can specify source, suitable parameters and demuxers in FFdecoder API as follows:

      # define framerate
      ffparams = {"-framerate": "30"}
      
      # initialize and formulate the decoder with "desktop" source for BGR24 output
      decoder = FFdecoder("desktop", source_demuxer="gdigrab", frame_format="bgr24", verbose=True, **ffparams).formulate()
      
    • Capturing a region: If you want to limit capturing to a region, and show the area being grabbed, you can specify source and suitable parameters in FFdecoder API as follows:

      x_offset and y_offset specify the offsets of the grabbed area with respect to the top-left border of the desktop screen. They default to 0.

      # define suitable parameters
      ffparams = {
          "-framerate": "30", # input framerate
          "-ffprefixes": [
              "-offset_x", "10", "-offset_y", "20", # grab at position 10,20
              "-video_size", "640x480", # frame size
              "-show_region", "1", # show only region
          ],
      }
      
      # initialize and formulate the decoder with "desktop" source for BGR24 output
      decoder = FFdecoder("desktop", source_demuxer="gdigrab", frame_format="bgr24", verbose=True, **ffparams).formulate()
      

    Linux OS users can use the x11grab to capture an X11 display. You can refer following steps to specify source for capturing different regions of your display:

    For X11 display, the source input has the syntax: "display_number.screen_number[+x_offset,y_offset]".

    • Capturing entire desktop: For capturing all your displays as one big contiguous display, you can specify source, suitable parameters and demuxers in FFdecoder API as follows:

      # define framerate
      ffparams = {"-framerate": "30"}
      
      # initialize and formulate the decoder with ":0.0" desktop source for BGR24 output
      decoder = FFdecoder(":0.0", source_demuxer="x11grab", frame_format="bgr24", verbose=True, **ffparams).formulate()
      
    • Capturing a region: If you want to limit capturing to a region, and show the area being grabbed, you can specify source and suitable parameters in FFdecoder API as follows:

      x_offset and y_offset specify the offsets of the grabbed area with respect to the top-left border of the X11 screen. They default to 0.

      # define suitable parameters
      ffparams = {
          "-framerate": "30", # input framerate
          "-ffprefixes": [
              "-video_size", "1024x768", # frame size
          ],
      }
      
      # initialize and formulate the decoder with ":0.0" desktop source(starting with the upper-left corner at x=10, y=20) 
      # for BGR24 output
      decoder = FFdecoder(":0.0+10,20", source_demuxer="x11grab", frame_format="bgr24", verbose=True, **ffparams).formulate()
      

    MacOS users can use the AVFoundation to list input devices and is the currently recommended framework by Apple for stream capturing on Mac OSX-10.7 (Lion) and later as well as on iOS. You can refer following steps to identify and specify your capture video device's name or index on MacOS/OSX machines:

    QTKit is also available for stream capturing on Mac OS X 10.4 (Tiger) and later, but has been marked deprecated since OS X 10.7 (Lion) and may not be available on future releases.

    • Identify Video Devices: You can enumerate all the available input devices including screens ready to be captured using avfoundation as follows:

      $ ffmpeg -f avfoundation -list_devices true -i ""
      
      ffmpeg version N-45279-g6b86dd5... --enable-runtime-cpudetect
        libavutil      51. 74.100 / 51. 74.100
        libavcodec     54. 65.100 / 54. 65.100
        libavformat    54. 31.100 / 54. 31.100
        libavdevice    54.  3.100 / 54.  3.100
        libavfilter     3. 19.102 /  3. 19.102
        libswscale      2.  1.101 /  2.  1.101
        libswresample   0. 16.100 /  0. 16.100
      [AVFoundation input device @ 0x7f8e2540ef20] AVFoundation video devices:
      [AVFoundation input device @ 0x7f8e2540ef20] [0] FaceTime HD camera (built-in)
      [AVFoundation input device @ 0x7f8e2540ef20] [1] Capture screen 0
      [AVFoundation input device @ 0x7f8e2540ef20] AVFoundation audio devices:
      [AVFoundation input device @ 0x7f8e2540ef20] [0] Blackmagic Audio
      [AVFoundation input device @ 0x7f8e2540ef20] [1] Built-in Microphone
      
    • Capturing entire desktop: Then, you can specify and initialize your located screens in FFdecoder API using its index shown:

      # initialize and formulate the decoder with `0:` index desktop screen for BGR24 output
      decoder = FFdecoder("0:", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
      
    • [OPTIONAL] Capturing mouse: You can also specify additional specifications to capture the mouse pointer and screen mouse clicks as follows:

      # define specifications
      ffparams = {"-ffprefixes":["-capture_cursor", "1", "-capture_mouse_clicks", "0"]}
      
      # initialize and formulate the decoder with "0:" source for BGR24 output
      decoder = FFdecoder("0:", source_demuxer="avfoundation", frame_format="bgr24", verbose=True, **ffparams).formulate()
      

    If these steps doesn't work for you then reach us out on Gitter ➶ Community channel

    # define specifications
    ffparams = {"-ffprefixes":["-capture_cursor", "1", "-capture_mouse_clicks", "0"]}
    
    # initialize and formulate the decoder with "0:" source for BGR24 output
    decoder = FFdecoder("0:", source_demuxer="avfoundation", frame_format="bgr24", verbose=True, **ffparams).formulate()
    

    Related usage recipe can found here ➶

  • Virtual Sources: Valid filtergraph to use as input with lavfi (Libavfilter input virtual device) source that reads data from the open output pads of a libavfilter filtergraph. For example, for generating and decoding Mandelbrot graph of 1280x720 frame size and 30 framerate using lavfi input virtual device, we can do as follows in FFdecoder API:

    # initialize and formulate the decoder with "mandelbrot" source of
    # `1280x720` frame size and `30` framerate for BGR24 output
    decoder = FFdecoder(
        "mandelbrot=size=1280x720:rate=30",
        source_demuxer="lavfi",
        frame_format="bgr24",
    ).formulate()
    

    Related usage recipes can found here ➶

 

source_demuxer

This parameter specifies the demuxer(-f) for the input source (such as dshow, v4l2, gdigrab etc.) to support Live Feed Devices, lavfi (Libavfilter input virtual device) that reads data from the open output pads of a libavfilter filtergraph, and

Any invalid or unsupported value to source_demuxer parameter value will raise Assertion error!

Use ffmpeg -demuxers terminal command to lists all FFmpeg supported demuxers.

Specifying source_demuxer for Index based Camera Device Capturing in FFdecoder API

For enabling Index based Camera Device Capturing in FFdecoder API, the source_demuxer parameter value MUST be either None(also means empty) or "auto":

# initialize and formulate the decoder with "0" index source for BGR24 output
decoder = FFdecoder("0", frame_format="bgr24").formulate()
# initialize and formulate the decoder with "0" index source for BGR24 output
decoder = FFdecoder("0", source_demuxer="auto, frame_format="bgr24").formulate()

Related usage recipes can found here ➶

Data-Type: String

Default Value: Its default value is None.

Usage:

# initialize and formulate the decoder with `dshow` demuxer
decoder = FFdecoder("foo.mp4", source_demuxer="dshow").formulate()

 

frame_format

This parameter select the pixel format for output video frames (such as gray for grayscale output).

Any invalid or unsupported value to frame_format parameter will discarded!

Any improper frame_format parameter value (i.e. either null(special-case), undefined, or invalid type) , then -pix_fmt FFmpeg parameter value in Decoding pipeline uses output_frames_pixfmt metadata property extracted from Output Stream. Thereby, in case if no valid output_frames_resolution metadata property is found, then API finally defaults to Default pixel-format1 (calculated variably).

Use frame_format="null" to manually discard -pix_fmt FFmpeg parameter entirely from Decoding pipeline.

This feature allows users to manually skip -pix_fmt FFmpeg parameter in Decoding pipeline, essentially for using only format ffmpeg filter values instead, or even better let FFmpeg itself choose the best available output frame pixel-format for the given source.

Data-Type: String

Default Value: Its default value is Default pixel-format1 (calculated variably).

Usage:

# initialize and formulate the decoder for grayscale frames
decoder = FFdecoder("foo.mp4", frame_format="gray").formulate()

Use ffmpeg -pix_fmts terminal command to lists all FFmpeg supported pixel formats.

Various Pixel formats related usage recipes can found here ➶

 

custom_ffmpeg

This parameter can be used to manually assigns the system file-path/directory where the custom or downloaded FFmpeg executable is located.

Behavior on Windows

If custom FFmpeg executable binary file-path/directory is not assigned through custom_ffmpeg parameter on Windows machine, then FFdecoder API will automatically attempt to download and extract suitable Static FFmpeg binaries at suitable location on your windows machine. More information can be found here ➶.

How to change FFmpeg Static Binaries download directory?

You can use -ffmpeg_download_path (via. -custom_sourcer_params) exclusive parameter in FFdecoder API to set the custom directory for downloading FFmpeg Static Binaries during the Auto-Installation step on Windows Machines. If this parameter is not altered, then these binaries will auto-save to the default temporary directory (for e.g. C:/User/temp) on your windows machine. It can be used as follows in FFdecoder API:

# # define suitable parameter to download at "C:/User/foo/foo1"
ffparams = {"-custom_sourcer_params": {"-ffmpeg_download_path": "C:/User/foo/foo1"}}

# initialize and formulate the decoder
FFdecoder("foo.mp4", verbose=True, **ffparams).formulate()

If binaries were not found at the manually specified path, DeFFcode APIs will throw RuntimeError!

Data-Type: String

Default Value: Its default value is None.

Usage:

# If ffmpeg executables are located at "/foo/foo1/ffmpeg"
FFdecoder("foo.mp4", custom_ffmpeg="/foo/foo1/ffmpeg").formulate()

 

verbose

This parameter enables verbose logs (if True), essential for debugging.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

# initialize and formulate decoder with verbose logs
FFdecoder("foo.mp4", verbose=True).formulate()

 

ffparams

This dictionary parameter accepts all supported parameters formatted as its attributes:

Data-Type: Dictionary

Default Value: Its default value is {}.

Supported Parameters

A. FFmpeg Parameters

Almost any FFmpeg parameter (supported by installed FFmpeg) can be passed as dictionary attributes in ffparams parameter.

Let's assume we want to 00:00:01.45(or 1045msec) in time and decode one single frame from given source (say foo.mp4) in FFdecoder API, then we can assign required FFmpeg parameters as dictionary attributes as follows:

Kindly read FFmpeg Docs carefully before passing any additional values to ffparams parameter. Wrong invalid values may result in undesired errors or no output at all.

All FFmpeg parameters are case-sensitive. Remember to double check every parameter if any error(s) occurred.

# define the FFmpeg parameter to seek to 00:00:01.45(or 1s and 45msec)
# in time and get one single frame
ffparams = {"-ss": "00:00:01.45", "-frames:v": 1}

# initialize and formulate decoder with suitable source and FFmpeg params
decoder = FFdecoder("foo.mp4", verbose=True, **ffparams).formulate()

B. Exclusive Parameters

In addition to FFmpeg parameters, FFdecoder API also supports few Exclusive Parameters to allow users to flexibly change its internal pipeline, properties, and handle some special FFmpeg parameters (such as repeated map) that cannot be assigned via. python dictionary.

These parameters are discussed below:

  • -vcodec (str) : This attribute works similar to -vcodec FFmpeg parameter for specifying supported decoders that are compiled with FFmpeg in use. If not specified, it's value is derived from source video metadata. Its usage is as follows:

    Use ffmpeg -decoders terminal command to lists all FFmpeg supported decoders.

    Use {"-vcodec":None} in ffparams to discard -vcodec FFmpeg parameter entirely from Decoding pipeline.

    This feature allows users to manually skip -vcodec FFmpeg parameter in Decoding pipeline, for letting FFmpeg itself choose the best available video decoder for the given source.

    # define suitable parameter
    ffparams = {"-vcodec": "h264"} # set decoder to `h264`
    

  • -framerate (float/int) : This attribute works similar to -framerate FFmpeg parameter for generating video-frames at specified framerate. If not specified, it calculated from video metadata. Its usage is as follows:

    Any invalid or unsupported value to -framerate attribute will discarded!

    The output_frames_framerate metadata property is only available when FFmpeg filters via. -vf or -filter_complex are manually defined.

    Any improper -framerate parameter value (i.e. either null(special-case), undefined, or invalid type) , then -framerate/-r FFmpeg parameter value in Decoding pipeline uses output_frames_framerate metadata property extracted from Output Stream. Thereby, in case if no valid output_framerate metadata property is found, then API finally defaults to source_video_framerate metadata property extracted from Input Source Stream.

    In case neither output_framerate nor source_video_framerate valid metadata properties are found, then RuntimeError is raised.

    Use {"-framerate":"null"} in ffparams to discard -framerate/-r FFmpeg parameter entirely from Decoding pipeline.

    This feature allows users to manually skip -framerate/-r FFmpeg parameter in Decoding pipeline, essentially for using only fps filter values, or even better, let FFmpeg itself choose the best available output framerate for the given source.

    # define suitable parameter
    ffparams = {"-framerate": 60.0} # set input video source framerate to 60fps
    

  • -custom_resolution (tuple/list) : This attribute sets the custom resolution/size of the output frames. Its value can either be a tuple ((width,height)) or a list ([width, height]). If not specified, it calculated from video metadata. Its usage is as follows:

    Any invalid or unsupported value to -custom_resolution attribute will discarded!

    The output_frames_resolution metadata property is only available when FFmpeg filters via. -vf or -filter_complex are manually defined.

    Any improper -custom_resolution parameter value (i.e. either null(special-case), undefined, or invalid type) , then -s/-size FFmpeg parameter value in Decoding pipeline uses output_frames_resolution metadata property extracted from Output Stream. Thereby, in case if no valid output_frames_resolution metadata property is found, then API finally defaults to source_video_resolution metadata property extracted from Input Source Stream.

    In case neither output_frames_resolution nor source_video_resolution valid metadata properties are found, then RuntimeError is raised.

    Use {"-custom_resolution":"null"} in ffparams to discard -size/-s FFmpeg parameter entirely from Decoding pipeline.

    This feature allows users to manually skip -size/-s FFmpeg parameter in Decoding pipeline, essentially for using only fps filter values, or even better, let FFmpeg itself choose the best available output frames resolution for the given source.

    # define suitable parameter
    ffparams = {"-output_dimensions": (1280,720)} # to produce a 1280x720 resolution/scale output video
    

  • -ffprefixes (list): This attribute sets the special FFmpeg parameters that generally occurs at the very beginning (such as -re) before input (-i) source. The FFmpeg parameters defined with this attribute can repeated more than once and maintains its original order in the FFmpeg command. Its value can be of datatype list only and its usage is as follows:

    Difference from -clones parameter

    The -clones and -ffprefixes parameters even tho fundamentally work the same, they're meant to serve at different positions in the FFmpeg command. Normally, FFdecoder API pipeline looks something like following with these parameters in place:

    ffmpeg {{-ffprefixes FFmpeg params}} -vcodec h264 -i foo.mp4 -pix_fmt rgb24 -s 1280x720 -framerate 25.0 {{-clones FFmpeg params}} -f rawvideo -
    

    Turn on verbose parameter (verbose = True) to see the FFmpeg command that is being executed in FFdecoder's pipeline. This helps you debug/address any issues and make adjustments accordingly.

    # define suitable parameter
    ffparams = {"-ffprefixes": ['-re']} # executes as `ffmpeg -re <rest of command>`
    

  • -clones (list): This attribute sets the special FFmpeg parameters after that are repeated more than once or occurs in a specific order (that cannot be altered) in the FFmpeg command. Its value can be of datatype list only and its usage is as follows:

    Turn on verbose parameter (verbose = True) to see the FFmpeg command that is being executed in FFdecoder's pipeline. This helps you debug/address any issues and make adjustments accordingly.

    # define suitable parameter
    ffparams = {"-clones": ['-map', '0:v:0', '-map', '1:a?']} 
    
    # NOTE: Will be format as `ffmpeg -vcodec -i foo.mp4 -pix_fmt rgb24 -s 1280x720 -framerate 25.0 -map 0:v:0 -map 1:a -f rawvideo -`
    

  • -custom_sourcer_params (dict) : This attribute assigns all Exclusive Parameter meant for Sourcer API's sourcer_params dictionary parameter directly through FFdecoder API. Its usage is as follows:

    # define suitable parameter meant for `sourcer_params`
    ffparams = {"-custom_sourcer_params": {"-ffmpeg_download_path": "C:/User/foo/foo1"}}
    

  • -default_stream_indexes (list/tuple) : This attribute assign value directly to default_stream_indexes parameter in Sourcer API's probe_stream() method for selecting specific video and audio stream index in case of multiple ones. Value can be of format: (int,int) or [int,int] as follows:

    # define suitable parameter meant for `probe_stream()` method
    ffparams = {"-default_stream_indexes": (0,1)} # ("0th video stream", "1st audio stream")
    

  • -enforce_cv_patch (bool) : This attribute can be enabled(True) for patching YUV pixel-formats (such as YUV420p, yuv444p, NV12, NV21 etc.) frames to be seamless compatibility with OpenCV APIs such as imshow(), write() etc. It can be used as follows:

    As of now, YUV pixel-formats starting with YUV and NV are only supported.

    # define suitable parameter
    ffparams = {"-enforce_cv_patch": True} # enables OpenCV patch for YUV frames
    

    YUV pixel-formats usage recipe can found here ➶

  • -disable_ffmpeg_window (bool): This attribute can be used to prevent the FFmpeg command line window from appearing when using the FFdecoder API on Windows. This is especially useful when creating an .exe file for your Python script with logging disabled(verbose=False), as it stops the FFmpeg window from popping up even in windowed or no-console mode. Its usage is as follows:

    The -disable_ffmpeg_window flag is only available on Windows OS with logging disabled.

    # define suitable parameter
    ffparams = {"-disable_ffmpeg_window": True} # disables FFmpeg creation window
    

  • -passthrough_audio (bool/list) : (Yet to be supported)

 


  1. Default pixel-format is calculated variably in FFdecoder API:

    • If frame_format != "null":
      • If frame_format parameter is valid and supported: Default pixel-format is frame_format parameter value.
      • If frame_format parameter is NOT valid or supported:
        • If output_frame_pixfmt metadata is available: Default pixel-format is output_frame_pixfmt metadata value.
        • If output_frame_pixfmt metadata is NOT available: Default pixel-format is rgb24 if supported otherwise source_video_pixfmt metadata value.
    • If frame_format == "null": Default pixel-format is source_video_pixfmt metadata value