WriteGear API Parameters: Compression Mode¶

output¶

This parameter sets the valid filename/path/URL for the video output.

Data-Type: String

Usage:

Its valid input can be one of the following:

• Path to directory: Valid path of the directory to save the output video file. In this case, WriteGear API will automatically assign a unique filename (with a default extension i.e..mp4) as follows:

  writer = WriteGear(output = '/home/foo/foo1') #Define writer 
  

• Filename (with/without path): Valid filename(with valid extension) of the output video file. In case filename is provided without path, then current working directory will be used.

  writer = WriteGear(output = 'output.mp4') #Define writer 
  

  Make sure to provide valid filename with valid file-extension based on the encoder in use.

• URL: Valid URL of a network stream with a protocol supported by installed FFmpeg (verify with command ffmpeg -protocols) only. This is useful for building a Video-Streaming Server with FFmpeg in WriteGear API. For example, you can stream on a rtmp protocol URL as follows:

  writer = WriteGear(output = 'rtmp://localhost/live/test') #Define writer 
  

compression_mode¶

This parameter selects the WriteGear's Primary Mode of Operation, i.e. if this parameter is enabled (.i.e compression_mode = True) WriteGear will use FFmpeg to encode output video, and if disabled (.i.e compression_mode = False), the OpenCV's VideoWriter API will be used for encoding files/streams.

Data-Type: Boolean

Default Value: Its default value is True.

Usage:

WriteGear(output = 'output.mp4', compression_mode=True)

custom_ffmpeg¶

This parameter assigns the custom path/directory where the custom FFmpeg executables are located in Compression Mode only.

Data-Type: String

Default Value: Its default value is None.

Usage:

# if ffmpeg executables are located at "/foo/foo1/FFmpeg"
WriteGear(output = 'output.mp4', custom_ffmpeg="/foo/foo1/FFmpeg")

output_params¶

This parameter allows us to exploit almost all FFmpeg supported parameters effortlessly and flexibly for encoding in Compression Mode, by formatting desired FFmpeg Parameters as this parameter's attributes. All supported parameters and encoders for compression mode discussed below:

Data-Type: Dictionary

Default Value: Its default value is {}.

Supported Parameters¶

• FFmpeg Parameters: All parameters based on selected encoder in use, are supported, and can be passed as dictionary attributes in output_param. For example, for using libx264 encoder to produce a lossless output video, we can pass required FFmpeg parameters as dictionary attributes, as follows:

  While providing additional av-source with -i FFmpeg parameter in output_params make sure it don't interfere with WriteGear's frame pipeline otherwise it will break things!

  All ffmpeg parameters are case-sensitive. Remember to double check every parameter if any error occurs.

  Kindly check H.264 docs ➶ and other FFmpeg Docs ➶ for more information on these parameters

   output_params = {"-vcodec":"libx264", "-crf": 0, "-preset": "fast", "-tune": "zerolatency"} 
  

• Special Internal Parameters: In addition to FFmpeg parameters, WriteGear API also supports some Special Parameters to tweak its internal properties. These parameters are discussed below:

  • -ffmpeg_download_path (string): sets the custom directory for downloading FFmpeg Static Binaries in Compression Mode, during the Auto-Installation on Windows Machines Only. 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:

    output_params = {"-ffmpeg_download_path": "C:/User/foo/foo1"} # will be saved to "C:/User/foo/foo1"
    

  • -input_framerate (float/int) : sets the constant framerate of the output. It can be used as follows:

    output_params = {"-input_framerate": 60.0} # set the constant framerate to 60fps
    

    Its usage example can be found here ➶

  • -output_dimensions (tuple/list) : sets the custom dimensions(size/resolution) of the output video (otherwise input video-frame size will be used). Its value can either be a tuple => (width,height) or a list => [width, height], Its usage is as follows:

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

  • -clones (list): required to set special FFmpeg parameters that are repeated more than once in the command (For more info., see this issue) or in cases where you want to preserve order of multiple FFmpeg parameters. This attribute only accepts list datatype as value. Its usage is as follows:

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

    WriteGear by automatically applies -format or -f, -pix_fmt and -vcodec or -v:f like critical input parameters for every stream. Therefore if you need multiple values for these parameter just define them with -clones attribute.

    output_params = {
        "-i": "plug:dsnoopUSB",
        "-f": "alsa",
        "-ac": "1",
        "-ar": "48000",
        "-clones": ["-vcodec", "mpeg1video", "-f", "mpegts"],
    }
    

  • -ffpreheaders (list): required to set special FFmpeg parameters that are present at the starting of command(such as -re). This attribute only accepts list datatype as value. Its usage is as follows:

    This attribute is quite powerful and can break FFmpeg pipeline easily if not used correctly. User Discretion is advised!

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

    output_params = {
        "-ffpreheaders": ["-re"], # executes as `ffmpeg -re <rest of command>`
    }
    

  • -disable_ffmpeg_window (bool): sets a special flag to enable detached subprocess creation on Windows OS, and can be useful while creating an .exe file for a python script that uses WriteGear API. On Windows, in certain cases, even after creating the .exe file in windowed mode or no-console mode, the FFmpeg commandline window would pop up while its being used by WriteGear API. Its usage is as follows:

    New in v0.3.2

    This feature was added in v0.3.2.

    -disable_ffmpeg_window is only available on Windows OS with logging disabled(logging=False) in compression mode.

    output_params = {"-disable_ffmpeg_window": True} # disables FFmpeg creation window
    

  • -disable_force_termination (bool): sets a special flag to manually disable the default forced termination of FFmpeg process in WriteGear API when -i FFmpeg parameter is used (For more details, see issue: #149). Its usage is as follows:

    The -disable_force_termination flag is a absolute necessity when video duration is too short(< 60sec), otherwise WriteGear may produce invalid or no output.

    output_params = {"-disable_force_termination": True} # disable the default forced-termination behaviour
    

Supported Encoders¶

All the encoders that are compiled with FFmpeg in use, are supported by WriteGear API. You can easily check the compiled encoders by running following command in your terminal:

ffmpeg -encoders           # use `ffmpeg.exe -encoders` on windows

logging¶

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

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

WriteGear(output = 'output.mp4', logging=True)