vedit 0.0.3

Library for editing video by wrapping ffmpeg.

vedit Overview

Project homepage at: https://github.com/digitalmacgyver/vedit

vedit is a Python library that simplifies editing and combining video files using ffmpeg.

Examples of the sorts of things vedit makes easy include:

• Extracting a clip from a longer video

• Combining videos or clips together by concatenating them end to end

• Composing videos together, for example side by side or overlayed on top of a background image

• Changing the resolution of a video and cropping or padding a video to change its aspect ratio

• Overlaying images onto a video

• Adding an audio track (like a song) to a video

There are numerous stumbling blocks to these tasks - vedit makes the above things easy by automatically handling videos with:

• Different resolutions

• Different sample aspect ratios

• Different pixel formats

• Different frame rates

• Different audio streams and channels

---

Installation

Assuming you have pip installed:

pip install vedit

However, there is nothing in the package that is special. The only dependencies are the future module and a Python 2.7 or later (including Python 3) interpreter. You can just download from the project GitHub repository and put the vedit directory in your Python path of an interpreter that also has future installed.

---

Before You Begin

vedit depends on the ffmpeg and ffprobe programs from the FFmpeg project, and on the libx264 video codec and the libfdk_aac audio codec, for example by configuring ffmpeg for compilation with:

./configure –enable-gpl –enable-libx264 –enable-nonfree –enable-libfdk-aac –enable-libfreetype –enable-libfontconfig

(--enable-libfreetype --enable-libfontconfig only needed if the audio_desc option is used).

---

Table of Contents

• Examples

  • Example 1: Clip 2 seconds out of the middle of a video

  • Example 2: Resize a video with PAD, CROP, or PAN

  • Example 3: Put two videos next to each other

  • Example 4: Replace the audio track of a video

  • Example 5: Overlay videos on top of other videos

  • Example 6: Cascade overlayed videos and images on top of a base video or image

  • Example 7: Add an overlay image, such as a watermark

• Module Concepts

  • Windows

  • Display Configuration

  • Videos and Clips

  • Watermarks

  • Audio

• Logging Output

• Getting Help

• Contributing

• Odds and Ends

---

Examples

To get an idea of the sorts of things you can do with a few lines of code, consider these examples, which can be generated from the examples.py script in the root directory of the vedit Python module.

All the examples below assume that FFmpeg is installed as described in Before You Begin.

All the examples below begin with the following boilerplate, and assume the ./example_output directory exists:

#!/usr/bin/env python

import vedit
import logging
logging.basicConfig()
log = logging.getLogger()
log.setLevel( logging.DEBUG )

Back to Table of Contents

---

Example 1: Clip 2 seconds out of the middle of a video

Link to input for example: https://youtu.be/9ul6rWAewd4

Link to example output: https://youtu.be/FEr6WMUx_4A

# Clipping 2 seconds out of source video from 1.5 seconds to 3.5 seconds.
source = vedit.Video( "./examples/testpattern.mp4" )
output_file = "./example_output/example01.mp4"
clip = vedit.Clip( video=source, start=1.5, end=3.5 )
window = vedit.Window( width=source.get_width(),
                       height=source.get_height(),
                       output_file=output_file )
window.clips = [ clip ]
window.render()
log.info( "Output file at %s" % ( output_file ) )

Back to Table of Contents

---

Example 2: Resize a video with PAD, CROP, or PAN

Link to source input: https://youtu.be/Qmbgrr6WJEY

Links to example outputs:

• Padded clip: https://youtu.be/2bTdwEzraxA

• Panned clip: https://youtu.be/lCpbnudnFyc

• Cropped clip: https://youtu.be/96v-KVq9B-g

# Turning a 1280x720 16:9 input video into a 640x480 4:3 video.
source = vedit.Video( "./examples/d005.mp4" )
clip = vedit.Clip( video=source )

#Since the input and output aspect ratios don't match, pad the input onto a blue background.
pad_output = "./example_output/example02-pad.mp4"
pad_display = vedit.Display( display_style=vedit.PAD, pad_bgcolor="Blue" )
window = vedit.Window( width=640, height=480,
                       display=pad_display,
                       output_file=pad_output )
window.clips = [ clip ]
window.render()
log.info( "Pad output file at: %s" % ( pad_output ) )

# Render a cropped version as well. Note the watermark is getting cropped out on the right.
crop_output = "./example_output/example02-crop.mp4"
crop_display = vedit.Display( display_style=vedit.CROP )
window = vedit.Window( width=640, height=480,
                       display=crop_display,
                       output_file=crop_output )
window.clips = [ clip ]
window.render()
log.info( "Crop output file at: %s" % ( crop_output ) )

# Render a version where we pan over the input image as it plays as well. Note the watermark moves from left to right.
pan_output = "./example_output/example02-pan.mp4"
pan_display = vedit.Display( display_style=vedit.PAN )
window = vedit.Window( width=640, height=480,
                       display=pan_display,
                       output_file=pan_output )
window.clips = [ clip ]
window.render()
log.info( "Pan output file at: %s" % ( pan_output ) )

Back to Table of Contents

---

Example 3: Put two videos next to each other

Example output: https://youtu.be/fsYw2jLyuQ4

# Lets set up some source videos, and some clips for use below.
video_1 = vedit.Video( "./examples/i030.mp4" )

# Put two clips from video 1 side by side, with audio from the
# left clip only, ending after 8 seconds (we could also use clips
# from different videos).
clip_1_0_5 = vedit.Clip( video=video_1, start=0, end=5 )
clip_1_10_20 = vedit.Clip( video=video_1, start=10, end=20,
                           display=vedit.Display( include_audio=False ) )

# Set up two windows, one for each clip, and one to hold the other two, and set the duration.
#
# Since clip 1 is 5 seconds long and we are making an 8 second
# video, there will be time when clip 1 is not playing - set the
# background color to green during this time.
output_file = "./example_output/example03.mp4"
base_window = vedit.Window( width=1280*2, height=720, duration=8, bgcolor='Green',
                            output_file=output_file )
# Set the x, y coordinates of this window inside its parent, as
# measure from the top right.
#
# Here we are putting the videos flush side by side, but they
# could be on top of each other, overlapping, centered in a much
# larger base_window, etc., etc..
clip_1_window = vedit.Window( width=1280, height=720, x=0, y=0, clips=[ clip_1_0_5 ] )
clip_2_window = vedit.Window( width=1280, height=720, x=1280, y=0, clips=[ clip_1_10_20 ] )
base_window.windows = [ clip_1_window, clip_2_window ]
base_window.render()
log.info( "Side by side output is at: %s" % ( output_file ) )

Back to Table of Contents

---

Example 4: Replace the audio track of a video

Example outputs:

• Not attributed: https://youtu.be/4Z2Uigssc88

• Attributed song: https://youtu.be/ojgAs5A5bSg

source = vedit.Video( "./examples/i010.mp4" )
output_file = "./example_output/example04.mp4"
# Get a clip, but override any Window settings for its audio.
clip = vedit.Clip( video=source, display=vedit.Display( include_audio=False ) )
# Give this window it's own audio track, and set the duration to
# 10 seconds (otherwise it will go on as long as the audio track).
#
# Note - if the window audio track is longer than the video
# content, it fades out starting 5 seconds from the end.
window = vedit.Window( audio_file="./examples/a2.mp4", duration=10,
                       output_file=output_file )
window.clips = [ clip ]
window.render()
log.info( "Replaced audio in output: %s" % ( output_file ) )

# Let's make a version where we attribute the audio with some text.
song_attribution = '''This video features the song:
Chuckie Vs Hardwell Vs Sandro Silva Vs Cedric & Quintino
EPIC CLARITY JUMP- (NC MASHUP) LIVE
By: NICOLE CHEN
Available under under a Creative Commons License:
http://creativecommons.org/licenses/by/3.0/ license'''

output_file = "./example_output/example04-attributed.mp4"
window = vedit.Window( audio_file="./examples/a2.mp4",
                       audio_desc=song_attribution,
                       duration=10,
                       output_file=output_file )
window.clips = [ clip ]
window.render()
log.info( "Replaced audio in output: %s" % ( output_file ) )

Back to Table of Contents

---

Example 5: Overlay videos on top of other videos

Example outputs:

• All audio tracks (bleagh): https://youtu.be/lqLLlXPYg3c

• Just one audio track: https://youtu.be/hL0t3RXHKAM

# Let's overlay two smaller windows on top of a base video.
base_video = vedit.Video( "./examples/i030.mp4" )
base_clip = vedit.Clip( video=base_video )
output_file = "./example_output/example05.mp4"
# Use the default width, height, and display parameters:
# 1280x1024, which happens to be the size of this input.
base_window = vedit.Window( clips = [ base_clip ],
                            output_file=output_file )

# We'll create two smaller windows, each 1/3 the size of the
# base_window, and position them towards the top left, and bottom
# right of the base window.
overlay_window1 = vedit.Window( width=base_window.width/3, height=base_window.height/3,
                                x=base_window.width/12, y=base_window.height/12 )
overlay_window2 = vedit.Window( width=base_window.width/3, height=base_window.height/3,
                                x=7*base_window.width/12, y=7*base_window.height/12 )

# Now let's put some clips in each of the overlay windows.
window_1_clips = [
    vedit.Clip( video=vedit.Video( "./examples/d007.mp4" ) ),
    vedit.Clip( video=vedit.Video( "./examples/d006.mp4" ) ),
]
window_2_clips = [
    vedit.Clip( video=vedit.Video( "./examples/p006.mp4" ) ),
    vedit.Clip( video=vedit.Video( "./examples/p007.mp4" ) ),
    vedit.Clip( video=vedit.Video( "./examples/p008.mp4" ) ),
]

# Now let's embed the clips in the windows, and the overlay
# windows in our base_window and render.
overlay_window1.clips = window_1_clips
overlay_window2.clips = window_2_clips
base_window.windows = [ overlay_window1, overlay_window2 ]
base_window.render()
log.info( "Made multi-video composition at: %s" % ( output_file ) )

# Well - the last video looks OK, but it sounds terrible - the
# audio from all the videos are being mixed together.
#
# Let's try again but exclude audio from everything but the base
# video.
output_file = "./example_output/example05-single-audio.mp4"
no_audio_display_config = vedit.Display( include_audio=False )
no_audio_overlay_window1 = vedit.Window( width=base_window.width/3, height=base_window.height/3,
                                x=base_window.width/12, y=base_window.height/12,
                                display=no_audio_display_config )
no_audio_overlay_window2 = vedit.Window( width=base_window.width/3, height=base_window.height/3,
                                x=7*base_window.width/12, y=7*base_window.height/12,
                                display=no_audio_display_config )

# Now let's embed the clips in the windows, and the overlay
# windows in our base_window and render.
no_audio_overlay_window1.clips = window_1_clips
no_audio_overlay_window2.clips = window_2_clips
base_window.output_file = output_file
base_window.windows = [ no_audio_overlay_window1, no_audio_overlay_window2 ]
base_window.render()
log.info( "Made multi-video composition with single audio track at: %s" % ( output_file ) )

Back to Table of Contents

---

Example 6: Cascade overlayed videos and images on top of a base video or image

Example output: https://youtu.be/K2SuPqWrG3M

import glob
import random

# The OVERLAY display_style when applied to a clip in the window
# makes it shrink a random amount and be played while it scrolls
# across the base window.
#
# Let's use that to combine several things together and make a
# huge mess!
output_file = "./example_output/example06.mp4"
base_video = vedit.Video( "./examples/i030.mp4" )

# Let's use a different audio track for this.
base_clip = vedit.Clip( video=base_video, display=vedit.Display( include_audio=False ) )
base_window = vedit.Window( clips = [ base_clip ],
                            output_file=output_file,
                            duration=30,
                            audio_file="./examples/a2.mp4" )

# Turn our cat images into clips of random length between 3 and 6
# seconds and have them cascade across the screen from left to
# right.
cat_display = vedit.Display( display_style=vedit.OVERLAY,
                             overlay_direction=vedit.RIGHT,
                             include_audio=False,
                             overlay_concurrency=4,
                             overlay_min_gap=0.8 )
cat_clips = []
for cat_pic in glob.glob( "./examples/cat*jpg" ):
    cat_video_file = vedit.gen_background_video( bgimage_file=cat_pic,
                                                 duration=random.randint( 3, 6 ) )
    cat_video = vedit.Video( cat_video_file )
    cat_clips.append( vedit.Clip( video=cat_video, display=cat_display ) )

# Turn our dog images into clips of random length between 2 and 5
# seconds and have them cascade across the screen from top to
# bottom.
dog_display = vedit.Display( display_style=vedit.OVERLAY,
                             overlay_direction=vedit.DOWN,
                             include_audio=False,
                             overlay_concurrency=4,
                             overlay_min_gap=0.8 )
dog_clips = []
for dog_pic in glob.glob( "./examples/dog*jpg" ):
    dog_video_file = vedit.gen_background_video( bgimage_file=dog_pic,
                                                 duration=random.randint( 3, 6 ) )

    dog_video = vedit.Video( dog_video_file )
    dog_clips.append( vedit.Clip( video=dog_video, display=dog_display ) )

# Throw in the clips from the p series of videos of their full
# duration cascading from bottom to top.
pvideo_display = vedit.Display( display_style=vedit.OVERLAY,
                                overlay_direction=vedit.UP,
                                include_audio=False,
                                overlay_concurrency=4,
                                overlay_min_gap=0.8 )
pvideo_clips = []
for p_file in glob.glob( "./examples/p0*mp4" ):
    pvideo_video = vedit.Video( p_file )
    pvideo_clips.append( vedit.Clip( video=pvideo_video, display=pvideo_display ) )

# Shuffle all the clips together and add them onto the existing
# clips for the base_window.
overlay_clips = cat_clips + dog_clips + pvideo_clips
random.shuffle( overlay_clips )
base_window.clips += overlay_clips
base_window.render()
log.info( "Goofy mashup of cats, dogs, and drone videos over Icelandic countryside at: %s" % ( output_file ) )

Note: Since the composition of this video involves several random elements, the output you get will not be the same as the example output below.

Back to Table of Contents

---

Example 7: Add an overlay image, such as a watermark

Example output: https://youtu.be/1PrADMtqdRU

import glob

# Let's make our background an image with a song.
output_file = "./example_output/example07.mp4"
dog_background = vedit.Window( bgimage_file="./examples/dog03.jpg",
                               width=960, #The dimensions of this image
                               height=640,
                               duration=45,
                               audio_file="./examples/a3.mp4",
                               output_file=output_file )

# Let's put two windows onto this image, one 16:9, and one 9:16.
horizontal_window = vedit.Window( width = 214,
                                 height = 120,
                                 x = (960/2-214)/2, # Center it horizontally on the left half.
                                 y = 80,
                                 display=vedit.Display( include_audio=False, display_style=vedit.CROP ) )
vertical_window = vedit.Window( width=120,
                                height=214,
                                x = 740,
                                y = (640-214)/2, # Center it vertically.
                                display=vedit.Display( include_audio=False, display_style=vedit.PAN ) )

# Let's let the system distribute a bunch of our 3 second clips
# among the horizontal and vertical windows automatically.
video_clips = []
for video_file in glob.glob( "./examples/*00[5-9].mp4" ):
    video_clips.append( vedit.Clip( end=3, video=vedit.Video( video_file ) ) )

# With these options this will randomize the input clips among
# the two windows, and keep recycling them until the result is 45
# seconds long.
vedit.distribute_clips( clips=video_clips,
                        windows=[ horizontal_window, vertical_window ],
                        min_duration=45,
                        randomize_clips=True )

# Add the overlay windows to the background.
dog_background.windows = [ horizontal_window, vertical_window ]

# Let's set up a watermark image to show over the front and end of
# out video. The transparent01.png watermark image is 160x160
# pixels.
#
# Let's put it in the top left for the first 10 seconds.
front_watermark = vedit.Watermark( filename="./examples/transparent01.png",
                                   x=0,
                                   y=0,
                                   fade_out_start=7,
                                   fade_out_duration=3 )
# Let's put it in the bottom right for the last 15 seconds.
back_watermark = vedit.Watermark( filename="./examples/transparent01.png",
                                  x=dog_background.width-160,
                                  y=dog_background.height-160,
                                  fade_in_start=-15, # Negative values are times from the end of the video.
                                  fade_in_duration=5 )

# Add watermarks to the background.
dog_background.watermarks = [ front_watermark, back_watermark ]

dog_background.render()
log.info( "Random clips over static image with watermarks at: %s" % ( output_file ) )

Back to Table of Contents

---

Module Concepts

There are four main classes in the vedit module:

Video

Video represents a given video or image file on the filesystem.

Clip

Clip represents a portion of a video with a given start and end time. When associated with a Window and a Display a Clip can be rendered into an output video.

Display

Display configures the properties that a given Clip has when it is rendered into a given Window.

Window

Window objects are the building blocks that are used to compose Clip objects together. The width and height properties of a Window determine the size of a Clip when it is rendered in that Window. In basic usage one or more Clip objects are associated with a Window which is then rendered. In more advanced usage a Window can include any number of child Window and Clip objects to create complex outputs where several different clips play at the same time.

Back to Table of Contents

---

Display Configuration

The Display object contains configuration that dictates how a given Clip appears when the Window it is in is rendered.

Each Clip can its own Display, and so can each Window. When considering what Display settings to use for a given Clip the following selections are made:

1. If the Clip has a Display object, it is used.

2. Otherwise, if the Window has a Display object, it is used.

3. Otherwise, the Default display elements described below are used.

Constructor arguments:

Argument	Required	Default	Description
display_style	No	vedit.PAD	One of vedit.CROP, PAD, PAN, or OVERLAY
overlay_concurrency	No	3	If display_style is OVERLAY, how many Clips may cascade at the same time
overlay_direction	No	vedit.DOWN	One of UP, DOWN, LEFT, or RIGHT. If display_style is OVERLAY, what direction the Clips cascade
overlay_min_gap	No	4	If display_style is OVERLAY, the shortest period of time between clips cascade
pad_bgcolor	No	‘Black’	If display_style is PAD, what color should be on the background of the Clip in [0x|#]RRGGBB format
pan_direction	No	vedit.ALTERNATE	One of vedit.UP, DOWN, LEFT, or RIGHT. If display_style is PAN, what direction the Window should pan over the Clip
include_audio	No	True	Should audio from this Clip be included in the output

Public methods: None

The OVERLAY display_style

This display_style makes the Clip be rendered as a small (randomly sized between 1/2 and 1/3 of the width of its Window) tile that cascades across the Window while it plays.

The idea here is to make a collage of images or clips. For a silly example see https://youtu.be/K2SuPqWrG3M - the output for Example 6: Cascade overlayed videos and images on top of a base video or image.

When a several Clips are rendered in a given Window with the OVERLAY display_style the behavior of the cascading is further controlled by:

• overlay_concurrency - The number of clips that can be in the Window at once.

• overlay_direction - One of vedit.UP, DOWN, LEFT, or RIGHT. The Clip will move across the Window in this direction as it plays.

• overlay_min_gap - The shortest time in seconds between when two Clip objects will move across the Window.

CROP, PAD, and PAN

display_style: When the a Clip is rendered in a Window, if the Clip and the Window do not have the same aspect ratio, something must be done to make the Clip fit in the Window.

If the display_style is:

CROP: The Clip will be scaled to the smallest size such that both its height and width are at least as large as the Window it is in. The Clip is then centered in the Window and any portions of the Clip that fall outside the Window are cropped away and discarded.

As in Example 2: Resize a video with PAD, CROP, or PAN when: https://youtu.be/Qmbgrr6WJEY is cropped the result is: https://youtu.be/96v-KVq9B-g

PAD: The Clip will be scaled to the largest size such that both its height and width are no larger than the Window it is in. Then any space in the Window not covered by the clip is colored the pad_bgcolor color (defaults to black).

As in Example 2: Resize a video with PAD, CROP, or PAN when: https://youtu.be/Qmbgrr6WJEY is padded onto a blue background the result is: https://youtu.be/2bTdwEzraxA

PAN: The Clip will be scaled to the smallest size such that both its height and width are at least as large as the Window it is in. The Clip then is scrolled through the Window in the direction specified by pan_direction. pan_direction is one of UP/RIGHT, DOWN/LEFT, or ALTERNATE.

As in Example 2: Resize a video with PAD, CROP, or PAN when: https://youtu.be/Qmbgrr6WJEY is panned with pan_direction of vedit.RIGHT the result is: https://youtu.be/lCpbnudnFyc

Display Examples:

# A display that will crop the input and remove the audio:
crop_silent = Display( display_style=vedit.CROP, include_audio=False )

# A display that will pad the input with a green background and include the audio from it:
pad = Display( display_style=vedit.PAD, pad_bgcolor='Green', include_audio=True )
# Or - more concisely relying on the defaults values for display_style and include_audio:
pad = Display( pad_bgcolor='Green' )

# A display that will have up to 5 clips cascading over the Window
at a time, starting no more than once a second, and moving from top
to bottom:
cascade_5 = Display( display_style=vedit.OVERLAY, overlay_concurrency=5, overlay_min_gap=1 )

# A display that will pan over the input from bottom to top or right to left (depending on whether the Clip is taller or wider than the Window it is in):
pan_up = Display( display_style=vedit.PAN, pan_direction=vedit.UP )

Back to Table of Contents

---

Windows

The Window object is used to compose Clip objects together into a rendered video output.

A Window has a background of a solid color or static image, and optionally may have:

• A list of Clip``s that it will show in order (perhaps cascading through the ``Window as they play if the Display.display_style for that Clip is OVERLAY).

• A list of other Window objects that are rendered on top of it, for example several windows can be composed like:

  +------------------------------------------+
  |                  Window 1                |
  |  +-------------------------+             |
  |  | Window 2                |  +---------+|
  |  |                         |  | Window 3||
  |  |               +------------|         ||
  |  +---------------| Window 4   |         ||
  |                  |            |         ||
  |                  | +---------+|         ||
  |                  | | Window 5|+---------+|
  |                  | +---------+  |        |
  |                  +--------------+        |
  +------------------------------------------+

In the example above there are five windows:

• Window 1 has child Window objects: Window 2, Window 3, and Window 4

• Window 4 has child Window: Window 5

Each of these five Window objects would have it’s own content of Clips, background images, and/or Watermark objects.

Example 5: Overlay videos on top of other videos has an example of two Windows overlayed onto another at: https://youtu.be/hL0t3RXHKAM

The duration of a Window's rendered video output will be:

• The duration attribute, if set during construction

• Otherwise, if an audio_file is specified during construction, the length of that audio stream

• Otherwise, the longest computed time it will take the clips in this or any of its child windows to play

Constructor arguments: (presented in rough order of importance)

Argument	Required	Default	Description
windows	No	None	A list of child Windows. May be set after construction by assigning to the .windows attribute
clips	No	None	A list of Clips to render in this Window. May be set after construction by assigning to the .clips attribute
bgcolor	No	‘Black’	The background color for this Window that will be shown in regions of this Window that do not otherwise have content (from a Clip, a child Window, or Watermark). May be set with a string in [0x|#]RRGGBB format.
bgimage_file	No	None	If provided, a background image for this Window that will be shown in regions or times where there is not otherwise content. No scaling is done to this image, so it must be sized at the desired width and height.
duration	No	None	If specified, the duration of this Window when rendered. Otherwise will default first to the duration of the optional audio_file for this Window, and then to the maximum duration of the Clips in this Window or any of it’s child Windows.
width	No	1280	Width in pixels of this Window
height	No	720	Height in pixels of this Window
output_file	No	./output.mp4	Where to place the output video for when this Window is rendered. Not needed for Windows that are children of other Windows.
display	No	None	An optional Display object that specifies the Display configuration for Clips in this Window. NOTE: If a Clip has its own Display object, it will override the Display configuration of the Window it is placed in. The default values are: display_style=PAD, pad_bgcolor='Black', include_audio=True.
audio_file	No	None	If specified the path to an audio file whose first audio stream will be added to the output of this Window.
x	No	0	If this Window is a child of another Window, the x coordinate of the top left corner of this Window, as measured from the top left of the parent Window
y	No	0	If this Window is the child of another Window, the y coordinate of the top left corner of this Window, as measured from the top left of the parent Window
watermarks	No	None	A list of Watermark objects that can be used to place static images over everything else in this Window at certain times.
audio_desc	No	None	If a string is specified it’s text will be placed at the bottom left of the window 5 seconds prior to the end of the video.
z_index	No	None	If not specified Windows will be placed on top of one another in the order they are created, older Windows having lower z_indexes. If specified should be a numeric value, and Windows will be placed underneath other Windows of higher z_index.
pix_fmt	No	None	If specified the pixel format of the output video. Defaults to: yuv420p
sample_aspect_ratio	No	None	The SAR of a video is the aspect ratio of individual pixels. If specified must be in W:H format. The SAR tine Window should have when rendered. Defaults to the SAR of the source Video that has provided Clips to this Window. If more than one SAR is present in the inputs a WARNING is issued and 1:1 is used.
overlay_batch_concurrency	No	16	ffmpeg seems to have problems when many overlays are used, resulting in crashes or errors in the resultant video. This parameter configures the maximum number of overlays that will be composed at one time during rendering. If you are having mysterious ffmpeg errors during rendering, try lowering this.

Public methods:

• .render() - Compose this Window's: bgcolor, bgimage_file, audio_file, clips, child windows, watermarks, and audio_desc into a video of width with and height height and place the output at output_file.

• compute_duration( clips, include_overlay_timing=False ) - Return a float of how long the Clips in the clips list input would take to render in this Window. If the optional include_overlay_timing argument is true then instead a tuple will be returned, the first element of which is the duration that would result from the clips, and the second is a list of the start and end times of any clips whose Display.display_type is OVERLAY.

Window Examples:

# Let's assume we have some existing media objects / files to work with:
clip1 = vedit.Clip( ... )
clip2 = vedit.Clip( ... )
clip3 = vedit.Clip( ... )
watermark = vedit.Watermark( ... )
background_image = "./media/background_01.jpg"
song = "./media/song.mp3"

# A 640x480 window that uses the default Display properties (overridden on a Clip by Clip basis if they have their own Display settings):
tv = vedit.Window( clips=[ clip1, clip2 ], width=640, height=480 )

# Let's embed the tv window in a 1080x720 window near the top left
# (50 pixels from the left, 60 from the top), with a background_image.
#
# We'll make the hd window 30 seconds long.
#
# We'll add our song to the hd window.
#
# Note: 1080x720 is the default resolution for a Window, so we don't have to set it.

hd = vedit.Window( windows=[ tv ], bgimage_file=background_image, x=50, y=60,
                   duration=30, audio_file=song )

# Let's add a clips to the hd window.
hd.clips.append( clip3 )

# Let's render the result.
#
# Since we didn't set output_file on the hd Window, the output will
# be placed in ./output.mp4
hd.render()

Back to Table of Contents

---

Videos and Clips

The Video and Clip objects are tightly related.

A Video represents a source input file. The primary use of the Video object is as an input to the Clip object’s video constructor argument.

Video Constructor arguments:

Argument	Required	Default	Description
filename	Yes	None	The path to a source input file.

Video Public methods:

• get_width() - Return the width of this video in pixels

• get_height() - Return the height of this video in pixels

Clip Constructor arguments:

Argument	Required	Default	Description
video	Yes	None	A Video object to extract this Clip from
start	No	0	The time in seconds from the start of the Video this Clip should begin at
end	No	End of Video	The time in seconds from the start of the Video this Clip should end at. NOTE: The end time is the absolute end time in the source Video, not relative to the start time of this Clip.
display	No	None	If specified, a Display object that determines how this Clip should be rendered

Clip Public methods:

• get_duration() - Return the width of this video in pixels

• get_height() - Return the height of this video in pixels

Video and Clip Examples:

video1 = vedit.Video( "./media/video01.avi" )
video2 = vedit.Video( "./media/video02.wmv" )

# All of video 1
clip1_all = vedit.Clip( video1 )

# Bits of video2, with Display settings that override whatever the
# Display settings of the Windows these are eventually included in.
vid2_display = Display( display_style=vedit.OVERLAY, include_audio=False )
# From second 3-8.5
clip2_a = vedit.Clip( video2, start=3, end=8.5, display=vid2_display )
# From second 12-40
clip2_b = vedit.Clip( video2, start=12, end=40, display=vid2_display )
# From second 99 to the end
clip2_c = vedit.Clip( video2, start=99, display=vid2_display )

Back to Table of Contents

---

Watermarks

The Watermark object gives an easy way to place an image or rectangle of a solid color on top of a resulting Window over a certain time in the video.

Watermark objects are applied to a Window by sending a list of them to the watermarks constructor argument for the Window, or can be applied after construction by setting the .watermarks attribute of a Window.

NOTE: The image file of a watermark is used as is with no scaling,

you must ensure the size of the watermark file is appropriate to the size of the Window it is placed in.

Constructor arguments:

Argument	Required	Default	Description
filename	Yes	None	Path to an image file to use for the Watermark. Mutually exclusive with bgcolor.
x	No	“0”	Passed to the ffmpeg overlay filter’s x argument to position this watermark. Can be a simple numeric value which will be interpreted as a pixel offset from the left, or something more complex like: "main_w-overlay_w-10" to position near the right of the screen.
y	No	“0”	Passed to the ffmpeg overlay filter’s y argument to position this watermark. Can be a simple numeric value which will be interpreted as a pixel offset from the top, or something more complex like: "trunc((main_h-overlay_h)/2)" to position vertically center.
fade_in_start	No	None	If specified the watermark will begin to appear at fade_in_start seconds. Negative values are interpreted as offsets from the end of the video.
fade_in_duration	No	None	If specified, the watermark will fade in over this many seconds to full opacity.
fade_out_start	No	None	If specified, the watermark will begin to vanish at fade_out_start seconds. Negative values are interpreted as offsets from the end of the video.
fade_out_duration	No	None	If specified, the watermark will fade out over this many seconds to full transparency.
bgcolor	No	None	Mutually exclusive with filename. If specified, the width and height arguments are required, and the Watermark will take the form of a rectangle of that size and color.

Watermark Public methods: None

Watermark Examples:

# Let's assume we have an existing Window we want to apply watermarks to.
window = vedit.Window( ... )

# And a watermark image.
watermark_file = "./media/watermark_corner.png"

# Let's add the watermark image in the bottom right of the video.
watermark_image = vedit.Watermark( filename=watermark_file, x="main_w-overlay_w-10", y="main_h-overlay_h-10" )

# Let's fade in the window from white over 3 seconds.
white_intro = vedit.Watermark( bgcolor='White', width=window.width, height=window.height, fade_out_start=0, fade_out_duration=3 )

# Let's fade the window out to black over 5 seconds from the end of the video.
black_outro = vedit.Watermark( bgcolor='Black', width=window.width, height=window.height, fade_in_start=-5, fade_in_duration=5 )

window.watermarks = [ watermark_image, white_intro, black_outro ]

window.render()

Back to Table of Contents

---

Audio

There are a few ways to manipulate the audio of the output:

1. Each Clip can be configured to mix it’s audio into the output by virtue of configuring it with a Display configuration with include_audio=True (the default).

2. Alternatively, if the Clip has no such configuration, the Window it is in can have a Display configuration with include_audio=True.

3. Finally, each Window can have it’s own audio track via the audio_file constructor argument.

All Clip and Window who have audio present will see their audio mixed together in the output.

Finally, for Window objects with an audio_file argument, if the audio file is longer than the duration of the window, the volume of that audio_file stream will fade out over the last 5 seconds of the duration of the Window.

Back to Table of Contents

---

Logging Output

vedit produces lots of output through Python’s logging framework. Messages are at these levels:

debug

Everything, including command output from ffmpeg

info

Step by step notifications of commands run, but curtailing the output

warn

Only notices where vedit is making some determination about what to do with ambiguous inputs

To enable logging output from a script using vedit do something like:

import logging
logging.basicConfig()
log = logging.getLogger()
log.setLevel( logging.DEBUG )

Back to Table of Contents

---

Getting Help

File an issue on GitHub for this project https://github.com/digitalmacgyver/vedit/issues

Back to Table of Contents

Contributing

Feel free to fork and issue a pull request at: https://github.com/digitalmacgyver/vedit

Back to Table of Contents

---

Odds and Ends

• The first video stream encountered in a file is the one used, the rest are ignored.

• The first audio stream encountered in a file is the one used, the rest are ignored.

• The output Sample Aspect Ratio (SAR) for a Window can be set. All inputs and outputs are assumed to have the same SAR. If not set the SAR of the Video input will be used, or 1:1 will be used if there is no Video input.

  • Some video files report strange Sample Aspect Ratio (SAR) via ffprobe. The nonsense SAR value of 0:1 is assumed to be 1:1. SAR ratios between 0.9 and 1.1 are assumed to be 1:1.

• The pixel format of the output can be set, the default is yuv420p.

• The output video frame rate will be set to 30000/1001

• The output will be encoded with the H.264 codec.

• The quality of the output video relative to the inputs is set by the ffmpeg -crf option with an argument of 16, which should be visually lossless.

• If all input clips have the same number of audio channels, those channels are in the output. In any other scenario the resultant video will have a single channel (mono) audio stream.

Back to Table of Contents