WriteGear API

WriteGear is undoubtedly the most powerful Video Processing Gear of them all. It solely handles various powerful FFmpeg tools that allow us to do almost anything you can imagine with multimedia files. With WriteGear API, you can process real-time video frames into a lossless format and specification suitable for our playback in just a few lines of codes. These specifications include setting bitrate, codec, framerate, resolution, subtitles, compression, etc. Furthermore, we can multiplex extracted audio at the output with compression and all that in real-time (see this example). In addition to this, WriteGear also provides flexible access to OpenCV's VideoWriter API which provide some basic tools for video frames encoding but without compression.

Modes:

WriteGear primarily operates in the following two modes:

• Compression Mode: In this mode, WriteGear utilizes FFmpeg's 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 OpenCV's VideoWriter 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.

Warning:

• 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 fallbacks to Non-Compression Mode.

• Follow this WIKI Page for FFmpeg installation.

Importing:

You can import WriteGear as follows:

from vidgear.gears import WriteGear

Important WriteGear Functions:

1. write(self, frame, rgb_mode = False) : pipelines ndarray frames to valid Video File.

   Parameters:

   • rgb_mode: set this flag to enable RGB Mode - specifies that incoming frames are of RGB format(instead of default BGR) in Compression Mode. Its default value is False. See its usage example here.

2. close(self): It safely Terminates the Write process. Therefore it is compulsory to call this function at the end of the main function.

   ---

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

   ---

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

Parameters and Attributes:

1. output_filename(string): sets the valid output Video filename/path. Its Valid Inputs are:

• path: 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).

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

  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.

2. compression_mode(boolean): if enabled(compression=True) WriteGear API will utilize the FFmpeg executables to encode output video and if disabled(compression=False) the OpenCV's VideoWriter API will be used. Its default value is True.

3. custom_ffmpeg(string): In Compression Mode, if specified, it assigns the custom path/directory where the custom FFmpeg executables are located.

Note: 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.

4. **output_params(dict): This parameter provides the flexibility to manipulate almost all parameters/properties which are supported by FFmpeg(in Compression Mode) or OpenCV's VideoWriter(in Non-Compression Mode) whichever being accessed. In addition to these parameters, other special parameters to manipulate WriteGear API'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

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