Video Information

A. Viewing Video Information

After importing it is important to know all the information about the video source. This information is key to knowing what filters will work with the video as it currently is, and if you will need to change anything to make the source compatible with a particular function you intend to use. The easiest way to obtain this information is by adding .test.ClipInfo() after the video import function (Ex. A-1). This function will display the clip information in the top left corner of the video output.

IMPORTANT: When using VapourSynth-Viewer you will receive "Resize error 3074: no path between colorspaces" when a YUV video is imported that has an "Unknown" color matrix. Read the "Color Matrix" section for examples of how to manually set a color matrix for a video source.

Example (A-1):

from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.avi').text.ClipInfo()
video.set_output()

When it comes to figuring out filter compatibility, the only thing you will need to concern yourself with is the ColorSpace. If you plan to combine multiple clips you will need to pay attention to the ColorSpace, Width, Height, and the frame rate.

B. Color Matrix

One of the most important things to pay attention to for color accuracy when processing videos is the color matrix for videos in the YUV color family. Unlike AviSynth, VapourSynth can read the source for any defined color matrix information. It is impossible to know what color matrix was used when encoding if it is not defined in the file, however there are standards for decoding that can be followed to best guess what it could have been. Standard definition videos typically use SMPTE 170M (also known Rec.601) and high definition video use Rec.709. In VapourSynth the resize functions are used to control color space and color matrix. It is possible to set a color matrix for a video that has an "Unknown" one (Ex. B-1) or even change from one color matrix to another (Ex. B-2).

Example (B-1):

Defining Color Matrix for Standard Definition Video

from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.avi')
video = core.resize.Point(video, matrix_in_s="170m")
video.set_output()

NOTE: For high definition video use matrix_in_s="709".

Example (B-2):

Changing Color Matrix (Rec.709 to Rec.601)

from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.avi')
video = core.resize.Point(video, matrix_in_s="709", matrix_s="170m")
video.set_output()

C. Color Space

Color space is a critical attribute to pay attention to when exporting, combining videos, or attempting to use scripts and filters. VapourSynth breaks color space information down into color families that categorize the different format types. The format type will control the bit-depth and planar format. It is important to pay attention to the color matrix when handling YUV color family videos. If the color matrix is unknown, it is crucial to set one before altering the color space or exporting the video. Read the "Color Matrix" section for examples of how to manually set a color matrix for a video source. In VapourSynth the resize functions are used to control color space and color matrix. It is important to always define the color matrix when converting to any YUV format (Ex. C-1). Unless the color matrix is unknown (Ex. C-2), it will not be required to define when converting YUV to RGB (Ex. C-3).

Example (C-1): Converting Video from RGB to YUV

import vapoursynth as vs
from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.avi')
video = core.resize.Point(video, format=vs.YUV420P8, matrix_s="709")
video.set_output()

Example (C-2): Converting Video from YUV to RGB (Unknown Color Matrix)

import vapoursynth as vs
from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.mp4')
video = core.resize.Point(video, matrix_in_s="170m", format=vs.RGB24)
video.set_output()

Example (C-3): Converting Video from YUV to RGB (Known Color Matrix)

import vapoursynth as vs
from vapoursynth import core
video = core.lsmas.LWLibavSource(r'video.avi')
video = core.resize.Point(video, format=vs.RGB24)
video.set_output()