WriteGear

WriteGear API

WriteGear handles various powerful Writer Tools that provide us the freedom to do almost anything imagine with multimedia files.

WriteGear API provide a complete, flexible & robust wrapper around FFmpeg, a leading multimedia framework. With WriteGear, we can process real-time video frames into a lossless compressed format with any suitable specification in just few easy lines of codes. These specifications include setting any video/audio property such as bitrate, codec, framerate, resolution, subtitles, etc. easily as well complex tasks such as multiplexing video with audio in real-time(see this example wiki). Best of all, WriteGear grants the freedom to play with any FFmpeg parameter with its exclusive custom Command function(see this example wiki), while handling all errors robustly.

In addition to this, WriteGear also provides flexible access to OpenCV's VideoWriter API which provides some basic tools for video frames encoding but without compression.

 

Modes of Operation:

WriteGear primarily operates in the following two modes:

• Compression Mode: In this mode, WriteGear utilizes FFmpeg inbuilt encoders to encode lossless multimedia files. It provides us the ability to exploit almost any available parameters available within FFmpeg, with so much ease and flexibility and while doing that it robustly handles all errors/warnings quietly. You can find more about this mode here ➶.

• Non-Compression Mode: In this mode, WriteGear utilizes basic OpenCV's inbuilt VideoWriter API. Similar to compression mode, WriteGear also supports all parameters manipulation available within this API. But this mode lacks the ability to manipulate encoding parameters and other important features like video compression, audio encoding, etc. You can learn about this mode here ➶.

 

 

---

Important: ⚠️

• DO NOT feed frames to WriteGear with different dimensions or channels!, otherwise WriteGear will exit with ValueError.

• In case WriteGear API fails to detect valid FFmpeg executables on your system(even if Compression Mode is enabled), it will automatically fallback to Non-Compression Mode. 💡 Follow this WIKI Page ➶ for FFmpeg installation.

• Heavy resolution multimedia files take time to render which can last up to ~.1-to-2 secs, Kindly wait till the function terminates itself and DO NOT try to kill the process instead.

---

 

 

Table of Contents:

• Importing
• Usage
  • WriteGear API(Compression Mode: FFmpeg):
  • WriteGear API(Non-Compression Mode: OpenCV
  • Bonus: Custom FFmpeg Commands in WriteGear API
• Parameters and Attributes

 

 

Importing:

You can import WriteGear as follows:

from vidgear.gears import WriteGear

 

 

Usage: 🔨

1. WriteGear API(Compression Mode: FFmpeg):

See here for details and complete example ➶

2. WriteGear API(Non-Compression Mode: OpenCV):

See here for details and complete example ➶

Bonus: Custom FFmpeg Commands in WriteGear API

See here for details and complete example ➶

 

 

Parameters and Attributes: 🔧

• output_filename (string) : sets the valid output Video filename/path for the output video. Its valid inputs are:

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

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

  • Filename (with/without path): Valid filename(with valid extension) of the output video file.

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

    Note: 💡 Make sure to provide valid filename with valid file-extension based on the encoder(in case of FFmpeg) & FOURCC(in case of OpenCV) whichever being used based on selected compression mode.

• compression_mode (boolean) : selects the WriteGear's Mode of Operation. If this parameter is enabled (.i.e compression_mode = True) WriteGear utilized the FFmpeg Pipeline to encode output video, and if it's disabled (.i.e compression_mode = False), the OpenCV's VideoWriter API will be used for encoding. Its default value is True.

• custom_ffmpeg (string) : In Compression Mode, this parameter assigns the custom path/directory where the custom FFmpeg executables are located.

  ⚠️ For Compression Mode, it is compulsory to provide custom binaries on a Windows OS Machine, otherwise WriteGear API will automatically download and extract suitable Static FFmpeg binaries to Temporary directory.

• **output_params (dict) : provides the complete flexibility to pass all the supported parameters to FFmpeg (in Compression Mode) or OpenCV's VideoWriter (in Non-Compression Mode), whichever being accessed by the user. In addition to these parameters, other special parameters to manipulate WriteGear's internal properties, are also supported.

  All supported parameters details and their usage is depicted in the following links:

  • For Compression Mode ➶
  • For Non-Compression Mode ➶

• logging (boolean) : set this flag to enable/disable logging, essential for debugging. Its default value is False.