Python API¶
This section includes information for using the pure Python API of
bob.io.video
.
-
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
(filename[, check=True]) → new reader¶ Bases:
object
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 withuint8
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
([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 toFalse
by default influences the error reporting in case problems are found with the video file. If you set it toTrue
, we will report problems raising exceptions. If you either don’t set it or set it toFalse
, 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 propertynumber_of_frames
(orlen
) 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
(filename, height, width[, framerate=25.[, bitrate=1500000.[, gop=12[, codec=''[, format=''[, check=True]]]]]]) → new writer¶ Bases:
object
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)