Documentation

Clip

class vidpy.Clip(resource=None, service=None, start=0, end=None, offset=0, **kwargs)

A VidPy clip

Parameters:

• resource (str) – Path to a video file, audio file, image, or melt xml document
• service (str) – Optional melt service
• start (float) – The in-point of the clip in seconds (optional). Setting this will trim from the start of the clip
• end (float) – The out-point of the clip in seconds (optional). Setting this will trim from the end of the clip
• offset (float) – Time in seconds before the clip is played.
• **kwargs – Option parameters that will get sent to melt

alpha_op(operation='shave', thresh=0.5, amount=0.333344, invert=False, display='image', input_as_alpha=0)

Display and manipulate the alpha channel

Parameters:

• display – Display: what to display. Choices are image, alpha_as_gray, gray+red, black, gray, white and checkers.
• input_as_alpha – use input alpha for the display function above.
• operation (str) – select the operation to be done on the alpha channel. Options are: shave, shrink_hard, shrink_soft, grow_hard, grow_soft, thresh
• thresh (float) – threshold (only used if you’ve selected the thresh operation)
• amount (float) – grow/shrink amount
• invert (bool) – invert the alpha channel

args(singletrack=False)

Returns melt command line arguments as a list

blink(interval)

Blinks the clip at an interval

Parameters:interval (float) – time in seconds for on/off cycle

brightness(brightness=0.5)

Adjusts the brightness of the clip

Parameters:brightness (float) – brightness between 0.0 and 1.0

cartoon(triplevel=0.99, diffspace=0.003)

Cartoonify video, with a form of edge detectection

Parameters:

• triplevel (float) – level of trip (0 to 1)
• diffspace (float) – difference space (0 to 1)

charcoal()

Applies a charcoal effect

chroma(amount=0.15, color=None, blend=None)

Removes a color from the clip, making it transparent

Parameters:

• amount (float) – distance to the color, between 0.0 and 1.0. The higher the number the more will be removed.
• color (str) – The color to remove. If left blank, the top left pixel color will be used.
• blend (float) – Chromakey blend value, between 0 and 1

contrast(amount=0.5)

Adjusts the contrast of the clip

Parameters:contrast (float) – The amount of contrast (between 0 and 1)

crop(top=0, left=0, bottom=0, right=0)

Crops the clip

Parameters:

• top (int) – Pixels to crop from the top
• left (int) – Pixels to crop from the left
• bottom (int) – Pixels to crop from the bottom
• right (int) – Pixels to crop from the right

cut(start=None, end=None, duration=None)

Trims the clip

Parameters:

• start (float) – Time to trim from the start of the clip in seconds
• end (float) – Time to trim from the end of the clip in seconds
• duration (float) – Total duration of the clip (overwrited end)

dither(amount=0.104167)

Dithers the clip and reduces the number of available colors

Parameters:amount (float) – Number of values per channel

duration

Duration of the clip

dust(maxdiameter=2, maxcount=10)

Add dust and specks to the clip

Parameters:

• maxdiameter (int) – Maximal diameter of a dust piece between 0 and 100
• maxcount (int) – How many dust pieces are on the image

dynamic_threshold()

Applies a dynamic thresholding effect

edgeglow(threshold=0.5, upscale=0.5, downscale=0)

Adds glowing edges

Parameters:

• threshold (float) – threshold for edge lightening
• upscale (float) – multiplier for upscaling edge brightness
• downscale (float) – multiplier for downscaling edge brightness

extract_color(color='r')

Extracts either red, green, or blue from clip

Parameters:color (str) – Either ‘r’, ‘g’ or ‘b’

fadein(duration)

Fades the clip in

Parameters:duration (float) – Time to fade in, in seconds

fadeout(duration)

Fades the clip out

Parameters:duration (float) – Time to fade out, in seconds

flip(axis)

Flip the clip over an axis

Parameters:axis (str) – The axis to flip over, either “horizontal” or “vertical”

fx(name, params=None)

Adds any melt filter to a clip

For a full list, see: https://www.mltframework.org/plugins/PluginsFilters/

Parameters:

• name (str) – the name of a filter to add
• params (dict) – a dictionary containing melt filter parameters

get_profile()

Returns the melt generated profile for the clip

glow(blur=0.5)

Apply a glow effect

Parameters:blur (float) – Amount to blur by

gradient(start_color='#ffffff', end_color='#000000', pattern='linear', start_opacity=0.5, end_opacity=0.5, start_x=0.5, start_y=0, end_x=0.5, end_y=1, offset=0, blend='normal')

Draws a gradient on top of the clip.

Parameters:

• start_color (str) – First color of the gradient
• end_color (str) – Second color of the gradient
• pattern (str) – “linear” or “radial” gradient
• start_opacity (float) – Opacity of the first color of the gradient
• end_opacity (float) – Opacity of the second color of the gradient
• start_x (float) – X position of the start point of the gradient
• start_y (float) – Y position of the start point of the gradient
• end_x (float) – X position of the end point of the gradient
• end_y (float) – Y position of the end point of the gradient
• offset – Position of first color in the line connecting gradient ends, really useful only for radial gradient
• blend (str) – Blend mode. Values can be: ‘normal’, ‘add’, ‘saturate’, ‘multiply’, ‘screen’, ‘overlay’, ‘darken’, ‘lighten’, ‘colordodge’, ‘colorburn’, ‘hardlight’, ‘softlight’, ‘difference’, ‘exclusion’, ‘hslhue’, ‘hslsaturation’, ‘hslcolor’, or ‘hslluminosity’

grain(noise=40, contrast=160, brightness=70)

Adds grain over the clip

Parameters:

• noise (int) – Maximal value of noise (0 to 200)
• contrast (int) – Adjust contrast for the image (0 to 400)
• brightness (int) – Adjust brightness for the image (0 to 400)

grayscale()

Convert the clip to grayscale

height

Height of the original clip

hflip()

Flip the clip horizontally

hue(shift=0)

Adjusts the hue of the clip

Parameters:shift (float) – The amount to shift the hue by (between 0 and 1)

invert()

Inverts the colors of the clip

loop()

Loops the clip indefinitely

luminance()

Creates a luminance map of the clip

mirror(axis='horizontal', reverse=False)

Provides various mirror and image reversing effects.

Parameters:

• axis (str) – can be either “horizontal”, “vertical”, “diagonal”, “xdiagonal”, “flip”, or “flop”
• reverse (bool) – reverse the mirror

move(sequence, repeat=False, cycle=0, mirror=False)

Moves the clip around.

Takes a list of (keyframe, x, y, w, h) params At each target frame, the clip will be moved and optionally resized to the supplied x,y,w,h params.

You can use pixels or percentages (in quotes)

Parameters:sequence (list) – a sequence of (keyframe, x, w, w, h) params

opacity(amount)

Sets the clip’s opacity

Parameters:amount (float) – Opacity, between 0.0 and 1.0

original_duration

Duration of the original clip

original_fps

FPS of the original clip

pixelize(width=0.1, height=0.1)

Pixelize the clip

Parameters:

• width (float) – Horizontal size of one pixel, as percent of screen size (0 to 1)
• height (float) – Vertical size of one pixel, as percent of screensize (0 to 1)

position(x=0, y=0, w='100%', h='100%', distort=True)

Positions and resizes the clip. Coordinates can be either in pixels or percent.

To maintain aspect ration, set distort=False

Parameters:

• x – optional x coordinate
• y – optional y coordinate
• w – optional width
• h – optional height
• distort (bool) – Option to distort the image or maintain its ratio

posterize(levels=0.1)

Posterizes the clip by reducing the number of colors used.

Parameters:levels (float) – Number of values per channel

preview()

Previews the clip

repeat(total)

Repeats the clip

Parameters:total (int) – How many times to repeat the clip

resize(w='100%', h='100%', distort=True)

Resizes the clip. Coordinates can be either in pixels or percent.

To maintain aspect ration, set distort=False

Parameters:

• w – optional width
• h – optional height
• distort (bool) – Option to distort the image or maintain its ratio

rotate(amount=1, axis='x')

Rotate the clip along an axis

Parameters:

• amount (float) – Degrees to rotate by
• axis (str) – The axis to rotate over, by default “x”

saturate(saturation=0.125)

Adjusts the saturation of the clip

Parameters:saturation (float) – Saturation amount (0 to 1)

save(filename, **kwargs)

Saves the clip as a video file

Parameters:

• filename (str) – The file to save to.
• kwargs – Pass in any arguments that you would to Composition (width, height, fps, bgcolor)

set_duration(duration)

Sets the duration of the clip

Parameters:duration (float) – Duration of the clip in seconds

set_mask(clip)

Sets the mask for the clip based on the luma values of a video, image, or vidpy Clip

Parameters:clip (Clip or path) – any vidpy clip, or path to video or image

set_offset(offset)

Sets the offset of the clip - determines when the clip will start playing.

Parameters:offset (float) – Offset of the clip in seconds

sharpness(amount=0.3, size=0)

Sharpens the clips https://www.mltframework.org/plugins/FilterFrei0r-sharpness/

Parameters:

• amount (float) – amount
• size (float) – size

sobel()

Applies a sobel filter

softglow(blur=0.5, brightness=0.75, sharpness=0.85, blurblend=0)

Does softglow effect on highlights

Parameters:

• blur (float) – Blur of the glow
• brightness (float) – Brightness of highlight areas
• sharpness (float) – Sharpness of highlight areas
• blurblend (float) – lend mode used to blend highlight blur with input image

speed(speed)

Sets the playback speed of the clip.

The speed can be any number between 20 and 0.01. Negative values will play video in reverse.

Parameters:speed (float) – playback speed

spin(speed=1, axis='x')

Spin the clip continuously. But why?

Parameters:

• speed (float) – Speed to rotate by
• axis (str) – The axis to rotate over, by default “x”

squareblur(size=0.5)

Blurs the clip

Parameters:size (float) – Amount of blur (0 to 1)

text(text, color='#ffffff', bgcolor='0x00000000', olcolor='0x00000000', outline=0, halign='center', valign='middle', pad=0, font='Sans', size=1080, style='normal', weight=400, bbox=(0, 0, '100%', '100%'))

Overlays text on a clip.

Parameters:

• text (str) – The text
• font (str) – The font family to use
• color (str) – Text foreground color
• bgcolor (str) – Optional background color
• olcolor (str) – Text outline color
• outline (int) – Outline size
• style (str) – Font style, can be “normal” or “italic”
• weight (int) – The weight of the text (boldness). Can be between 100 and 1000
• bbox (list) – A bounding box for text to appear in. By default is (0, 0, ‘100%’, ‘100%’
• halign (str) – Horizontal aligment of text. Can be “center” (default), “left” or “right”
• valign (str) – Vertical aligment of text. Can be “middle” (default), “top” or “bottom”

threshold(threshold=0.5)

Thresholds the clip

Parameters:threshold (float) – Threshold value (0 to 1)

total_frames

Total frames in the original clip

transition(name, params=None)

Adds any melt transition to a track

For a full list, see: https://www.mltframework.org/plugins/PluginsTransitions/

Parameters:

• name (str) – the name of a transition to add
• params (dict) – a dictionary containing melt transition parameters

vflip()

Flip the clip vertically

vignette(aspect=0.5, clear=0, softness=0.6)

Applies a vignette effect

Parameters:

• aspect (float) – Aspect ratio (0 to 1)
• clear (float) – Size of the unaffected center (0 to 1)
• softness (float) – Softness (0 to 1)

volume(amt)

Sets the volume for the clip, from 0 (mute) to 1 (full volume)

Parameters:amt (float) – Volume between 0 and 1

width

Width of the original clip

zoompan(origin, dest, start=0, end=-1)

Zooms and pans the clip over time

Takes an origin and destination coordinates either in pixels or percent.

Parameters:

• origin (list) – where to start from, as an [x, y, width, height] list
• dest (list) – where to end up as an [x, y, width, height] list
• start (float) – when to start the zoompan in seconds
• end (float) – when to end the zoompan in seconds

Text

class vidpy.Text(text, start=0, end=None, offset=0, color='#ffffff', bgcolor='0x00000000', olcolor='0x00000000', outline=0, halign='center', valign='middle', pad=0, font='Sans', size=1080, style='normal', weight=400, bbox=(0, 0, '100%', '100%'), **kwargs)

Subclass of Clip that allows you to write text in your composition

Parameters:

• text (str) – The text
• font (str) – The font family to use
• color (str) – Text foreground color
• bgcolor (str) – Optional background color
• olcolor (str) – Text outline color
• outline (int) – Outline size
• style (str) – Font style, can be “normal” or “italic”
• weight (int) – The weight of the text (boldness). Can be between 100 and 1000
• bbox (list) – A bounding box for text to appear in. By default is (0, 0, ‘100%’, ‘100%’
• halign (str) – Horizontal aligment of text. Can be “center” (default), “left” or “right”
• valign (str) – Vertical aligment of text. Can be “middle” (default), “top” or “bottom”

Color

class vidpy.Color(color, **kwargs)

Subclass of Clip to create solid colors

Parameters:color (str) – the color of the clip

Camera

class vidpy.Camera(device=0, avformat='avfoundation', pixel_format='yuyv422', width=1280, height=720, fps=30, **kwargs)

Captures from a camera using ffmpeg

(Only tested on Mac)

Parameters:

• device – The device to use (by default, 0)
• avformat – The format to use in ffmpeg (avfoundation by default)
• width (int) – width of capture (default 1280)
• height (int) – height of capture (default 720)

Composition

class vidpy.Composition(clips, bgcolor='#000000', singletrack=False, duration=None, fps=None, width=None, height=None)

A composition made of a list of clips.

Parameters:

• clips (list) – A list of Clip objects
• bgcolor (str) – The background color of the composition, in hex
• singletrack (bool) – Boolean that determines if clips play all at once (default) or sequentially
• duration (float) – Duration of the composition in seconds.
• fps (int) – Frames per second of output
• width (int) – Width of output in pixels
• height (int) – Height of output in pixels

args()

Generate mlt command line arguments

Returns:mlt command line arguments Return type:str

preview()

Previews the composition using melt’s default viewer.

save(filename, **kwargs)

Save the composition as a video file.

Parameters:

• filename (str) – the file to save to (any video type is accepted)
• **kwargs – additional parameters to pass to ffmpeg

Returns:

the path to the saved file

Return type:

filename (str)

save_xml(filename=None)

Saves the composition as a mlt xml file.

Parameters:filename (str) – path to save to Returns:path to the saved file Return type:str

xml()

Renders the composition as XML and sets the current duration, width, height and fps.

Returns:an mlt xml representation of the composition Return type:str