The drawvg filter, introduced in FFmpeg 8.1, enables high-quality vector graphics rendering on video frames using the VGS scripting language. This tool leverages the Cairo library to provide a concise yet powerful way to create dynamic overlays and transitions.

drawvg filter for FFmpeg

drawvg is a FFmpeg filter, available since 8.1, to render vector graphics on top of video frames.

The render is done by executing a script written in its own language, called VGS (Vector Graphics Script). The script consists of a series of commands to describe 2D graphics, which are rasterized using the Cairo library.

VGS is not intended to be used as a general-purpose language. Since its scope is limited, it prioritizes being concise and easy to use. The syntax is heavily inspired by languages like Magick Vector Graphics, or SVG's <path>. Some features of the syntax (like using whitespaces to separate arguments) are also present in languages like TCL or shell scripts. Many command names are taken from PostScript.

Scripts can use FFmpeg expressions to describe graphics dynamically, so they can compute coordinates based on frame dimensions, frame metadata, generate random values, read pixel colors, etc.

Examples

Progress Indicator

The variable t can be used to compute one of the angles of the arcn command to create an animation.

progress.vgs

setvar T 3
setvar R (h / 6)
translate (w - R - 5) (R + 5)
moveto 0 0
arcn 0 0 R
(3 * PI / 2 - (PI * 2 * mod(t - ts, T) / T))
(-PI / 2)
setcolor [email protected]
fill

Using Frame Metadata

drawvg can access the output of cropdetect with the getmetadata command to draw a rectangle representing the calculated area.

cropdetect.vgs

getmetadata cdx lavfi.cropdetect.x
getmetadata cdy lavfi.cropdetect.y
getmetadata cdw lavfi.cropdetect.w
getmetadata cdh lavfi.cropdetect.h
rect cdx cdy cdw cdh
setcolor [email protected]
setlinewidth 10
stroke

CircleCrop Transition

This example creates a transition where a circle can be positioned anywhere to reveal the next frame.

circlecrop.vgs

rect 0 0 w h
setvar d (sin(PI / 2 * (t - ts)))
circle (4 * w / 5) (3 * h / 5) (max(w, h) * (1 - d))
eofill

Reading Colors

The function p(x, y) returns the color of a pixel at given coordinates, allowing for custom pixelization effects using shapes like rhombuses.

pixelate.vgs

setvar SIZE 20
setvar MID (SIZE / 2)
repeat (h / SIZE + 1) {
  save
  if (mod(i, 2)) { translate SIZE 0 }
  repeat (w / SIZE + 1) {
    setvar px (p(0, 0))
    if (not(isnan(px))) { setcolor px }
    moveto (-SIZE) 0
    lineto 0 (-SIZE), SIZE 0, 0 SIZE
    closepath
    preserve
    fill
    setcolor [email protected]
    stroke
    translate (SIZE * 2) 0
  }
  restore
  translate 0 SIZE
}