Skip to content

video_processing ¤

AnyResolutionType module-attribute ¤

AnyResolutionType: TypeAlias = Union[
    ResolutionSpecifier, VideoResolution
]

FULL_HD module-attribute ¤

FULL_HD = VideoResolution(resolution_height=1080, resolution_width=1920)

HIGH_DEFINITION module-attribute ¤

HIGH_DEFINITION = VideoResolution(
    resolution_height=720, resolution_width=1280
)

QUAD_HD module-attribute ¤

QUAD_HD = VideoResolution(resolution_height=1440, resolution_width=2560)

ResolutionSpecifier module-attribute ¤

ResolutionSpecifier: TypeAlias = Literal[
    "480p", "720p", "1080p", "1440p", "2160p"
]

STANDARD_DEFINITION module-attribute ¤

STANDARD_DEFINITION = VideoResolution(
    resolution_height=480, resolution_width=640
)

ULTRA_HD module-attribute ¤

ULTRA_HD = VideoResolution(
    resolution_height=2160, resolution_width=3840
)

VideoResolution dataclass ¤

VideoResolution(
    resolution_width: int | None = None,
    resolution_height: int | None = None,
    allow_upscaling: bool = False,
)

allow_upscaling class-attribute instance-attribute ¤

allow_upscaling: bool = False

If true, allow upscaling beyond original resolution (e.g. 1080p -> 4k)

resolution_height class-attribute instance-attribute ¤

resolution_height: int | None = None

Height of the video, in pixels. Auto-inferred if None based on aspect ratio. NOTE: MUST be divisible by 2.

resolution_width class-attribute instance-attribute ¤

resolution_width: int | None = None

Width of the video, in pixels. Auto-inferred if None based on aspect ratio. NOTE: MUST be divisible by 2.

scale_factor ¤

scale_factor() -> str

Output a video filter flag usable with Ffmpeg to rescale the resolution of a video.

frame_count ¤

frame_count(video_path: Path) -> int

Given a path to a video file, return the number of frames present in the video.

if no streams are present, returns 0. If multiple streams are present, returns frame count

of the first video stream.

has_audio_track ¤

has_audio_track(video_path: Path) -> bool

Given a path to a video file, return whether or not there is an audio track present.

normalize_video ¤

normalize_video(
    input_path: Path,
    output_path: Path,
    key_frame_interval: int | None = DEFAULT_KEY_FRAME_INTERVAL_SEC,
    force: bool = True,
    resolution: AnyResolutionType | None = None,
    num_threads: int | None = None,
) -> None

Convert video file to an h264 encoded video file using ffmpeg.

This function will also perform several other processing tasks to ensure that video is properly encoded in a way that is best supported by nominal. This includes: * Ensuring that there are key-frames (I-frames) present approximately every 2s of video content * Video is encoded with H264 * Audio is encoded with AAC * Video has YUV4:2:0 planar color space

While this package includes bindings to use ffmpeg installed on your local system, it does not include ffmpeg as a dependency due to the GPLv3 licensing present in the standard H264 processing library contained within, thus, you must have ffmpeg installed locally to use this.

Parameters:

  • input_path ¤

    (Path) –

    Path to video file on local filesystem.

  • output_path ¤

    (Path) –

    Path to write converted video file to. NOTE: it is expected that the output file is either an mkv or a mp4 file.

  • key_frame_interval ¤

    (int | None, default: DEFAULT_KEY_FRAME_INTERVAL_SEC ) –

    Number of seconds between keyframes allowed in the output video. NOTE: While this field is technically optional, setting the right value here can be essential to allowing fluid playback on the frontend, in particular, in network constrained environments. Setting this value too low or too high can impact performance negatively-- typically, a value at or around 2s is considered "best of both worlds" as a reasonable default value.

  • force ¤

    (bool, default: True ) –

    If true, forcibly delete existing output path if already exists.

  • resolution ¤

    (AnyResolutionType | None, default: None ) –

    If provided, re-scale the video to the provided resolution

  • num_threads ¤

    (int | None, default: None ) –

    If provided, the number of CPU cores to tell ffmpeg to use. NOTE: If not provided, ffmpeg will choose. Typically, this amounts to the number of cores present on the machine

NOTE: this requires that you have installed ffmpeg on your system with support for H264.

scale_factor_from_resolution ¤

scale_factor_from_resolution(resolution: AnyResolutionType) -> str

Build a video filter that scales the video using ffmpeg.

Parameters:

  • resolution ¤

    (AnyResolutionType) –

    resolution specifier or explicit / custom resolution to scale video to

Returns:

  • str –

    Video filter specifier that can be used with ffmpeg to re-scale video contents