video_utils is a Python package containing many tools useful for converting video files to h264/h265 encoded MP4 or MKV files.
- Compatible with Python3
- Will try to download SRT subtitles from opensubtitles.org if no subtitles in input file
- Can tag movies and TV shows
- Can extract closed captions and VOBSUB subtitles from input file and convert to SRT files (dependencies required)
- Can be set to use a certain percentage of CPU available (dependency required)
Be sure to look over the file naming convention in the documents folder to ensure that metadata is properly downloaded.
Whenever possible, please always use the latest version from the repository.
To install it using pip:
pip install git+https://github.com/kwodzicki/video_utils
In order for this package to work, a few command-line utilities are required, while other are optional as they add extra functionality. The required and optional utilities are listed below.
- ffmpeg - Used for transcoding, cutting comercials, audio downmixing, etc.
- MediaInfo - Used to get stream information for transcode settings
- comskip - Used to locate commercials in DVRed files
- MKVToolNix - Used for MKV tagging and extraction of VobSub subtitles from MKV files
- ccextractor - Used to extract captions from DVRed TV files to SRT
- VobSub2SRT - Used to convert VobSub subtitles to SRT subtitles
- cpulimit - Used to prevent processes from using 100% of CPU
This package includes code to tag MP4 video files using data from various websites. These include The Movie Database (TMDb) and The TV Database (TVDb). However, to enable use of TMDb and TVDb, API keys are required.
To get an API key for TMDb, you must go to their website and create an account. After you have created an account, go to your account settings, and then API. From there you can create an API key; the v3 key is what is required.
To get an API key for TVDb, you must go to their website and create an account. After you have created an account, go to API Access and generate a new key.
After you have generated your own API keys, there are two ways to install them.
This method requires you to create a file in your home directory named .video_utilsrc.
If this does not make sense, Method 2 may be the way to go.
After this file is created, you can add your API key(s) to it. Note that if you only registered for one API key, you should only place that one in the file. The file is JSON formatted:
{
"TMDB_API_KEY" : "YOUR_TMDb_KEY_HERE",
"TVDB_API_KEY" : "YOUR_TVDb_KEY_HERE"
}
After you add your API key(s), you can save and close the file.
You won't have to worry about this again unless you need to change your keys!
Note that Settings in the .video_utilsrc are overriden by environment variables; see next section.
This method requires you to set environment variables that the video_utils package can use to get the API keys.
These variables must be set for the user that will be running the package.
To do this, simply add the following lines to your ~/.bashrc or ~/.bash_profile:
export TVDB_API_KEY="YOUR_TVDb_KEY_HERE"
export TMDB_API_KEY="YOUR_TMDb_KEY_HERE"
If code will be run under a user without a home directory, or you just want to make sure that the envrionment variables are defined for all users, you can add the environment variable definitions to the /etc/profile file the same way you did above.
To limit the definition of the variables to specifc users, you can filter by their uid.
For example, if your user is uid 456, then you could add the following to /etc/profile:
# Add TVDB_API_KEY and TMDB_API_KEY environment variables to user with uid 456
if [ "$(id -u)" -eq 456 ]; then
export TVDB_API_KEY="YOUR_TVDb_KEY_HERE"
export TMDB_API_KEY="YOUR_TMDb_KEY_HERE"
fi
To enable automated commercial skipping, ensure that the comskip utility is installed and in your PATH environment variable.
To tune how comskip detects commerical breaks in videos, a .ini file is used.
video_utils provides an easy way to set the .ini file through the config file or an environment variable as discussed below.
By default, the .ini file included in the package (video_utils/config/comskip.ini) will be used for commercial skippping.
To override this behavior, simply set the COMSKIP_INI_DIR environment variable and place the comskip.ini file you would like to use in that directory.
For example, say you have a comskip.ini file in /path/to/comskip_inis/.
Simply add the following line to your ~/.bashrc or ~/.bash_profile:
export COMSKIP_INI_DIR=/path/to/comskip_inis/
If you happen to have tuned .ini files for specific shows, you can also place those in the COMSKIP_INI_DIR directory and they will be used.
However, the file names MUST match the Plex convention for TV Show series name (i.e., Series name (year)) or Movie (i.e., Movie name (year)) for the package to find them.
If no matching series/movie .ini is found, then the package will fall back to the comskip.ini file in the directory.
Note that all files MUST end with the .ini extension.
If code will be run under a user without a home directory, such as Linux where Plex typically runs under the plex user, one can add the environment variable definition to the /etc/profile file, which will define it for all user on the computer. You can also have it only defined for given users based on the uid. For example, if your plex user is uid 456, then you could add the following to /etc/profile:
# Add COMSKIP_INI environment variable if user plex (uid 456)
if [ "$(id -u)" -eq 456 ]; then
export COMSKIP_INI_DIR=/path/to/comskip_inis
fi
Note that you can set the COMSKIP_INI_DIR in the ~/.video_utilsrc file:
{
"COMSKIP_INI_DIR" : "/path/to/comskip_inis"
}
Settings in the .video_utilsrc are overriden by environment variables.
This package provides a few command line utilities for some of the core components.
Commercials can be removed using the comremove utility, which allows for input of a Mpeg Transport Stream file (.ts), with some extra options for .ini file specification and CPU limiting.
For more information use the --help flag when running the utility.
The videotagger utility tags MP4 or MKV files with data from TMDb or TVDb (pending API keys installed) either using the TMDb or TVDb id found in the file name if the file naming convention is used, or using a user supplied id.
For more information use the --help flag when running the utility.
This watchdog is designed to be run as a service that will transcode files created by MakeMKV to h264/5 encoded files.
Note that files should conform to the naming convention outlined in ./docs/Input_File_Naming.pdf.
When setting the output directory for converted files, it is suggested to set the directory to the directory where your Plex Libraries reside.
For example, if your libraries are on a drive mounted at /mnt/PlexHDD, and movies and tv shows are in directories named Movies and TV Shows, respectively, then you will want to set the output directory to /mnt/PlexHDD.
This way, output files will be placed inside your Plex Library tree; this watchdog will attempt to run Plex Scan if run as user plex.
Note that the watchdog does not try to find movie or tv directories, it will use the case-sensitive Movies and TV Shows directory names.
Future versions may allow for explicitly setting the output directories.
This watchdog does a few things:
- Watches specified directory(ies) for new files, filtering by given extensions (default
.mkv) - Attempts to extract subtitles to VobSub (requires MKVToolNix)
- Convert subtitles to SRT (requires VobSub2SRT
- Converts movie to MP4/MKV format using the
VideoConverterclass - Attempts to download and write MP4/MKV tags to file
- Attempts to run
Plex Media Scannerto add output file to Plex Library
Sample workflow for converting files:
- Use MakeMKV to create
.mkvfile; shoud NOT save to directory being watched by this watchdog - Rename the file to conform to input naming convention
- Move/copy file into watched directory
- Let program take care of the rest
See the makemkv_watchdog.service file in ./systemd directory for an example of how to set up a Linux service.
See the makemkv_watchdog.plist file in ./LaunchDaemons directory for an example of how to set up a macOS service.
This watchdog is designed to be run as a service that will post process DVR output, namely for TV shows. This watchdog does a few things:
- Watches specified directory for new DVR files; waits to process file until they are moved to their final location by Plex
- Attempts to get the IMDb id of the episode based on the series name, year, and episode title.
- Renames file to match input file naming convention for video_utils package
- Attempts to add chapters marking commercials in file using
comskipCLI if installed; can remove commercials if --destructive flag is set - Attempts to extract subtitles to SRT using
ccextractorCLI if installed - Converts movie to MP4 format using the
VideoConverterclass - Attempts to download and write MP4 tags to file
- Attempts to run
Plex Media Scannerto locate.mp4file; re-runs scanner if source.tsfile is deleted
Note that this watchdog can be set to run a user specified script (i.e., a post processing script that you have written).
Just use the --script flag when setting up the service; this will override all other flags.
Of course you can always use these utilities in your own code. A brief example of how to use the VideoConverter class is below:
# create an instance of VideoConverter class
from video_utils.videoconverter import VideoConverter
converter = VideoConverter()
# set path to file to convert
file = '/path/to/file/Forgetting Sarah Marshall..2008.tt0800039.mkv'
# transcode the file
converter.transcode( file )
video_utils is released under the terms of the GNU GPL v3 license.