VideoStream¶
scenedetect.video_stream
Module
This module contains the VideoStream
class, which provides a library agnostic
interface for video input. To open a video by path, use scenedetect.open_video()
:
from scenedetect import open_video
video = open_video('video.mp4')
You can also optionally specify a framerate and a specific backend library to use. Unless specified,
OpenCV will be used as the video backend. See scenedetect.backends
for a detailed example.
New VideoStream
implementations can be
tested by adding it to the test suite in tests/test_video_stream.py.
VideoStream
Interface¶
- class scenedetect.video_stream.VideoStream¶
Interface which all video backends must implement.
- abstract static BACKEND_NAME()¶
Unique name used to identify this backend. Should be a static property in derived classes (BACKEND_NAME = ‘backend_identifier’).
- Return type
str
- abstract property aspect_ratio: float¶
Pixel aspect ratio as a float (1.0 represents square pixels).
- property base_timecode: scenedetect.frame_timecode.FrameTimecode¶
FrameTimecode object to use as a time base.
- abstract property duration: Optional[scenedetect.frame_timecode.FrameTimecode]¶
Duration of the stream as a FrameTimecode, or None if non terminating.
- abstract property frame_number: int¶
Current position within stream as the frame number.
Will return 0 until the first frame is read.
- abstract property frame_rate: float¶
Frame rate in frames/sec.
- abstract property frame_size: Tuple[int, int]¶
Size of each video frame in pixels as a tuple of (width, height).
- abstract property is_seekable: bool¶
True if seek() is allowed, False otherwise.
- abstract property name: Union[bytes, str]¶
Name of the video, without extension, or device.
- abstract property path: Union[bytes, str]¶
Video or device path.
- abstract property position: scenedetect.frame_timecode.FrameTimecode¶
Current position within stream as FrameTimecode.
This can be interpreted as presentation time stamp, thus frame 1 corresponds to the presentation time 0. Returns 0 even if frame_number is 1.
- abstract property position_ms: float¶
Current position within stream as a float of the presentation time in milliseconds. The first frame has a PTS of 0.
- abstract read(decode=True, advance=True)¶
Return next frame (or current if advance = False), or False if end of video.
- Parameters
decode (bool) – Decode and return the frame.
advance (bool) – Seek to the next frame. If False, will remain on the current frame.
- Returns
If decode = True, returns either the decoded frame, or False if end of video. If decode = False, a boolean indicating if the next frame was advanced to or not is returned.
- Return type
Union[ndarray, bool]
- abstract reset()¶
Close and re-open the VideoStream (equivalent to seeking back to beginning).
- Return type
None
- abstract seek(target)¶
Seek to the given timecode. If given as a frame number, represents the current seek pointer (e.g. if seeking to 0, the next frame decoded will be the first frame of the video).
For 1-based indices (first frame is frame #1), the target frame number needs to be converted to 0-based by subtracting one. For example, if we want to seek to the first frame, we call seek(0) followed by read(). If we want to seek to the 5th frame, we call seek(4) followed by read(), at which point frame_number will be 5.
May not be supported on all backend types or inputs (e.g. cameras).
- Parameters
target (Union[FrameTimecode, float, int]) – Target position in video stream to seek to. If float, interpreted as time in seconds. If int, interpreted as frame number.
- Raises
SeekError – An error occurs while seeking, or seeking is not supported.
ValueError – target is not a valid value (i.e. it is negative).
- Return type
None
video_stream
Functions and Constants¶
The following functions and constants are available in the scenedetect.video_stream
module.
- scenedetect.video_stream.DEFAULT_MIN_WIDTH: int = 260¶
The default minimum width a frame will be downscaled to when calculating a downscale factor.
- scenedetect.video_stream.compute_downscale_factor(frame_width, effective_width=260)¶
Get the optimal default downscale factor based on a video’s resolution (currently only the width in pixels is considered).
The resulting effective width of the video will be between frame_width and 1.5 * frame_width pixels (e.g. if frame_width is 200, the range of effective widths will be between 200 and 300).
- Parameters
frame_width (int) – Actual width of the video frame in pixels.
effective_width (int) – Desired minimum width in pixels.
- Returns
The defalt downscale factor to use to achieve at least the target effective_width.
- Return type
int
Exceptions¶
- exception scenedetect.video_stream.VideoOpenFailure(message='Unknown backend error.')¶
Raised by a backend if opening a video fails.
- Parameters
message (str) – Additional context the backend can provide for the open failure.
- exception scenedetect.video_stream.SeekError¶
Either an unrecoverable error happened while attempting to seek, or the underlying stream is not seekable (additional information will be provided when possible).