normalize_video#

nominal.experimental.video_processing.normalize_video(input_path: Path | str, output_path: Path | str, key_frame_interval: int | None = DEFAULT_KEY_FRAME_INTERVAL_SEC, force: bool = True, resolution: Literal['480p', '720p', '1080p', '1440p', '2160p'] | VideoResolution | 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 to video file on local filesystem.

  • output_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 – 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 – If true, forcibly delete existing output path if already exists.

  • resolution – If provided, re-scale the video to fit within the provided resolution, preserving aspect ratio

  • num_threads – 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.