video_utils package

Subpackages

Submodules

video_utils.comremove module

For flagging/removing commericals

The ComRemove class is designed to use the comskip CLI (and ffmpeg) to identify and label (via chapters) or remove (via ffmpeg) the commercial segments.

class video_utils.comremove.ComRemove(**kwargs)

Bases: object

For identifying/removing commericals in video

check_size(in_file: str, cut_file: str) → None

Check that the file with no commercials is a reasonable size

A check to see if too much has been removed. If the file size is sane, then just replace the input file with the cut file (one with no commercials). If the file size is NOT sane, then the cut file is removed and the original input file is saved. Borrowed from https://github.com/ekim1337/PlexComskip

Parameters:

  • in_file (str) – Full path of file to run comskip on

  • cut_file (str) – Full path of file with NO commercials

Returns:

None

comchapter(in_file: str, edl_file: str) → str

Create ffmpeg metadata file with chapter information for commercials.

The edl file created by comskip is parsed into an FFMETADATA file. This file can then be passed to ffmpeg to create chapters in the output file marking show and commercial segments.

Parameters:

  • in_file (str) – Full path of file to run comskip on

  • edl_file (str) – Full path of .edl file produced by

Returns:

Path to ffmpeg metadata file

Return type:

str

comcut(in_file: str, edl_file: str) → list[str] | None

Method to create intermediate files that do NOT contain comercials.

Parameters:

  • in_file (str) – Full path of file to run comskip on

  • edl_file (str) – Full path of .edl file produced by

Returns:

File paths for the intermediate files created if successful.

Else, returns None.

Return type:

list

comjoin(tmpfiles: list[str]) → str | None

Join intermediate files that do NOT contain comercials into one file

Parameters:

tmpfiles (list) – Full paths of intermediate files to join

Returns:

Returns path to continous file created by joining

intermediate files if joining is successful. Else returns None.

comskip(in_file: str, name: str = '') → str | None

Locate commerical breaks in the input file

Parameters:

in_file (str) – Full path of file to run comskip on

Keyword Arguments:

name (str) – Name of series or movie (Plex convention). Required if trying to use specific comskip.ini file

Returns:

Path to .edl file produced by comskip IF the comskip runs successfully. If comskip does not run successfully, then None is returned.

convert_txt(txt_file: str, edl_file: str) → str | None

Convert txt file created by comskip to edl_file

Parameters:

  • txt_file (str) – Path to txt_file

  • edl_file (str) – Path to edl_file

Keyword Arguments:

None –

Returns:

Path to edl file

Return type:

str

remove_commercials(in_file: str, chapters: bool = False, name: str = '') → bool

Main method for commercial identification and removal.

Parameters:

in_file (str) – Full path of file to run commercial removal on

Keyword Arguments:

  • chapters (bool) – Set for non-destructive commercial ‘removal’. If set, will generate .chap file containing show segment and commercial break chapter info for FFmpeg.

  • name (str) – Name of series or movie (Plex convention). Required if trying to use specific comskip.ini file

Returns:

If chapters is True, returns string to ffmpeg metadata file on

success, False otherwise. if Chapters is False, returns True on success, False otherwise

video_utils.comremove.cli() → None

Entry point for CLI

video_utils.comremove.file_remove(*args) → None

Delete any number of files

video_utils.mediainfo module

Wrapper class for mediainfo CLI

class video_utils.mediainfo.MediaInfo(infile: str | None = None, **kwargs)

Bases: object

Class that acts as wrapper for mediainfo CLI

property format: str | None

Full name of file format; e.g., MPEG-4, Matroska

get(*args)

Method for geting mediainfo keys; similar to dict.get()

get_audio_info(language: str | list[str] | None = None) → dict | None

Get audio stream information from a video

Audio stream information is obtained using information from the mediainfo command and parsing it into a dictionary in a format that allows for input into ffmpeg command for transcoding.

Parameters:

None –

Keyword Arguments:

language (str,list) – Language(s) for audio tracks. Must be ISO 639-2 codes.

Returns:

Information in a format for input into the ffmpeg command.

Return type:

dict

get_text_info(languages: str | list[str]) → dict | None

Get text stream information from a video

Video stream information is obtained using information from the mediainfo command and parsing it into a dictionary in a format for use in either the video_utils.subtitles.subtitle_extract() or video_utils.subtitles.ccextract() functions to extract the text to individual files and/or convert the text to SRT format.

Parameters:

language (str,list) – Language(s) for text streams. Must be ISO 639-2 codes. Note that language selection is not currently available for mpeg transport streams with CC muxed into video as mediainfo gives no information on CC languagues (20190217)

Keyword Arguments:

None –

Returns:

Dictionary containing the 3 different language strings,

the output extension to be used on the subtitle file, and the MKV ID used to identify tracks in MKVToolNix for each text stream of interest. Returns None if NO text streams found.

Return type:

dict

Note

(20190219) - While this method will parse information from all the text streams in the file, the ccextract function currently only extracts the first CC stream as there is not clear documentation on how to extract specific streams and mediainfo does not return any language information for the streams

get_video_info(x265: bool = False, dolby_vision_file: str | None = None, hdr10plus_file: str | None = None) → dict | None

Get video stream information from a video

Video stream information is obtained using information from the mediainfo command and parsing it into a dictionary in a format that allows for input into ffmpeg command for transcoding. Rate factors for different resolutions are the mid-points from the ranges provided by: https://handbrake.fr/docs/en/latest/workflow/adjust-quality.html

  • RF 18-22 for 480p/576p Standard Definition

  • RF 19-23 for 720p High Definition

  • RF 20-24 for 1080p Full High Definition

  • RF 22-28 for 2160p 4K Ultra High Definition

Rate factors used:

  • 22 : 480p/576p

  • 23 : 720p

  • 24 : 1080p

  • 20 : 2160p

Parameters:

None –

Keyword Arguments:

  • x265 (bool) – Set to force x265 encoding.

  • dolby_vision_file (str) – Path to Dolby Vision metadata file

  • hdr10plus_file (str) – Path to HDF10+ metadata file

Returns:

Information in a format for input into the ffmpeg command.

Return type:

dict

get_x265_opts(video_data: dict, crf: int, dolby_vision_file: str | None, hdr10plus_file: str | None) → list[str]

Get options for x265 encoding

Build options for x265, namely HDR encoding flags

property hdr_format: str
property infile: str | None

Return the input file path

property is_dolby_vision: bool
property is_hd: bool | None

Is file high definition

property is_hdr: bool
property is_hdr10: bool
property is_hdr10plus: bool
property is_sd: bool | None

Is file standard definition

property is_uhd: bool | None

Is file high definition

is_valid_file() → bool | None

Check if file is valid.

This is done by checking that the size of the first video stream is less than the size of the file. This many not work in all cases, but seems to be true for MPEGTS files.

keys() → list

Method for geting mediainfo keys; similar to dict.keys()

property video_size: tuple[int] | None

Method to get dimensions of video

Returns:

Video (width, height) if video stream exists. None otherwise.

Return type:

tuple

video_utils.mediainfo.aspect_adjust(video_data: dict) → str

Check video aspect ratio

Have run into movies that are ‘widescreen’, but the aspect ratio gets goofy and is displayed as full screen. This function acts to fix that by checking the Display and Original aspect ratios and adjust the aspect ratio accordingly.

Parameters:

video_data (dict) – Information about video stream from mediainfo.

Returns:

Empty string if no adjustment needed,

otherwise is a video filter.

Return type:

str

video_utils.mediainfo.mediainfo(fname: str) → dict

Parse mediainfo JSON output

Parse the JSON formatted output of the mediainfo command into a format that is similar to that parsed from the OLDXML style

video_utils.mediainfo.num_convert(val: str) → int | float | str

Convert string to int/float

video_utils.mediainfo.set_resolution(video_height: int) → tuple[int]

Determine video resolution

Given the height (in pixels) of the video, determine the resolution and the constant rate factor for transcoding.

Parameters:

video_height (int) – The height (in pixles) of the source video.

Returns:

Resolution of the video (int) and the

constant rate factor options (list) for ffmpeg

Return type:

tuple

video_utils.version module

video_utils.videoconverter module

For converting/transcoding video files

The class defined here is the ‘main’ class of the entire package, transcoding files, tagging the output, extracting/converting subtitles.

class video_utils.videoconverter.VideoConverter(in_place: bool = False, transcode_log: str | None = None, comskip_log: str | None = None, lang: str | list[str] | None = None, threads: int | None = None, container: str = 'mp4', cpulimit: int | None = None, x265: bool = False, remove: bool = False, comdetect: bool = False, subtitles: bool = False, srt: bool = False, sub_delete_source: bool = False, crop: bool = False, **kwargs)

Bases: ComRemove, MediaInfo, OpenSubtitles

Convert video files to h264/265 MP4/MKV

Video files must be decodeable by the ffmpeg video software. All audio tracks will be passed through to the output file The x264 video code will be used for all files with resolutions of 1080P and lower, while x265 will be used for all videos with resolution greater than 1080P. The x265 codec can be enabled for lower resolution videos.

Dependencies:

ffmpeg, mediainfo

property container: str

Video container; e.g., mp4 or mkv

file_info(infile: str, metadata: dict | None = None) → bool | None

Extract some information from the input file name

Extracts information from the input file name and sets up some output file variables.

Parameters:

infile (str) – Full path of file

Keyword Arguments:

metadata (dict) – Metadata for file; if none entered, will attempt to get metadata from TMDb or TVDb

Returns:

None

get_subtitles(*args, **kwargs) → None

Try to get subtitles through various means

Get subtitles for a movie/tv show via extracting VobSub(s) from the input file and converting them to SRT file(s). If a file fails to convert, the VobSub files are removed.

Parameters:

None –

Keyword Arguments:

None –

Returns:

Updates sub_status and creates/updates list of VobSubs that

failed vobsub2srt conversion.

Return codes:

  • 0 : Completed successfully.

  • 1 : VobSub(s) and SRT(s) already exist

  • 2 : Error extracting VobSub(s).

  • 3 : VobSub(s) are still being extracted.

Dependencies:

  • mkvextract : A CLI for extracting streams for an MKV file.

  • vobsub2srt : A CLI for converting VobSub images to SRT

hdr_metadata() → None

To get HDR metdata from input file

We check to see if the file has any HDR information. If it does, then we extract the HEVC video stream so that we can try to get any Dolby Vision and/or HDR10+ metadata from the files. We also have to re-evalute that video encoding settings based on HDR color metadata for the video and (if any) DV/HDR10+ data.

In the case of HDR content, the FFmpeg transcode command that is run actually creates two (2) files; one with the transcoded video stream and another with audio, chapter, etc. information. This is done so that any Dolby Vision/HDR10+ metadata can be injected back into the re-encoded HEVC stream.

property outdir: str

Output directory for transcoded and extra files

property threads
transcode(infile: str, log_file: str | None = None, metadata: dict | None = None, chapters: bool = False, **kwargs) → str | bool | None

Actually transcode a file

Designed mainly with MKV file produced by MakeMKV in mind, this method acts to setup options to be fed into the ffmpeg CLI to transcode the file. A non-exhaustive list of options chosen are

  • Set quality rate factor for x264/x265 based on video resolution

    and the recommended settings found here: https://handbrake.fr/docs/en/latest/workflow/adjust-quality.html

  • Used variable frame rate, which ‘preserves the source timing

  • Uses x264 codec for all video 1080P or lower, uses x265 for

    video greater than 1080P, i.e., 4K content.

  • Copy any audio streams with more than two (2) channels

  • Extract VobSub subtitle file(s) from the mkv file.

  • Convert VobSub subtitles to SRT files.

This program will accept both movies and TV episodes, however, movies and TV episodes must follow specific naming conventions as specified under in the ‘File Naming’ section below.

Parameters:

infile (str) – Full path to MKV file to covert. Make sure that the file names follow the following formats for movies and TV shows:

Keyword Arguments:

  • log_file (str) – File to write logging information to

  • metadata (dict) – Pass in result from previous call to getMetaData

  • chapters (bool) – Set if commericals are to be marked with chapters. Default is to cut commericals out of video file

  • comdetect (bool) – Set to remove/mark commercial segments in file

Returns:

Outputs a transcoded video file in the MP4 container and

subtitle files, based on keywords used. Also returns codes to signal any errors.

Transcode Status

  • 0 : Everything finished cleanly

  • 1 : Output file exists

  • 5 : comskip failed

  • 10 : No video OR no audio streams

transcode_postprocess(outfile)

To handle result of transcoding

Based on the result of the FFmpeg subprocess, handle what happens to output and intermediate files.

Note that HDR videos are a special case where the FFmpeg actually outputs 2 files: one with just video and one with everything else. These files are then joined together using mkvmerge to create final output file.

Parameters:

outfile (str) – Name of the output file created by FFmpeg

Returns:

If everything went as planned, then the path to

the output file is returned. On failure, None is returned.

Return type:

str | None

Module contents

Collection of utilities to manipulate video files; namely transcoding, subtitle extraction, audio aligning/downmixing, and metadata editing.