VideoStream — PySceneDetect 0.6.5-dev1 documentation

# 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')
    while True:
        frame = video.read()
        if frame is False:
            break
    print("Read %d frames" % video.frame_number)

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.

exception scenedetect.video_stream.FrameRateUnavailable

  Exception instance to provide consistent error messaging across backends when the video frame rate is unavailable or cannot be calculated. Subclass of VideoOpenFailure.

  Parameters:

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

  The stream is guaranteed to be left in a valid state, but the position may be reset.

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.

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 read(decode=True, advance=True)

    Read and decode the next frame as a np.ndarray. Returns False when video ends.

    Parameters:

      - decode (bool) – Decode and return the frame.

      - advance (bool) – Seek to the next frame. If False, will return the current (last) frame.

    Returns:

      If decode = True, the decoded frame (np.ndarray), or False (bool) if end of video. If decode = False, a bool indicating if advancing to the the next frame succeeded.

    Return type:

      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 (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

  abstract property aspect_ratio: float

    Pixel aspect ratio as a float (1.0 represents square pixels).

  property base_timecode: FrameTimecode

    FrameTimecode object to use as a time base.

  abstract property duration: FrameTimecode | None

    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: bytes | str

    Name of the video, without extension, or device.

  abstract property path: bytes | str

    Video or device path.

  abstract property position: 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.