vedit package

Submodules

vedit.vedit module

Utility for extracting clips from videos, and composing clips together into arbitrary nested “windows” in an output.

Documentation at: https://github.com/digitalmacgyver/vedit

This module requires the ffmpeg binary from the FFmpeg project at https://ffmpeg.org/

The ffmpeg command must have been compiled with support for the libx264 video codec and the libfdk_aac audio codec, for example with this configure command:

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

class vedit.vedit.Clip(video=None, start=0, end=None, display=None)[source]

Bases: object

Clip objects represent a segment of a video which will be composed with other Clip objects into some Window objects using some Display settings and rendered into a result physical video file.

A Clip is a portion (or all) of a the underlying video represented by a Video object.

Inputs:

  • video - a Video object
  • start - Defaults to 0, the time in seconds this clip begins in the source Video
  • end - If specified, the time in seconds this clip ends in the source Video, defaults to the end of the Video
  • display - If specified, the Display settings this clip should be rendered with. If not specified this clip will fall back to the default Display settings of the Window it is being rendered in.
get_channels()[source]

Returns the number of channels in the audio for this video, None if there is no audio.

get_duration()[source]

Returns the duration, in seconds, of this Clip.

get_pix_fmt()[source]

Returns the Pixel Format of the Video this Clip is from.

get_sar()[source]

Returns the Sample Aspect Ratio (SAR) of the Video this Clip is from.

class vedit.vedit.Display(display_style='pad', pad_bgcolor='Black', overlay_concurrency=3, overlay_direction='down', overlay_min_gap=4, pan_direction='alternate', include_audio=True)[source]

Bases: object

Display objects allow for the configuration of how a Clip should be displayed.

Whenever a Clip is rendered, it is rendered with the following Display settings:

  • If the Clip itself has a Display object, those settings are used.
  • Otherwise, if the Window the Clip is being rendered in has a Display object, those settings are used.
  • Otherwise, the default Display settings are used.

The default Display settings are:

  • display_style = PAD
  • pad_bgcolor = ‘Black’

The display_style may be set to one of CROP, PAD, PAN, or OVERLAY.

If display_style is PAD, the pad_bgcolor may be set to any of the colors named recognized by the ‘ffmpeg -colors’ or a RGB code in hexadecimal “#RRGGBB” format.

If display_style is PAN then the pan_direction can bet set to one of UP/RIGHT or DOWN/LEFT or ALTERNATE, it defaults to ALTERNATE.

If display_style is OVERLAY:

  • overlay_direction can be one of LEFT/RIGHT/UP/DOWN and the overlay_concurrency may be set. overlay_concurrency is roughly how many clips can be on the screen at the same time during overlays. Defaults to DOWN.
  • overlay_concurrency lists the maximum number of clips that can be actively cascading at one time. Defaults to 3.
  • overlay_min_gap lists the minimum duration between when two clips may be started to animate. Defaults to 4 seconds.

If include_audio is set to true the audio from this clip will be included in the output, mixed together with whatever other audio is present in concurrent clips.

NOTE: If overlay_min_gap is high relative to the length of videos, there will be times when nothing is cascading and/or there are fewer than overlay_concurrency clips cascading.

get_pan_direction()[source]
class vedit.vedit.Video(filename)[source]

Bases: object

The Video object represents a video associated with a physical file on the filesystem.

A primary source if Clip objects is to cut them out of Video objects.

Inputs: * Filename - Full OS path to a video file.

Outputs: None

get_height()[source]
get_width()[source]
videos = {}
class vedit.vedit.Watermark(filename=None, x='0', y='0', fade_in_start=None, fade_in_duration=None, fade_out_start=None, fade_out_duration=None, bgcolor=None, width=None, height=None)[source]

Bases: object

A list of Watermark objects can be provided to a Window.

Each Watermark is either an image, or a rectangle of a solid color.

Each watermark will be overlayed on the Window when it is rendered in the order they are present in that Window’s watermarks list.

If a watermark image is provided, it The is not scaled before being placed on the Window, so you must ensure it is the appropriate size.

If a image is not provided, then: bgcolor, width, and height must be specified and will create a rectangle of that color and size as the watermark (this can be used to fade a video to black, or fade in from white for example).

The Watermark can be positioned with the x and y arguments, which are passed to the ffmpeg overlay filter, so they can be simple things like the pixel offset from the top left, or complicated expressions like “main_w-overlay_w-10” to right justify the image, or “trunc((main_h-overlay_h)/2)” to vertically center it.

By default the image is present for the whole video.

The appearance of the image can be set to:

  • Begin at fade_in_start
  • End at fade_out_start

Negative values of fade_in_start/fade_out_start are interpreted as offsets from the end of the video, rather than from the beginning.

The Watermark can be made to gradually fade in or out by setting the fade_in_duration or fade_out_duration.

class vedit.vedit.Window(windows=None, clips=None, bgcolor='Black', bgimage_file=None, width=1280, height=720, sample_aspect_ratio=None, pix_fmt=None, x=0, y=0, duration=None, z_index=None, watermarks=None, audio_file=None, audio_desc='', display=None, output_file='./output.mp4', overlay_batch_concurrency=16, force=False)[source]

Bases: object

Window is the primary object to interact with.

A Window composes an arbitrary number of other Window and Clip objects into a final video (and also maybe some images, sound files, watermarks, etc.). Windows can contain Windows which contain Windows etc.

Constructor arguments:

  • windows - Optional list of other Window objects which are children to this Window (may be manipulated after construction by explicitly settings the .windows attribute on the returned object).

  • clips - Option list of Clip objects to be rendered in this Window (may be manipulated after construction by explicitly setting the .clips attribute of the returned object).

  • display - An optional Display object to define how Clips should be rendered in this window (overridden on a Clip by Clip basis of their display argument). Defaults to the default Display() object.

  • bgcolor - Defaults to ‘Black’. In a variety of scenarios where there is no Clip or image content in a region of a Window, what color should that region be.

  • bgimage_file - Defaults to None. In a variety of scenarios where there are no Clips content in a region of the Window, what should be shown instead.

  • width - Defaults to 1280. Width in pixels of this Window.

  • height - Defaults to 720. Height in pixels of this Window.

  • x - Defaults to 0. The x coordinate of the top left pixel of this Window within its immediate parent Window, if any, as measured from the top left.

  • y - Defaults to 0. The y coordinate of the top left pixel of this Window within its immediate parent Window, if any, as measured from the top left.

  • audio_file. Optional. If specified, an audio track to play along with the resultant video.

  • audio_desc. Optional. If provided, text to display over the end of the video for the last 5 seconds.

  • duration - Optional. If specified the duration of the rendered content of this Window.

    Defaults to the length of the optional audio_file, or if that is not provided then defaults to the maximum duration of the rendered clips of this or any child windows.

    The duration of a given set of clips is calculated as the larger of:

    • Either, the length of all non-OVERLAY clips concatenated together
    • Or the length of the display time of all OVERLAY clips given their various staggered start times depending on the number of clips, their overlay concurrency, their durations, etc.

    If the specified duration is shorter than the content of clips some clips will not be shown. If it is longer there will be blank content at the end of the clips.

    If the duration and the length of the audio_file differ, then the audio file will fade out starting 5 seconds before the end of the video.

  • output_file - Defaults to ”./output.mp4” where the resulting video from a call to render this Window will be created.

  • z_index - Optional. If there are multiple windows being rendered, ones with higher z_indexes are rendered on top of others. If two windows have the same z_index which one ends up on top is arbitrary. If not specified windows will have increasing z_index in order of creation.

  • watermarks - Optional. A list of Watermark image objects to overlay on top of the resultant video.

  • sample_aspect_ratio - Optional. The Sample Aspect Ratio (SAR) for the rendered content of this Window. If specified, it must be in “W:H” format. This should not be needed generally unless you are encoding for TV broadcast or similar. Defaults to the SAR if the input Video, or 1:1 if there is no input Video. If multiple input videos have different SARs an Exception is thrown, you must preprocess your inputs to all have the same SAR.

  • pix_fmt - Optional. The pixel format of this window, defaults to yuv420p. All Windows that are rendered together must have the same pix_fmt.

  • overlay_batch_concurrency - Optional. Defaults to 16. An internal parameter that controls how many overlays we will attempt in one command line for FFMPEG. Increasing this value may cause crashes and memory corruption errors, setting it lower increases rendering time.

  • force - Defaults to False, force regeneration of all video content, ignoring what is in the cache.

NOTE: Window objects cache data both within and across program invocations. Broadly this saves a ton of compute time by not re-transcoding Clips whose results can’t change, but can result in the wrong stuff if there are collisions in the cache.

If two Clips have the same elements here, they are assumed to be the same in the Cache:

  • Absolute path to the filename from the underlying Video object
  • Clip start time
  • Clip end time
  • The display_style of the Clip as being rendered in this Window.
  • Clip width
  • Clip height
  • Window pan_direction (only relevant if display_style is PAN and pan_direction is ALTERNATE)
  • The pixel format of this Window

If the Cache is incorrect (most likely because the underlying contents of an input filename have changed), the cache should be cleared by calling the static clear_cache method of the Window class:

Window.clear_cache()

add_watermarks(watermarks, current)[source]
cache_dict = {}
cache_dict_file = 'cachedb'
static clear_cache()[source]

Try to remove all the files in the tmpdir. This is necessary if, for example, an input Video filename has new contents.

clip_render(clip, channels)[source]

Render a single clip into the tmpdir according to the rules defined by the appropriate Display object.

Returns the name of a file where the resulting rendered clip is at.

compute_duration(clips, include_overlay_timing=False)[source]

Don’t actually do anything, just report how long the clips will take to render in this window.

Returns either a float (if include_overlay_timing is false), or a tuple with the float and an array of overlay timing data.

The array of timing data has N elements, one for each clip of type Overlay, and each element is a start time, end time tuple.

The logic is:

Clips whose display_type is not OVERLAY are appended to one another.

Clips whose display_type is OVERLAY cascade on top of those as dictated by the number of them, their durations, and the overlay_concurrency and overlay_min_gap their Displays have.

get_child_windows(include_self=False)[source]

Recursively get the list of all child windows.

get_clip_hash(clip, width, height, pan_direction='', pix_fmt='yuv420p', include_audio=True)[source]

It can be very time consuming to produce a clip from a video, we endeavor here to not do the same work over and over if it’s not needed.

get_display(clip)[source]

Internal utility function to get the Display properties for this Clip being rendered in this Window. The logic is:

  1. If the Clip was created with a Display object, use that.
  2. Otherwise, if the Window was created with a Display object, use that.
  3. Otherwise, use the default Display object.
get_next_renderfile()[source]

Internal utility function, we need to generate a bunch of intermediate files, this generates unique names for them.

get_output_dimensions(cw, ch, ww, wh, operator)[source]
get_pan_clause(clip, direction, c, w)[source]
static load_cache_dict()[source]

If a given Clip is reused across several program invocations, we save time by not recreating it. We store information about what Clips we have around here.

render(helper=False, audio_channels=None)[source]

If helper is true we’re rendering a sub-window, the result of which is an intermediate file stored in the tmpdir somewhere. If helper is False then we are rendering user output, and it will go in the path specified by self.output_file.

render_clips(clips, background_file, audio_channels)[source]

Render the clips for the current window.

Inputs:

self - The current Window

clips - a list of clips to render

background_file - Path to a video file with a background for any OVERLAY clips to be rendered onto, this is returned if the clips argument is the empty list

For each clip we:

1. Check in our cache to see if we already have a version of this clip in the appropriate resolution.

2. If there is a cache miss, produce a clip of the appropriate resolution and cache it.

3. Concatenate and overlay the following clips according to this procedure:

We process the Clips in order in self.clips, and concatenate all the non-OVERLAY clips to one another.

Then we overlay the OVERLAY clips on top, starting at the beginning.

The return value is a file of rendered video, either that containing the clips, or just the background_file itself if there were no clips.

static save_cache_dict()[source]

If a given Clip is reused across several program invocations, we save time by not recreating it. We store information about what Clips we have around here.

static set_tmpdir(tmpdir)[source]
tmpdir = '/tmp/docs/vedit/'
z = 0
vedit.vedit.distribute_clips(clips, windows, min_duration=None, randomize_clips=False)[source]

Utility function for creating collage videos of a set of clips.

Input/Output parameters:

  • windows - A list of vsum.Window objects to distribute the clips among. These Window objects are modified by having whatever clips this function determines to send to them added to the end of their clips list.

Inputs:

  • clips - A list of vsum.Clip objects to distribute
  • min_duration - If set to a numeric value the clips will be repeated over and over until the desired min_duration is met. Otherwise each clip is shown once and the resulting duration is a function of the resulting length within each window.

NOTE: If min_duration is set, once it is obtained no more clips will be added to the result, and some input clips may be unused in that scenario.

  • randomize_clips - If true the input clips array will have it’s contents randomized prior to being distributed, otherwise the resulting clips will be shown in order.

The main idea is that a set of “windows” will be defined, such as this:

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

And clips will be distributed among them.

This attempts to place clips in the window whose aspect ratio is a close match for the clip, while also balancing the total content duration of the clips in the windows (note: this can be different from the total duration of the rendered window when cascading clips are used).

The exact logic used to distribute clips is:

1. Get a prioritize list of windows to put the clip in, the windows are prioritized first by having the closest aspect ratio to the clip, and then among windows with the same aspect ratio from lowest window duration to longest.

2. Then, we walk down this prioritized list and place this clip in the first window such that both:

  • ( window_duration + clip_duration ) <= 1.2*( minimum_window_duration + clip_duration )
  • and, if min_duration is set:
  • window_duration < min_duration
vedit.vedit.gen_background_video(duration, width=1280, height=720, bgcolor='Black', bgimage_file=None, output_file=None)[source]

Create a video file of the desired properties.

Inputs:

  • duration - Time in seconds of the video
  • width / height - Width / height in pixels of the video - these are overridden if bgimage_file is provided.
  • bgcolor - The background color of the video
  • bgimage_file - Optional, if specified the video should consist of this image rather than a solid color, if specified the dimensions of the image determine the width and height.
  • output_file - If specified, the resulting file will be copied to this location.

Outputs: Returns a string denoting the filesystem path where the resulting video can be found (which will differ from output_file).

Module contents

class vedit.Display(display_style='pad', pad_bgcolor='Black', overlay_concurrency=3, overlay_direction='down', overlay_min_gap=4, pan_direction='alternate', include_audio=True)[source]

Bases: object

Display objects allow for the configuration of how a Clip should be displayed.

Whenever a Clip is rendered, it is rendered with the following Display settings:

  • If the Clip itself has a Display object, those settings are used.
  • Otherwise, if the Window the Clip is being rendered in has a Display object, those settings are used.
  • Otherwise, the default Display settings are used.

The default Display settings are:

  • display_style = PAD
  • pad_bgcolor = ‘Black’

The display_style may be set to one of CROP, PAD, PAN, or OVERLAY.

If display_style is PAD, the pad_bgcolor may be set to any of the colors named recognized by the ‘ffmpeg -colors’ or a RGB code in hexadecimal “#RRGGBB” format.

If display_style is PAN then the pan_direction can bet set to one of UP/RIGHT or DOWN/LEFT or ALTERNATE, it defaults to ALTERNATE.

If display_style is OVERLAY:

  • overlay_direction can be one of LEFT/RIGHT/UP/DOWN and the overlay_concurrency may be set. overlay_concurrency is roughly how many clips can be on the screen at the same time during overlays. Defaults to DOWN.
  • overlay_concurrency lists the maximum number of clips that can be actively cascading at one time. Defaults to 3.
  • overlay_min_gap lists the minimum duration between when two clips may be started to animate. Defaults to 4 seconds.

If include_audio is set to true the audio from this clip will be included in the output, mixed together with whatever other audio is present in concurrent clips.

NOTE: If overlay_min_gap is high relative to the length of videos, there will be times when nothing is cascading and/or there are fewer than overlay_concurrency clips cascading.

get_pan_direction()[source]
class vedit.Video(filename)[source]

Bases: object

The Video object represents a video associated with a physical file on the filesystem.

A primary source if Clip objects is to cut them out of Video objects.

Inputs: * Filename - Full OS path to a video file.

Outputs: None

get_height()[source]
get_width()[source]
videos = {}
class vedit.Clip(video=None, start=0, end=None, display=None)[source]

Bases: object

Clip objects represent a segment of a video which will be composed with other Clip objects into some Window objects using some Display settings and rendered into a result physical video file.

A Clip is a portion (or all) of a the underlying video represented by a Video object.

Inputs:

  • video - a Video object
  • start - Defaults to 0, the time in seconds this clip begins in the source Video
  • end - If specified, the time in seconds this clip ends in the source Video, defaults to the end of the Video
  • display - If specified, the Display settings this clip should be rendered with. If not specified this clip will fall back to the default Display settings of the Window it is being rendered in.
get_channels()[source]

Returns the number of channels in the audio for this video, None if there is no audio.

get_duration()[source]

Returns the duration, in seconds, of this Clip.

get_pix_fmt()[source]

Returns the Pixel Format of the Video this Clip is from.

get_sar()[source]

Returns the Sample Aspect Ratio (SAR) of the Video this Clip is from.

class vedit.Window(windows=None, clips=None, bgcolor='Black', bgimage_file=None, width=1280, height=720, sample_aspect_ratio=None, pix_fmt=None, x=0, y=0, duration=None, z_index=None, watermarks=None, audio_file=None, audio_desc='', display=None, output_file='./output.mp4', overlay_batch_concurrency=16, force=False)[source]

Bases: object

Window is the primary object to interact with.

A Window composes an arbitrary number of other Window and Clip objects into a final video (and also maybe some images, sound files, watermarks, etc.). Windows can contain Windows which contain Windows etc.

Constructor arguments:

  • windows - Optional list of other Window objects which are children to this Window (may be manipulated after construction by explicitly settings the .windows attribute on the returned object).

  • clips - Option list of Clip objects to be rendered in this Window (may be manipulated after construction by explicitly setting the .clips attribute of the returned object).

  • display - An optional Display object to define how Clips should be rendered in this window (overridden on a Clip by Clip basis of their display argument). Defaults to the default Display() object.

  • bgcolor - Defaults to ‘Black’. In a variety of scenarios where there is no Clip or image content in a region of a Window, what color should that region be.

  • bgimage_file - Defaults to None. In a variety of scenarios where there are no Clips content in a region of the Window, what should be shown instead.

  • width - Defaults to 1280. Width in pixels of this Window.

  • height - Defaults to 720. Height in pixels of this Window.

  • x - Defaults to 0. The x coordinate of the top left pixel of this Window within its immediate parent Window, if any, as measured from the top left.

  • y - Defaults to 0. The y coordinate of the top left pixel of this Window within its immediate parent Window, if any, as measured from the top left.

  • audio_file. Optional. If specified, an audio track to play along with the resultant video.

  • audio_desc. Optional. If provided, text to display over the end of the video for the last 5 seconds.

  • duration - Optional. If specified the duration of the rendered content of this Window.

    Defaults to the length of the optional audio_file, or if that is not provided then defaults to the maximum duration of the rendered clips of this or any child windows.

    The duration of a given set of clips is calculated as the larger of:

    • Either, the length of all non-OVERLAY clips concatenated together
    • Or the length of the display time of all OVERLAY clips given their various staggered start times depending on the number of clips, their overlay concurrency, their durations, etc.

    If the specified duration is shorter than the content of clips some clips will not be shown. If it is longer there will be blank content at the end of the clips.

    If the duration and the length of the audio_file differ, then the audio file will fade out starting 5 seconds before the end of the video.

  • output_file - Defaults to ”./output.mp4” where the resulting video from a call to render this Window will be created.

  • z_index - Optional. If there are multiple windows being rendered, ones with higher z_indexes are rendered on top of others. If two windows have the same z_index which one ends up on top is arbitrary. If not specified windows will have increasing z_index in order of creation.

  • watermarks - Optional. A list of Watermark image objects to overlay on top of the resultant video.

  • sample_aspect_ratio - Optional. The Sample Aspect Ratio (SAR) for the rendered content of this Window. If specified, it must be in “W:H” format. This should not be needed generally unless you are encoding for TV broadcast or similar. Defaults to the SAR if the input Video, or 1:1 if there is no input Video. If multiple input videos have different SARs an Exception is thrown, you must preprocess your inputs to all have the same SAR.

  • pix_fmt - Optional. The pixel format of this window, defaults to yuv420p. All Windows that are rendered together must have the same pix_fmt.

  • overlay_batch_concurrency - Optional. Defaults to 16. An internal parameter that controls how many overlays we will attempt in one command line for FFMPEG. Increasing this value may cause crashes and memory corruption errors, setting it lower increases rendering time.

  • force - Defaults to False, force regeneration of all video content, ignoring what is in the cache.

NOTE: Window objects cache data both within and across program invocations. Broadly this saves a ton of compute time by not re-transcoding Clips whose results can’t change, but can result in the wrong stuff if there are collisions in the cache.

If two Clips have the same elements here, they are assumed to be the same in the Cache:

  • Absolute path to the filename from the underlying Video object
  • Clip start time
  • Clip end time
  • The display_style of the Clip as being rendered in this Window.
  • Clip width
  • Clip height
  • Window pan_direction (only relevant if display_style is PAN and pan_direction is ALTERNATE)
  • The pixel format of this Window

If the Cache is incorrect (most likely because the underlying contents of an input filename have changed), the cache should be cleared by calling the static clear_cache method of the Window class:

Window.clear_cache()

add_watermarks(watermarks, current)[source]
cache_dict = {}
cache_dict_file = 'cachedb'
static clear_cache()[source]

Try to remove all the files in the tmpdir. This is necessary if, for example, an input Video filename has new contents.

clip_render(clip, channels)[source]

Render a single clip into the tmpdir according to the rules defined by the appropriate Display object.

Returns the name of a file where the resulting rendered clip is at.

compute_duration(clips, include_overlay_timing=False)[source]

Don’t actually do anything, just report how long the clips will take to render in this window.

Returns either a float (if include_overlay_timing is false), or a tuple with the float and an array of overlay timing data.

The array of timing data has N elements, one for each clip of type Overlay, and each element is a start time, end time tuple.

The logic is:

Clips whose display_type is not OVERLAY are appended to one another.

Clips whose display_type is OVERLAY cascade on top of those as dictated by the number of them, their durations, and the overlay_concurrency and overlay_min_gap their Displays have.

get_child_windows(include_self=False)[source]

Recursively get the list of all child windows.

get_clip_hash(clip, width, height, pan_direction='', pix_fmt='yuv420p', include_audio=True)[source]

It can be very time consuming to produce a clip from a video, we endeavor here to not do the same work over and over if it’s not needed.

get_display(clip)[source]

Internal utility function to get the Display properties for this Clip being rendered in this Window. The logic is:

  1. If the Clip was created with a Display object, use that.
  2. Otherwise, if the Window was created with a Display object, use that.
  3. Otherwise, use the default Display object.
get_next_renderfile()[source]

Internal utility function, we need to generate a bunch of intermediate files, this generates unique names for them.

get_output_dimensions(cw, ch, ww, wh, operator)[source]
get_pan_clause(clip, direction, c, w)[source]
static load_cache_dict()[source]

If a given Clip is reused across several program invocations, we save time by not recreating it. We store information about what Clips we have around here.

render(helper=False, audio_channels=None)[source]

If helper is true we’re rendering a sub-window, the result of which is an intermediate file stored in the tmpdir somewhere. If helper is False then we are rendering user output, and it will go in the path specified by self.output_file.

render_clips(clips, background_file, audio_channels)[source]

Render the clips for the current window.

Inputs:

self - The current Window

clips - a list of clips to render

background_file - Path to a video file with a background for any OVERLAY clips to be rendered onto, this is returned if the clips argument is the empty list

For each clip we:

1. Check in our cache to see if we already have a version of this clip in the appropriate resolution.

2. If there is a cache miss, produce a clip of the appropriate resolution and cache it.

3. Concatenate and overlay the following clips according to this procedure:

We process the Clips in order in self.clips, and concatenate all the non-OVERLAY clips to one another.

Then we overlay the OVERLAY clips on top, starting at the beginning.

The return value is a file of rendered video, either that containing the clips, or just the background_file itself if there were no clips.

static save_cache_dict()[source]

If a given Clip is reused across several program invocations, we save time by not recreating it. We store information about what Clips we have around here.

static set_tmpdir(tmpdir)[source]
tmpdir = '/tmp/docs/vedit/'
z = 0
class vedit.Watermark(filename=None, x='0', y='0', fade_in_start=None, fade_in_duration=None, fade_out_start=None, fade_out_duration=None, bgcolor=None, width=None, height=None)[source]

Bases: object

A list of Watermark objects can be provided to a Window.

Each Watermark is either an image, or a rectangle of a solid color.

Each watermark will be overlayed on the Window when it is rendered in the order they are present in that Window’s watermarks list.

If a watermark image is provided, it The is not scaled before being placed on the Window, so you must ensure it is the appropriate size.

If a image is not provided, then: bgcolor, width, and height must be specified and will create a rectangle of that color and size as the watermark (this can be used to fade a video to black, or fade in from white for example).

The Watermark can be positioned with the x and y arguments, which are passed to the ffmpeg overlay filter, so they can be simple things like the pixel offset from the top left, or complicated expressions like “main_w-overlay_w-10” to right justify the image, or “trunc((main_h-overlay_h)/2)” to vertically center it.

By default the image is present for the whole video.

The appearance of the image can be set to:

  • Begin at fade_in_start
  • End at fade_out_start

Negative values of fade_in_start/fade_out_start are interpreted as offsets from the end of the video, rather than from the beginning.

The Watermark can be made to gradually fade in or out by setting the fade_in_duration or fade_out_duration.

vedit.distribute_clips(clips, windows, min_duration=None, randomize_clips=False)[source]

Utility function for creating collage videos of a set of clips.

Input/Output parameters:

  • windows - A list of vsum.Window objects to distribute the clips among. These Window objects are modified by having whatever clips this function determines to send to them added to the end of their clips list.

Inputs:

  • clips - A list of vsum.Clip objects to distribute
  • min_duration - If set to a numeric value the clips will be repeated over and over until the desired min_duration is met. Otherwise each clip is shown once and the resulting duration is a function of the resulting length within each window.

NOTE: If min_duration is set, once it is obtained no more clips will be added to the result, and some input clips may be unused in that scenario.

  • randomize_clips - If true the input clips array will have it’s contents randomized prior to being distributed, otherwise the resulting clips will be shown in order.

The main idea is that a set of “windows” will be defined, such as this:

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

And clips will be distributed among them.

This attempts to place clips in the window whose aspect ratio is a close match for the clip, while also balancing the total content duration of the clips in the windows (note: this can be different from the total duration of the rendered window when cascading clips are used).

The exact logic used to distribute clips is:

1. Get a prioritize list of windows to put the clip in, the windows are prioritized first by having the closest aspect ratio to the clip, and then among windows with the same aspect ratio from lowest window duration to longest.

2. Then, we walk down this prioritized list and place this clip in the first window such that both:

  • ( window_duration + clip_duration ) <= 1.2*( minimum_window_duration + clip_duration )
  • and, if min_duration is set:
  • window_duration < min_duration
vedit.gen_background_video(duration, width=1280, height=720, bgcolor='Black', bgimage_file=None, output_file=None)[source]

Create a video file of the desired properties.

Inputs:

  • duration - Time in seconds of the video
  • width / height - Width / height in pixels of the video - these are overridden if bgimage_file is provided.
  • bgcolor - The background color of the video
  • bgimage_file - Optional, if specified the video should consist of this image rather than a solid color, if specified the dimensions of the image determine the width and height.
  • output_file - If specified, the resulting file will be copied to this location.

Outputs: Returns a string denoting the filesystem path where the resulting video can be found (which will differ from output_file).