Python API

This section includes information for using the pure Python API of bob.io.video.

bob.io.video.get_config()

Returns a string containing the configuration information.

bob.io.video.available_video_codecs() → dict

Returns a dictionary with all available video codec properties.

Returns a dictionary containing a detailed description of the built-in codecs for videos that are available but not necessarily supported.

bob.io.video.available_videoreader_formats() → dict

Returns a dictionary with currently available video input formats.

Returns a dictionary containing a detailed description of the built-in input formats for videos that are available, but not necessarily supported by this library.

bob.io.video.available_videowriter_formats() → dict

Returns a dictionary with currently available video output formats.

Returns a dictionary containing a detailed description of the built-in output formats for videos that are available, but not necessarily supported by this library.

bob.io.video.describe_decoder([key]) → dict

Parameters:

key

[int|str, optional] A key which can be either the decoder name or its numerical identifier.

Returns a dictionary containing a description of properties in the given decoder.

bob.io.video.describe_encoder([key]) → dict

Parameters:

key

[int|str, optional] A key which can be either the encoder name or its numerical identifier.

Returns a dictionary containing a description of properties in the given encoder.

class bob.io.video.reader

Bases: object

reader(filename, [check=True]) -> new reader

Use this object to read frames from video files.

Constructor parameters:

filename

[str] The file path to the file you want to read data from

check

[bool] Format and codec will be extracted from the video metadata. By default, if the format and/or the codec are not supported by this version of Bob, an exception will be raised. You can (at your own risk) set this flag to False to avoid this check.

Video reader objects can read data from video files. The current implementation uses FFmpeg (or libav if FFmpeg is not available) which is a stable freely available video encoding and decoding library, designed specifically for these tasks. You can read an entire video in memory by using the bob.io.video.reader.load() method or use iterators to read it frame by frame and avoid overloading your machine’s memory. The maximum precision data FFmpeg will yield is a 24-bit (8-bit per band) representation of each pixel (32-bit depths are also supported by FFmpeg, but not by this extension presently). So, the output of data is done with uint8 as data type. Output will be colored using the RGB standard, with each band varying between 0 and 255, with zero meaning pure black and 255, pure white (color).

codec_long_name

[str] Full name of the codec in which this video file was recorded in

codec_name

[str] Short name of the codec in which this video file was recorded in

duration

[int] Total duration of this video file in microseconds (long)

filename

[str] The full path to the file that will be decoded by this object

format_long_name

[str] Full name of the format in which this video file was recorded in

format_name

[str] Short name of the format in which this video file was recorded in

frame_rate

[float] Video’s announced frame rate (note there are video formats with variable frame rates)

frame_type

[tuple] Typing information to load each frame separatedly

height

[int] The height of each frame in the video (a multiple of 2)

info

[str] A string with lots of video information (same as str(x))

load()

x.load([raise_on_error=False] -> numpy.ndarray

Loads all of the video stream in a numpy ndarray organized in this way: (frames, color-bands, height, width). I’ll dynamically allocate the output array and return it to you.

The flag raise_on_error, which is set to False by default influences the error reporting in case problems are found with the video file. If you set it to True, we will report problems raising exceptions. If you either don’t set it or set it to False, we will truncate the file at the frame with problems and will not report anything. It is your task to verify if the number of frames returned matches the expected number of frames as reported by the property number_of_frames (or len) of this object.

number_of_frames

[int] The number of frames in this video file

video_type

[tuple] Typing information to load all of the file at once

width

[int] The width of each frame in the video (a multiple of 2)

bob.io.video.supported_video_codecs() → dict

Returns a dictionary with currently supported video codec properties.

Returns a dictionary containing a detailed description of the built-in codecs for videos that are fully supported.

bob.io.video.supported_videoreader_formats() → dict

Returns a dictionary with currently supported video input formats.

Returns a dictionary containing a detailed description of the built-in input formats for videos that are fully supported.

bob.io.video.supported_videowriter_formats() → dict

Returns a dictionary with currently supported video output formats.

Returns a dictionary containing a detailed description of the built-in output formats for videos that are fully supported.

class bob.io.video.writer

Bases: object

writer(filename, height, width, [framerate=25., [bitrate=1500000., [gop=12, [codec=’‘, [format=’‘, [check=True]) -> new writer

Use this object to write frames to video files.

Constructor parameters:

filename

[str] The file path to the file you want to read data from

height

[int] The height of the video (must be a multiple of 2)

width

[int] The width of the video (must be a multiple of 2)

framerate

[float, optional] The number of frames per second

bitrate

[float, optional] The estimated bitrate of the output video

gop

[int, optional] Group-of-Pictures (emit one intra frame every gop frames at most).

codec

[str, optional] If you must, specify a valid FFmpeg codec name here and that will be used to encode the video stream on the output file.

format

[str, optional] If you must, specify a valid FFmpeg output format name and that will be used to encode the video on the output file. Leave it empty to guess from the filename extension.

check

[bool, optional] The video will be created if the combination of format and codec are known to work and have been tested, otherwise an exception is raised. If you set this parameter to False, though, we will ignore this check.

Video writer objects can write data to video files. The current implementation uses FFmpeg (or libav if FFmpeg is not available) which is a stable freely available video encoding and decoding library, designed specifically for these tasks. Videos are objects composed of RGB colored frames. Each frame inserted should be a 3D numpy.ndarray composed of unsigned integers of 8 bits. Each frame should have a shape equivalent to (plane, height, width).

append(frame) → None

Writes a new frame or set of frames to the file.

The frame should be setup as a array with 3 dimensions organized in this way (RGB color-bands, height, width). Sets of frames should be setup as a 4D array in this way: (frame-number, RGB color-bands, height, width). Arrays should contain only unsigned integers of 8 bits.

Note

At present time we only support arrays that have C-style storages (if you pass reversed arrays or arrays with Fortran-style storage, the result is undefined).

bit_rate

[float] The indicative bit rate for this video file, given as a hint to FFmpeg (compression levels are subject to the picture textures)

close() → None

Closes the current video stream and forces writing the trailer. After this point the video is finalized and cannot be written to anymore.

codec_long_name

[str] Full name of the codec in which this video file was recorded in

codec_name

[str] Short name of the codec in which this video file was recorded in

duration

[int] Total duration of this video file in microseconds (long)

filename

[str] The full path to the file that will be decoded by this object

format_long_name

[str] Full name of the format in which this video file was recorded in

format_name

[str] Short name of the format in which this video file was recorded in

frame_rate

[float] Video’s announced frame rate (note there are video formats with variable frame rates)

frame_type

[tuple] Typing information to load each frame separatedly

gop

[int] Group of pictures setting (see the Wikipedia entry for details on this setting)

height

[int] The height of each frame in the video (a multiple of 2)

info

[str] A string with lots of video information (same as str(x))

is_opened

[bool] A flag, indicating if the video is still opened for writing (or has already been closed by the user using close())

number_of_frames

[int] The number of frames in this video file

video_type

[tuple] Typing information to load all of the file at once

width

[int] The width of each frame in the video (a multiple of 2)