Python API

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

bob.io.video.available_video_codecs() → codecs

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 available but not necessarily supported.

Returns:

codecs : dict

A dictionary of available codecs

bob.io.video.available_videoreader_formats() → formats

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.

Returns:

formats : dict

A dictionary of available input formats

bob.io.video.available_videowriter_formats() → formats

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.

Returns:

formats : dict

A dictionary of available output formats

bob.io.video.describe_decoder(key) → description

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

Parameters:

key : `int` or `str`

A key which can be either the decoder name or its numerical identifier.

Returns:

description : dict

The description of the requested encoder

bob.io.video.describe_encoder(key) → description

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

Parameters:

key : `int` or `str`

A key which can be either the encoder name or its numerical identifier.

Returns:

description : dict

The description of the requested encoder

bob.io.video.get_config()

Returns a string containing the configuration information.

class bob.io.video.reader

Bases: object

Use this object to read frames from video files.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).

Constructor Documentation:

reader (filename, [check])

Opens a video file for reading

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 the check flag to False to avoid this check.

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.

Class Members:

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

Todo

Explain, what exactly is contained in this tuple

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(raise_on_error) → video

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 set it to False (the default), 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 number_of_frames (or len) of this object.

Parameters:

raise_on_error : bool

[Default: False] Raise an excpetion in case of errors?

Returns:

video : 3D or 4D numpy.ndarray

The video stream organized as: (frames, color-bands, height, width

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

Todo

Explain, what exactly is contained in this tuple

width

int <– The width of each frame in the video (a multiple of 2)

bob.io.video.supported_video_codecs() → codecs

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.

Returns:

codecs : dict

A dictionary of supported codecs

bob.io.video.supported_videoreader_formats() → formats

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.

Returns:

formats : dict

A dictionary of supported input formats

bob.io.video.supported_videowriter_formats() → formats

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.

Returns:

formats : dict

A dictionary of supported output formats

class bob.io.video.writer

Bases: object

Use this object to write frames to video filesVideo 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).

Constructor Documentation:

writer (filename, height, width, [framerate], [bitrate], [gop], [codec], [format], [check])

Create a video writer

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 the check parameter to False, though, we will ignore this check.

Parameters:

filename : str

The file path to the file you want to write data to

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

[Default: 25.] The number of frames per second

bitrate : float

[Default: 150000.] The estimated bitrate of the output video

gop : int

[Default: 12] Group-of-Pictures (emit one intra frame every gop frames at most)

codec : str

[Default: ''] 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

[Default: ''] 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

[Default: True]

Class Members:

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).

Parameters:

frame : 3D or 4D numpy.ndarray of uint8

The frame or set of frames to write

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 will be written in

codec_name

str <– Short name of the codec in which this video file will be written 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 will be written in

format_name

str <– Short name of the format in which this video file will be written 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

Todo

Explain, what exactly is contained in this tuple

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

Todo

Explain, what exactly is contained in this tuple

width

int <– The width of each frame in the video (a multiple of 2)