Skip to content

Custom FFmpeg Commands in WriteGear API⚓

WriteGear API now provides the execute_ffmpeg_cmd Method in Compression Mode that enables the user to pass any custom FFmpeg CLI (Command Line Interface) commands as input to its internal FFmpeg Pipeline by formating it as a list.

This opens endless possibilities of exploiting every FFmpeg params within WriteGear without relying on a third-party API to do the same and while doing that it robustly handles all errors/warnings quietly.


Important Information



  • Provides the ability to pass any custom command to WriteGear FFmpeg Pipeline.

  • Compatible with any FFmpeg terminal command.

  • Standalone On-the-fly functioning.

  • Can work without interfering with WriteGear API's Writer pipeline.

  • Minimum hassle and extremely easy to enable and use.




This method allows the users to pass the custom FFmpeg terminal commands as a formatted list directly to WriteGear API's FFmpeg pipeline for processing/execution. Its usage is as follows:

# format FFmpeg terminal command `ffmpeg -y -i source_video -acodec copy input_audio.aac` as a list
ffmpeg_command = ["-y", "-i", source_video, "-acodec", "copy", "input_audio.aac"]

# execute this list using this function


Usage Examples⚓

Following usage examples is just an idea of what can be done with this powerful function. So just Tinker with various FFmpeg parameters/commands yourself and see it working. Also, if you're unable to run any terminal FFmpeg command, then report an issue.

Using WriteGear to separate Audio from Video⚓

In this example, we will extract and save audio from a URL stream:

# import required libraries
from vidgear.gears import WriteGear

# define a valid url
url_to_stream = (

# Define writer with default parameters
writer = WriteGear(output="Output.mp4", logging=True)

# format command to convert stream audio as 'output_audio.aac' as list
ffmpeg_command_to_save_audio = [
]  # `-y` parameter is to overwrite outputfile if exists

# execute FFmpeg command

# safely close writer

After running this script, You will get the final 'output_audio.aac' audio file.


Using WriteGear to merge Audio with Video⚓

In this example, we will merge audio with video:

You can also directly add external audio input to video-frames in WriteGear. For more information, See this FAQ example ➶

Example Assumptions

  • You already have a separate video(i.e 'input-video.mp4') and audio(i.e 'input-audio.aac') files.

  • Both these Audio and Video files are compatible.

# import required libraries
from vidgear.gears import VideoGear
from vidgear.gears import WriteGear
import cv2
import time

# Open input video stream
stream = VideoGear(source="input-video.mp4").start()

# set input audio stream path
input_audio = "input-audio.aac"

# define your parameters
output_params = {
    "-input_framerate": stream.framerate
}  # output framerate must match source framerate

# Define writer with defined parameters and suitable output filename for e.g. `Output.mp4`
writer = WriteGear(output="Output.mp4", **output_params)

# loop over
while True:

    # read frames from stream
    frame =

    # check for frame if Nonetype
    if frame is None:

    # {do something with the frame here}

    # write frame to writer

    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):

# close output window

# safely close video stream

# safely close writer

# sleep 1 sec as the above video might still be rendering

# format FFmpeg command to generate `Output_with_audio.mp4` by merging input_audio in above rendered `Output.mp4`
ffmpeg_command = [
]  # `-y` parameter is to overwrite outputfile if exists

# execute FFmpeg command

After running this script, You will get the final 'Output_with_audio.mp4' file with both video and audio merged.


Last update: August 24, 2022