yuvio 1.6

Welcome to yuvio, a python package for reading and writing uncompressed yuv image and video data. yuvio supports all common yuv pixel formats specified by ffmpeg and more. Its modular design allows fast and easy extension to add support for your own pixel formats. If you believe an important pixel format is missing, feel free to open an issue.

NEW: Added support for colorspace conversion (YCbCr to/from RGB). For usage, see below. Supported specifications are

• 'bt601': Rec. ITU-R BT.601
• 'bt709': Rec. ITU-R BT.709
• 'bt2020': Rec. ITU-R BT.2020
• 'bt2100': Rec. ITU-R BT.2100

Install

yuvio is easily installed using python's pip package manager.

pip install yuvio

Usage

To read and write yuv files, yuvio provides the functions imread, imwrite, mimread and mimwrite for single and multiple frames, respectively. Both require the specification of a pixel format to use for the yuv data.

import yuvio

yuv_frame = yuvio.imread("example_yuv420p.yuv", 1920, 1080, "yuv420p")
yuvio.imwrite("example_yuv420p_copy.yuv", yuv_frame)

yuv_frames = yuvio.mimread("example_yuv420p.yuv", 1920, 1080, "yuv420p")
yuvio.mimwrite("example_yuv420p_copy.yuv", yuv_frames)

Thereby, yuvio is not restricted to file objects and can read and write from/to other io streams as well. For example, this allows to conveniently unpack the individual yuv planes from interleaved yuv data available in memory.

import io
import yuvio

data = ...  # e.g. np.ndarray
buffer = io.BytesIO(data)
yuv_frame = yuvio.imread(buffer, 1920, 1080, "v210")
y = yuv_frame.y
u = yuv_frame.u
v = yuv_frame.v

For advanced use cases, yuvio also provides direct access to the Reader and Writer objects. This allows sequential reading and writing from/to yuv files and may be beneficial for iterating over large files without keeping all frames in memory.

import yuvio

reader = yuvio.get_reader("example_yuv420p.yuv", 1920, 1080, "yuv420p")
writer = yuvio.get_writer("example_yuv420p_copy.yuv", 1920, 1080, "yuv420p")

for yuv_frame in reader:
    writer.write(yuv_frame)

To create custom yuv data, yuvio provides access to convenient yuv frame initializers empty, zeros and ones similar to numpys convenience array initializers.

import yuvio

empty = yuvio.empty(1920, 1080, "yuv420p")
zeros = yuvio.zeros(1920, 1080, "yuv420p")
ones = yuvio.ones(1920, 1080, "yuv420p")

For advanced use cases, yuvio also allows direct yuv frame initialization from custom data using the frame initializer.

import yuvio
import numpy as np

y = 255 * np.ones((1920, 1080), dtype=np.uint8)
u = np.zeros((960, 540), dtype=np.uint8)
v = np.zeros((960, 540), dtype=np.uint8)
frame_420 = yuvio.frame((y, u, v), "yuv420p")

frame_400 = yuvio.frame((y, None, None), "gray")

Colorspace conversion

Colorspace conversion from RGB to YCbCr colorspace and from YCbCr to RGB colorspace is possible using the from_rgb(rgb, pixel_format, specification, value_range) and to_rgb(yuv, specification, value_range) functions.

import yuvio

yuv_frame = ...
rgb = yuvio.to_rgb(yuv_frame, specification='bt709', value_range='limited')
yuv_frame = yuvio.from_rgb(rgb, 'yuv444p', specification='bt709', value_range='limited')

[!IMPORTANT]
Color conversion is only supported for '444' chroma subsampling, i.e., no chroma subsampling. Support for chroma subsampling is planned for a future release.

Formats

Print a complete list of available pixel formats using print(yuvio.pixel_formats). To get detailed information on the IO format of a specific pix_fmt use print(yuvio.pixel_formats[pix_fmt].io_info()).

Currently, the following pixel formats (pix_fmt) are available:

Grayscale/YUV 4:0:0

• 'gray'
• 'gray10le'
• 'gray10be'
• 'gray16le'
• 'gray16be'
• 'gray9le'
• 'gray9be'
• 'gray12le'
• 'gray12be'
• 'gray14le'
• 'gray14be'

Planar YUV 4:2:0

• 'yuv420p'
• 'yuv420p10le'
• 'yuv420p10be'
• 'yuv420p16le'
• 'yuv420p16be'
• 'yuv420p9le'
• 'yuv420p9be'
• 'yuv420p12le'
• 'yuv420p12be'
• 'yuv420p14le'
• 'yuv420p14be'

Semi-planar YUV 4:2:0

• 'nv12'

Planar YUV 4:2:2

• 'yuv422p'
• 'yuv422p10le'
• 'yuv422p10be'
• 'yuv422p16le'
• 'yuv422p16be'
• 'yuv422p9le'
• 'yuv422p9be'
• 'yuv422p12le'
• 'yuv422p12be'
• 'yuv422p14le'
• 'yuv422p14be'

Planar YUV 4:4:4

• 'yuv444p'
• 'yuv444p10le'
• 'yuv444p10be'
• 'yuv444p16le'
• 'yuv444p16be'
• 'yuv444p9le'
• 'yuv444p9be'
• 'yuv444p12le'
• 'yuv444p12be'
• 'yuv444p14le'
• 'yuv444p14be'

Interleaved YUV 4:2:0 (Even lines carry luma and chroma [y0 u0 y1 v0 ...], odd lines carry only luma [y0 y1 ...])

• 'yuv420i'
• 'yuv420i10le'
• 'yuv420i10be'
• 'yuv420i16le'
• 'yuv420i16be'
• 'yuv420i9le'
• 'yuv420i9be'
• 'yuv420i12le'
• 'yuv420i12be'
• 'yuv420i14le'
• 'yuv420i14be'

Interleaved YUV 4:2:2

• 'yuv422i'
• 'yuv422i10le'
• 'yuv422i10be'
• 'yuv422i16le'
• 'yuv422i16be'
• 'yuv422i9le'
• 'yuv422i9be'
• 'yuv422i12le'
• 'yuv422i12be'
• 'yuv422i14le'
• 'yuv422i14be'
• 'yuyv422': Same as 'yuv422i'
• 'uyvy422'
• 'yvyu422'

Interleaved YUV 4:4:4

• 'yuv444i'
• 'yuv444i10le'
• 'yuv444i10be'
• 'yuv444i16le'
• 'yuv444i16be'
• 'yuv444i9le'
• 'yuv444i9be'
• 'yuv444i12le'
• 'yuv444i12be'
• 'yuv444i14le'
• 'yuv444i14be'

Special formats

• 'v210'