Skip to content

requesters

Contains Request models that validate and prepare a request for extraction.

Request dataclass

Bases: ABC

Protocol defining the interface for validating and preparing extraction requests.

Public Methods:

`validate()` -> `Request`:
    Validate fields if specified and return a validated request of the same
    type.
`prepare()` -> `PreparedRequest`:
    Construct and return a prepared request using a video and a validated
    request of some type. A prepared request is required by an extractor of the
    same type.

Properties:

`is_validated` (bool): If the request has been validated.

is_validated abstractmethod property

is_validated

Return True if Request has been validated, False otherwise.

validate abstractmethod

validate()

Validate fields if specified and return a validated request of the same type.

Source code in videoxt/requesters.py
@abstractmethod
def validate(self) -> "Request":
    """
    Validate fields if specified and return a validated request of the same type.
    """
    ...

prepare abstractmethod

prepare(video)

Construct and return a prepared request using a video and a validated request of some type. A prepared request is required by an extractor of the same type.

Source code in videoxt/requesters.py
@abstractmethod
def prepare(self, video: Video) -> "PreparedRequest":
    """
    Construct and return a prepared request using a video and a validated request
    of some type. A prepared request is required by an extractor of the same type.
    """
    ...

BaseRequest dataclass

Bases: Request

Stores, validates and prepares extraction request arguments shared by all methods.

Fields

`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.

Public Methods

- `validate()` -> `BaseRequest`:
    Validate fields if specified and return a validated `BaseRequest`.
- `prepare()` -> `PreparedBaseRequest`:
    Construct and return a prepared base request using a video and a base
    request. A prepared base request is not used by any extractor. Its sole
    purpose is to validate and prepare the shared request arguments.

Properties

- `is_validated` -> `bool`: If the request has been validated.

start_time class-attribute instance-attribute

start_time = None

stop_time class-attribute instance-attribute

stop_time = None

destdir class-attribute instance-attribute

destdir = None

filename class-attribute instance-attribute

filename = None

verbose class-attribute instance-attribute

verbose = None

overwrite class-attribute instance-attribute

overwrite = None

fps class-attribute instance-attribute

fps = None

is_validated property

is_validated

Return True if Request has been validated, False otherwise.

validate

validate()

Validate fields if specified and return a validated BaseRequest.

Source code in videoxt/requesters.py
def validate(self) -> "BaseRequest":
    """Validate fields if specified and return a validated `BaseRequest`."""
    self._validate_start_time()
    self._validate_stop_time()
    self._validate_fps()
    self._validate_destdir()
    self._validate_filename()
    return self

prepare

prepare(video)

Construct and return a PreparedBaseRequest using self and a Video.

Args:
`video` (Video): Contains video metadata used to prepare request.
Returns:
`PreparedBaseRequest`: A prepared base extraction request.
Source code in videoxt/requesters.py
def prepare(self, video: Video) -> "PreparedBaseRequest":
    """
    Construct and return a `PreparedBaseRequest` using self and a `Video`.

    Args:
    -----
        `video` (Video): Contains video metadata used to prepare request.

    Returns:
    -----
        `PreparedBaseRequest`: A prepared base extraction request.
    """
    p = PreparedBaseRequest(
        video=video,
        start_time=self.start_time,
        stop_time=self.stop_time,
        fps=self.fps,
        destdir=self.destdir,
        filename=self.filename,
        verbose=self.verbose,
    )
    p.prepare()
    return p

AudioRequest dataclass

Bases: BaseRequest

Stores, validates and prepares 'audio' extraction request arguments.

Fields

`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`audio_format` (str | None):
    Set the extracted audio file format. Defaults to 'mp3' if not specified.
    See: `videoxt.constants.SUPPORTED_AUDIO_FORMATS`.
`speed` (float | None):
    Set the speed of the extracted audio. A value of 0.5 will halve the speed of
    the extracted audio. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted audio bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted audio. Defaults to False if not specified.
`volume` (float | None):
    Set the volume of the extracted audio. A value of 0.5 will halve the volume
    of the extracted audio. Defaults to 1.0 if not specified (no change).
`normalize` (bool | None):
    If True, normalize the audio. Normalization adjusts the gain of the audio to
    ensure consistent levels, preventing distortion and enhancing clarity in
    some cases. Defaults to False if not specified.

Public Methods

- `validate()` -> `AudioRequest`:
    Validate fields if specified and return a validated `AudioRequest`.
- `prepare()` -> `PreparedAudioRequest`:
    Construct and return a prepared audio request using a video and a validated
    `AudioRequest`. A prepared audio request is required by an `AudioExtractor`.

Properties

- `is_validated` -> `bool`: If the request has been validated.

audio_format class-attribute instance-attribute

audio_format = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

volume class-attribute instance-attribute

volume = None

normalize class-attribute instance-attribute

normalize = None

validate

validate()

Validate fields if specified and return a validated AudioRequest.

Source code in videoxt/requesters.py
def validate(self) -> "AudioRequest":
    """Validate fields if specified and return a validated `AudioRequest`."""
    super().validate()
    self._validate_audio_format()
    self._validate_speed()
    self._validate_volume()
    self._is_validated = True
    return self

prepare

prepare(video)

Construct and return a PreparedAudioRequest using self and a Video.

Fields will validate before preparation if not validated.

Args:
`video` (Video): Contains video metadata used to prepare request.
Returns:
`PreparedAudioRequest`:
    A prepared audio extraction request, required by an `AudioExtractor`.
Source code in videoxt/requesters.py
def prepare(self, video: Video) -> "PreparedAudioRequest":
    """
    Construct and return a `PreparedAudioRequest` using self and a `Video`.

    Fields will validate before preparation if not validated.

    Args:
    -----
        `video` (Video): Contains video metadata used to prepare request.

    Returns:
    -----
        `PreparedAudioRequest`:
            A prepared audio extraction request, required by an `AudioExtractor`.
    """
    if not self.is_validated:
        self.validate()  # XXX: log

    p = PreparedAudioRequest(
        video=video,
        start_time=self.start_time,
        stop_time=self.stop_time,
        destdir=self.destdir,
        filename=self.filename,
        verbose=self.verbose,
        overwrite=self.overwrite,
        fps=self.fps,
        audio_format=self.audio_format,
        speed=self.speed,
        bounce=self.bounce,
        reverse=self.reverse,
        volume=self.volume,
        normalize=self.normalize,
    )
    p.prepare()
    return p

ClipRequest dataclass

Bases: BaseRequest

Stores, validates and prepares 'clip' extraction request arguments.

Recommended usage: Set a short extraction range. The process can be slow for long or high-resolution videos.

Fields

`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the clip. Defaults to
    the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the clip by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the clip by `n` degrees. Allowed values: 0, 90, 180 or 270. Defaults
    to 0 if not specified (no change).
`speed` (float | None):
    Set the speed of the extracted clip. A value of 0.5 will halve the playback
    speed of the clip. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted clip bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted clip. Defaults to False if not specified.
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the clip. Defaults to False if
    not specified.
`volume` (float | None):
    Set the volume of the extracted clip's audio. A value of 0.5 will halve the
    volume of the clip's audio. Defaults to 1.0 if not specified (no change).
`normalize` (bool | None):
    If True, normalize the audio. Normalization adjusts the gain of the audio to
    ensure consistent levels, preventing distortion and enhancing clarity in
    some cases. Defaults to False if not specified.

Public Methods

- `validate()` -> `ClipRequest`:
    Validate fields if specified and return a validated `ClipRequest`.
- `prepare()` -> `PreparedClipRequest`:
    Construct and return a prepared clip request using a video and a validated
    `ClipRequest`. A prepared clip request is required by a `ClipExtractor`.

Properties

- `is_validated` -> `bool`: If the request has been validated.

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

monochrome class-attribute instance-attribute

monochrome = None

volume class-attribute instance-attribute

volume = None

normalize class-attribute instance-attribute

normalize = None

validate

validate()

Validate fields if specified and return a validated ClipRequest.

Source code in videoxt/requesters.py
def validate(self) -> "ClipRequest":
    """Validate fields if specified and return a validated `ClipRequest`."""
    super().validate()
    self._validate_resize()
    self._validate_dimensions()
    self._validate_rotate()
    self._validate_speed()
    self._validate_volume()
    self._is_validated = True
    return self

prepare

prepare(video)

Construct and return a PreparedClipRequest using self and a Video.

Fields will validate before preparation if not validated.

Args:
`video` (Video): Contains video metadata used to prepare request.
Returns:
`PreparedClipRequest`:
    A prepared clip extraction request, required by a `ClipExtractor`.
Source code in videoxt/requesters.py
def prepare(self, video: Video) -> "PreparedClipRequest":
    """
    Construct and return a `PreparedClipRequest` using self and a `Video`.

    Fields will validate before preparation if not validated.

    Args:
    -----
        `video` (Video): Contains video metadata used to prepare request.

    Returns:
    -----
        `PreparedClipRequest`:
            A prepared clip extraction request, required by a `ClipExtractor`.
    """
    if not self.is_validated:
        self.validate()  # XXX: log

    p = PreparedClipRequest(
        video=video,
        start_time=self.start_time,
        stop_time=self.stop_time,
        destdir=self.destdir,
        filename=self.filename,
        verbose=self.verbose,
        overwrite=self.overwrite,
        fps=self.fps,
        dimensions=self.dimensions,
        resize=self.resize,
        rotate=self.rotate,
        speed=self.speed,
        bounce=self.bounce,
        reverse=self.reverse,
        monochrome=self.monochrome,
        volume=self.volume,
        normalize=self.normalize,
    )
    p.prepare()
    return p

FramesRequest dataclass

Bases: BaseRequest

Stores, validates and prepares 'frames' extraction request arguments.

The images are saved to a directory named after the video file, or to a directory you specify.

Fields

`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`image_format` (str | None):
    Set the extracted image file format. Defaults to 'jpg' if not specified.
    See: `videoxt.constants.SUPPORTED_IMAGE_FORMATS`.
`capture_rate` (int | None):
    Capture every Nth video frame. Defaults to 1 if not specified, which
    extracts every frame within the extraction range.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the images. Defaults
    to the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the images by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the images by `n` degrees. Allowed values: 0, 90, 180 or 270.
    Defaults to 0 if not specified (no change).
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the images. Defaults to False if
    not specified.

Public Methods

- `validate()` -> `FramesRequest`:
    Validate fields if specified and return a validated `FramesRequest`.
- `prepare()` -> `PreparedFramesRequest`:
    Construct and return a prepared frames request using a video and a validated
    `FramesRequest`. A prepared frames request is required by a
    `FramesExtractor`.

Properties

- `is_validated` -> `bool`: If the request has been validated.

image_format class-attribute instance-attribute

image_format = None

capture_rate class-attribute instance-attribute

capture_rate = None

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

monochrome class-attribute instance-attribute

monochrome = None

validate

validate()

Validate fields if specified and return a validated FramesRequest.

Source code in videoxt/requesters.py
def validate(self) -> "FramesRequest":
    """Validate fields if specified and return a validated `FramesRequest`."""
    super().validate()
    self._validate_image_format()
    self._validate_capture_rate()
    self._validate_resize()
    self._validate_dimensions()
    self._validate_rotate()
    self._is_validated = True
    return self

prepare

prepare(video)

Construct and return a PreparedFramesRequest using self and a Video.

Fields will validate before preparation if not validated.

Args:
`video` (Video): Contains video metadata used to prepare request.
Returns:
`PreparedFramesRequest`:
    A prepared frames extraction request, required by a `FramesExtractor`.
Source code in videoxt/requesters.py
def prepare(self, video: Video) -> "PreparedFramesRequest":
    """
    Construct and return a `PreparedFramesRequest` using self and a `Video`.

    Fields will validate before preparation if not validated.

    Args:
    -----
        `video` (Video): Contains video metadata used to prepare request.

    Returns:
    -----
        `PreparedFramesRequest`:
            A prepared frames extraction request, required by a `FramesExtractor`.
    """
    if not self.is_validated:
        self.validate()  # XXX: log

    p = PreparedFramesRequest(
        video=video,
        start_time=self.start_time,
        stop_time=self.stop_time,
        destdir=self.destdir,
        filename=self.filename,
        verbose=self.verbose,
        overwrite=self.overwrite,
        fps=self.fps,
        image_format=self.image_format,
        capture_rate=self.capture_rate,
        dimensions=self.dimensions,
        resize=self.resize,
        rotate=self.rotate,
        monochrome=self.monochrome,
    )
    p.prepare()
    return p

GifRequest dataclass

Bases: BaseRequest

Stores, validates and prepares 'gif' extraction request arguments.

Recommended usage: Set a short extraction range. The process can be slow for long or high-resolution videos.

Fields

`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the gif. Defaults to
    the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the gif by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the gif by `n` degrees. Allowed values: 0, 90, 180 or 270. Defaults
    to 0 if not specified (no change).
`speed` (float | None):
    Set the speed of the extracted gif. A value of 0.5 will halve the playback
    speed of the gif. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted gif bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted gif. Defaults to False if not specified.
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the gif. Defaults to False if
    not specified.

Public Methods

- `validate()` -> `GifRequest`:
    Validate fields if specified and return a validated `GifRequest`.
- `prepare()` -> `PreparedGifRequest`:
    Construct and return a prepared gif request using a video and a validated
    `GifRequest`. A prepared gif request is required by a `GifExtractor`.

Properties

- `is_validated` -> `bool`: If the request has been validated.

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

monochrome class-attribute instance-attribute

monochrome = None

validate

validate()

Validate fields if specified and return a validated GifRequest.

Source code in videoxt/requesters.py
def validate(self) -> "GifRequest":
    """Validate fields if specified and return a validated `GifRequest`."""
    super().validate()
    self._validate_resize()
    self._validate_dimensions()
    self._validate_rotate()
    self._validate_speed()
    self._is_validated = True
    return self

prepare

prepare(video)

Construct and return a PreparedGifRequest using self and a Video.

Fields will validate before preparation if not validated.

Args:
`video` (Video): Contains video metadata used to prepare request.
Returns:
`PreparedGifRequest`:
    A prepared gif extraction request, required by a `GifExtractor`.
Source code in videoxt/requesters.py
def prepare(self, video: Video) -> "PreparedGifRequest":
    """
    Construct and return a `PreparedGifRequest` using self and a `Video`.

    Fields will validate before preparation if not validated.

    Args:
    -----
        `video` (Video): Contains video metadata used to prepare request.

    Returns:
    -----
        `PreparedGifRequest`:
            A prepared gif extraction request, required by a `GifExtractor`.
    """
    if not self.is_validated:
        self.validate()  # XXX: log

    p = PreparedGifRequest(
        video=video,
        start_time=self.start_time,
        stop_time=self.stop_time,
        destdir=self.destdir,
        filename=self.filename,
        verbose=self.verbose,
        overwrite=self.overwrite,
        fps=self.fps,
        dimensions=self.dimensions,
        resize=self.resize,
        rotate=self.rotate,
        speed=self.speed,
        bounce=self.bounce,
        reverse=self.reverse,
        monochrome=self.monochrome,
    )
    p.prepare()
    return p

PreparedRequest dataclass

Bases: ABC, ToJsonMixin

Protocol defining the interface for preparing requests for extraction.

Public Methods:

- `prepare()` -> `PreparedRequest`:
    Prepare fields and return a fully prepared request of some type.
- `json()` -> `str`:
    Return a JSON string representation of the prepared request type.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

is_prepared abstractmethod property

is_prepared

Return True if the request has been prepared, False otherwise.

is_verbose abstractmethod property

is_verbose

Return the state of the verbose field.

prepare abstractmethod

prepare()

Prepare fields and return a fully prepared request of some type.

Source code in videoxt/requesters.py
@abstractmethod
def prepare(self) -> "PreparedRequest":
    """Prepare fields and return a fully prepared request of some type."""
    ...

PreparedBaseRequest dataclass

Bases: PreparedRequest

Prepares and stores request arguments shared by all extraction methods.

Fields

`video` (Video):
    The object containing video metadata used to prepare the request.
`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`destpath` (Path):
    The destination path of the extracted file or directory. Not initialized.
`extraction_range` (dict):
    The range represented as seconds, as timestamps, and frame numbers.
    Not initialized.

Public Methods

- `prepare()` -> `PreparedBaseRequest`:
    Prepare fields and return a fully prepared base request.
- `json()` -> `str`:
    Return a JSON string representation of the prepared base request.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

video instance-attribute

video

start_time class-attribute instance-attribute

start_time = None

stop_time class-attribute instance-attribute

stop_time = None

destdir class-attribute instance-attribute

destdir = None

filename class-attribute instance-attribute

filename = None

verbose class-attribute instance-attribute

verbose = None

overwrite class-attribute instance-attribute

overwrite = None

fps class-attribute instance-attribute

fps = None

destpath class-attribute instance-attribute

destpath = field(init=False)

extraction_range class-attribute instance-attribute

extraction_range = field(init=False, default_factory=dict)

is_prepared property

is_prepared

Return True if the request has been prepared, False otherwise.

is_verbose property

is_verbose

Return the state of the verbose field.

prepare

prepare()

Prepare fields and return a PreparedBaseRequest.

Source code in videoxt/requesters.py
def prepare(self) -> "PreparedBaseRequest":
    """Prepare fields and return a `PreparedBaseRequest`."""
    self._prepare_start_time()
    self._prepare_stop_time()
    self._prepare_fps()
    self._prepare_extraction_range()
    self._prepare_verbose()
    self._prepare_overwrite()
    return self

PreparedAudioRequest dataclass

Bases: PreparedBaseRequest

Prepares and stores 'audio' extraction request arguments.

Fields

`video` (Video):
    The object containing video metadata used to prepare the request.
`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`destpath` (Path):
    The destination path of the extracted file or directory. Not initialized.
`extraction_range` (dict):
    The range represented as seconds, as timestamps, and frame numbers.
    Not initialized.
`audio_format` (str | None):
    Set the extracted audio file format. Defaults to 'mp3' if not specified.
    See: `videoxt.constants.SUPPORTED_AUDIO_FORMATS`.
`speed` (float | None):
    Set the speed of the extracted audio. A value of 0.5 will halve the speed of
    the extracted audio. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted audio bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted audio. Defaults to False if not specified.
`volume` (float | None):
    Set the volume of the extracted audio. A value of 0.5 will halve the volume
    of the extracted audio. Defaults to 1.0 if not specified (no change).
`normalize` (bool | None):
    If True, normalize the audio. Normalization adjusts the gain of the audio to
    ensure consistent levels, preventing distortion and enhancing clarity in
    some cases. Defaults to False if not specified.

Public Methods

- `prepare()` -> `PreparedAudioRequest`:
    Prepare fields and return a fully prepared audio request, required by an
    `AudioExtractor`.
- `json()` -> `str`:
    Return a JSON string representation of the prepared audio request.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

audio_format class-attribute instance-attribute

audio_format = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

volume class-attribute instance-attribute

volume = None

normalize class-attribute instance-attribute

normalize = None

prepare

prepare()

Prepare request fields and return a PreparedAudioRequest, required by an AudioExtractor.

Source code in videoxt/requesters.py
def prepare(self) -> "PreparedAudioRequest":
    """
    Prepare request fields and return a `PreparedAudioRequest`, required by an
    `AudioExtractor`.
    """
    self._check_video_has_audio()
    super().prepare()
    self._prepare_audio_format()
    self._prepare_destpath()
    self._prepare_speed()
    self._prepare_bounce()
    self._prepare_reverse()
    self._prepare_volume()
    self._prepare_normalize()
    self._is_prepared = True
    return self

PreparedClipRequest dataclass

Bases: PreparedBaseRequest

Prepares and stores 'clip' extraction request arguments.

Fields

`video` (Video):
    The object containing video metadata used to prepare the request.
`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`destpath` (Path):
    The destination path of the extracted file or directory. Not initialized.
`extraction_range` (dict):
    The range represented as seconds, as timestamps, and frame numbers.
    Not initialized.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the clip. Defaults to
    the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the clip by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the clip by `n` degrees. Allowed values: 0, 90, 180 or 270. Defaults
    to 0 if not specified (no change).
`speed` (float | None):
    Set the speed of the extracted clip. A value of 0.5 will halve the playback
    speed of the clip. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted clip bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted clip. Defaults to False if not specified.
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the clip. Defaults to False if
    not specified.
`volume` (float | None):
    Set the volume of the extracted clip's audio. A value of 0.5 will halve the
    volume of the clip's audio. Defaults to 1.0 if not specified (no change).
`normalize` (bool | None):
    If True, normalize the audio. Normalization adjusts the gain of the audio to
    ensure consistent levels, preventing distortion and enhancing clarity in
    some cases. Defaults to False if not specified.

Public Methods

- `prepare()` -> `PreparedClipRequest`:
    Prepare fields and return a fully prepared clip request, required by a
    `ClipExtractor`.
- `json()` -> `str`:
    Return a JSON string representation of the prepared clip request.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

monochrome class-attribute instance-attribute

monochrome = None

volume class-attribute instance-attribute

volume = None

normalize class-attribute instance-attribute

normalize = None

prepare

prepare()

Prepare request fields and return a PreparedClipRequest, required by a ClipExtractor.

Source code in videoxt/requesters.py
def prepare(self) -> "PreparedClipRequest":
    """
    Prepare request fields and return a `PreparedClipRequest`, required by a
    `ClipExtractor`.
    """
    super().prepare()
    self._prepare_destpath()
    self._prepare_resize()
    self._prepare_dimensions()
    self._prepare_rotate()
    self._prepare_speed()
    self._prepare_bounce()
    self._prepare_reverse()
    self._prepare_monochrome()
    self._prepare_volume()
    self._prepare_normalize()
    self._is_prepared = True
    return self

PreparedFramesRequest dataclass

Bases: PreparedBaseRequest

Prepares and stores 'frames' extraction request arguments.

Fields

`video` (Video):
    The object containing video metadata used to prepare the request.
`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`image_format` (str | None):
    Set the extracted image file format. Defaults to 'jpg' if not specified.
    See: `videoxt.constants.SUPPORTED_IMAGE_FORMATS`.
`capture_rate` (int | None):
    Capture every Nth video frame. Defaults to 1 if not specified, which
    extracts every frame within the extraction range.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the images. Defaults
    to the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the images by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the images by `n` degrees. Allowed values: 0, 90, 180 or 270.
    Defaults to 0 if not specified (no change).
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the images. Defaults to False if
    not specified.
`images_expected` (int):
    The number of images expected to be written to disk. Not initialized.

Public Methods

- `prepare()` -> `PreparedFramesRequest`:
    Prepare fields and return a fully prepared frames request, required by a
    `FramesExtractor`.
- `json()` -> `str`:
    Return a JSON string representation of the prepared frames request.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

image_format class-attribute instance-attribute

image_format = None

capture_rate class-attribute instance-attribute

capture_rate = None

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

monochrome class-attribute instance-attribute

monochrome = None

images_expected class-attribute instance-attribute

images_expected = field(init=False)

prepare

prepare()

Prepare request fields and return a PreparedFramesRequest, required by a FramesExtractor.

Source code in videoxt/requesters.py
def prepare(self) -> "PreparedFramesRequest":
    """
    Prepare request fields and return a `PreparedFramesRequest`, required by a
    `FramesExtractor`.
    """
    super().prepare()
    self._prepare_destpath()
    self._prepare_filename()
    self._prepare_image_format()
    self._prepare_capture_rate()
    self._prepare_resize()
    self._prepare_dimensions()
    self._prepare_rotate()
    self._prepare_monochrome()
    self._prepare_images_expected()
    self._is_prepared = True
    return self

PreparedGifRequest dataclass

Bases: PreparedBaseRequest

Prepares and stores 'gif' extraction request arguments.

Fields

`video` (Video):
    The object containing video metadata used to prepare the request.
`start_time` (float | int | str | None):
    Specify the extraction's start time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to 0 if not specified.
`stop_time` (float | int | str | None):
    Specify the extraction's stop time in seconds, or as a string in "HH:MM:SS"
    format. Defaults to the video duration if not specified.
`destdir` (Path | None):
    Specify the directory you want to save output to. Defaults to the video's
    directory if not specified.
`filename` (str | None):
    Specify the name of the extracted file(s). Defaults to the video filename
    if not specified.
`verbose` (bool | None):
    If True, the prepared request and extraction results will be printed as JSON
    to console. Defaults to False if not specified.
`overwrite` (bool | None):
    If True, permits overwriting the destination path if the file or directory
    already exists. Defaults to False if not specified.
`fps` (float | None):
    Override the frames per second (fps) value obtained from `cv2` when reading
    the video. This value is used to set the start and stop frames for the
    extraction range. This option should be used only in rare cases where `cv2`
    fails to accurately read the fps. If not specified, it defaults to the fps
    of the video as read by `cv2`.
`dimensions` (tuple[int, int] | None):
    Specify the dimensions (frame width, frame height) of the gif. Defaults to
    the video dimensions if not specified.
`resize` (float | None):
    Resize the dimensions of the gif by a factor of `n`. A value of 0.5
    will halve the dimensions. If you specify `dimensions`, `resize` will apply
    to the dimensions you specify. Defaults to 1.0 if not specified (no change).
`rotate` (int | None):
    Rotate the gif by `n` degrees. Allowed values: 0, 90, 180 or 270. Defaults
    to 0 if not specified (no change).
`speed` (float | None):
    Set the speed of the extracted gif. A value of 0.5 will halve the playback
    speed of the gif. Defaults to 1.0 if not specified (no change).
`bounce` (bool | None):
    If True, bounce the extracted gif bommerang-style. Defaults to False if
    not specified.
`reverse` (bool | None):
    If True, reverse the extracted gif. Defaults to False if not specified.
`monochrome` (bool | None):
    If True, apply a black-and-white filter to the gif. Defaults to False if
    not specified.

Public Methods

- `prepare()` -> `PreparedGifRequest`:
    Prepare fields and return a fully prepared gif request, required by a
    `GifExtractor`.
- `json()` -> `str`:
    Return a JSON string representation of the prepared gif request.
- `verbose_print()` -> `None`:
    Print the JSON string to console with a title, without private keys.

Properties:

- `is_prepared` -> `bool`: If the request has been prepared.
- `is_verbose` -> `bool | None`: Return the state of the verbose field.

dimensions class-attribute instance-attribute

dimensions = None

resize class-attribute instance-attribute

resize = None

rotate class-attribute instance-attribute

rotate = None

speed class-attribute instance-attribute

speed = None

bounce class-attribute instance-attribute

bounce = None

reverse class-attribute instance-attribute

reverse = None

monochrome class-attribute instance-attribute

monochrome = None

prepare

prepare()

Prepare request fields and return a PreparedGifRequest, required by a GifExtractor.

Source code in videoxt/requesters.py
def prepare(self) -> "PreparedGifRequest":
    """
    Prepare request fields and return a `PreparedGifRequest`, required by a
    `GifExtractor`.
    """
    super().prepare()
    self._prepare_destpath()
    self._prepare_resize()
    self._prepare_dimensions()
    self._prepare_rotate()
    self._prepare_speed()
    self._prepare_bounce()
    self._prepare_monochrome()
    self._prepare_reverse()
    self._is_prepared = True
    return self