tessl/pypi-youtube-dl
Command-line program to download videos from YouTube.com and other video sites
post-processors.mddocs/
Post-Processors
Post-processors handle media processing tasks after download completion, including format conversion, audio extraction, subtitle handling, metadata manipulation, and file system operations.
Capabilities
Audio Processing
FFmpeg-based audio extraction and conversion with support for multiple codecs and quality settings.
class FFmpegExtractAudioPP:
def __init__(self, downloader=None, preferredcodec=None, preferredquality=None, nopostoverwrites=False):
"""
Extract audio from video files.
Parameters:
- downloader: YoutubeDL instance
- preferredcodec (str): Output audio codec ('mp3', 'aac', 'flac', 'vorbis', 'wav', 'opus', 'm4a')
- preferredquality (str): Audio quality (bitrate or quality level)
- nopostoverwrites (bool): Don't overwrite existing post-processed files
"""
def run(self, information):
"""
Run the audio extraction process.
Parameters:
- information (dict): Video information dictionary
Returns:
tuple: (information_dict, files_to_delete)
"""Video Conversion
Video format conversion and re-encoding using FFmpeg.
class FFmpegVideoConvertorPP:
def __init__(self, downloader=None, preferedformat=None):
"""
Convert video files to different formats.
Parameters:
- downloader: YoutubeDL instance
- preferedformat (str): Target video format ('mp4', 'flv', 'ogg', 'webm', 'mkv', 'avi')
"""
def run(self, information):
"""
Run the video conversion process.
Parameters:
- information (dict): Video information dictionary
Returns:
tuple: (information_dict, files_to_delete)
"""Subtitle Processing
Subtitle embedding and format conversion capabilities.
class FFmpegEmbedSubtitlePP:
def __init__(self, downloader=None, subtitlesformat='srt'):
"""
Embed subtitle tracks into video files.
Parameters:
- downloader: YoutubeDL instance
- subtitlesformat (str): Subtitle format ('srt', 'vtt', 'ass')
"""
def run(self, information):
"""
Embed subtitles into video file.
Parameters:
- information (dict): Video information with subtitle files
Returns:
tuple: (information_dict, files_to_delete)
"""
class FFmpegSubtitlesConvertorPP:
def __init__(self, downloader=None, format=None):
"""
Convert subtitles between formats.
Parameters:
- downloader: YoutubeDL instance
- format (str): Target subtitle format ('srt', 'vtt', 'ass', 'lrc')
"""
def run(self, information):
"""
Convert subtitle files to target format.
Parameters:
- information (dict): Video information with subtitle files
Returns:
tuple: (information_dict, files_to_delete)
"""Metadata Processing
Metadata extraction, manipulation, and embedding capabilities.
class FFmpegMetadataPP:
def __init__(self, downloader=None):
"""
Add metadata to media files using FFmpeg.
Parameters:
- downloader: YoutubeDL instance
"""
def run(self, information):
"""
Add metadata to the media file.
Parameters:
- information (dict): Video information with metadata
Returns:
tuple: (information_dict, files_to_delete)
"""
class MetadataFromTitlePP:
def __init__(self, downloader=None, titleformat=None):
"""
Extract metadata from video title using regex.
Parameters:
- downloader: YoutubeDL instance
- titleformat (str): Regex pattern for title parsing
"""
def run(self, information):
"""
Extract metadata from title.
Parameters:
- information (dict): Video information dictionary
Returns:
tuple: (information_dict, files_to_delete)
"""Thumbnail Processing
Thumbnail embedding and manipulation functionality.
class EmbedThumbnailPP:
def __init__(self, downloader=None, already_have_thumbnail=False):
"""
Embed thumbnail image into media files.
Parameters:
- downloader: YoutubeDL instance
- already_have_thumbnail (bool): Whether thumbnail was already downloaded
"""
def run(self, information):
"""
Embed thumbnail into media file.
Parameters:
- information (dict): Video information with thumbnail
Returns:
tuple: (information_dict, files_to_delete)
"""File System Operations
File system and extended attribute processing.
class XAttrMetadataPP:
def __init__(self, downloader=None):
"""
Write metadata to extended file attributes.
Parameters:
- downloader: YoutubeDL instance
"""
def run(self, information):
"""
Write metadata to file extended attributes.
Parameters:
- information (dict): Video information with metadata
Returns:
tuple: (information_dict, files_to_delete)
"""
class ExecAfterDownloadPP:
def __init__(self, downloader=None, exec_cmd=None):
"""
Execute custom command after download completion.
Parameters:
- downloader: YoutubeDL instance
- exec_cmd (str): Command to execute with filename
"""
def run(self, information):
"""
Execute the configured command.
Parameters:
- information (dict): Video information dictionary
Returns:
tuple: (information_dict, files_to_delete)
"""Base PostProcessor Class
Base class that all post-processors inherit from.
class PostProcessor:
def __init__(self, downloader=None):
"""
Base post-processor class.
Parameters:
- downloader: YoutubeDL instance
"""
def set_downloader(self, downloader):
"""
Set the downloader instance.
Parameters:
- downloader: YoutubeDL instance
"""
def run(self, information):
"""
Run the post-processing operation.
Parameters:
- information (dict): Video information dictionary
Returns:
tuple: (information_dict, files_to_delete)
"""
def try_utime(self, path, atime, mtime, errnote='Cannot update utime of file'):
"""
Try to update file access and modification times.
Parameters:
- path (str): File path
- atime (float): Access time
- mtime (float): Modification time
- errnote (str): Error message if operation fails
"""Post-Processor Configuration
Post-processors are configured through the YoutubeDL params dictionary using the postprocessors key:
postprocessors = [
{
'key': 'FFmpegExtractAudio',
'preferredcodec': 'mp3',
'preferredquality': '192',
'nopostoverwrites': False,
},
{
'key': 'FFmpegVideoConvertor',
'preferedformat': 'mp4',
},
{
'key': 'FFmpegMetadata',
},
{
'key': 'EmbedThumbnail',
'already_have_thumbnail': False,
}
]Processing Order
Post-processors run in the order they are specified, with some considerations:
- FFmpegExtractAudio and FFmpegVideoConvertor should run before metadata processors
- FFmpegMetadata should run after format conversion but before subtitle embedding
- FFmpegEmbedSubtitle should run after metadata processing
- XAttrMetadata should run after content-changing processors
- ExecAfterDownload should run last to allow user scripts to process final files
Usage Examples
Audio Extraction
from youtube_dl import YoutubeDL
ydl_opts = {
'format': 'bestaudio/best',
'postprocessors': [{
'key': 'FFmpegExtractAudio',
'preferredcodec': 'mp3',
'preferredquality': '320',
}],
'keepvideo': False,
}
with YoutubeDL(ydl_opts) as ydl:
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])Video Conversion with Metadata
ydl_opts = {
'postprocessors': [
{
'key': 'FFmpegVideoConvertor',
'preferedformat': 'mp4',
},
{
'key': 'FFmpegMetadata',
},
{
'key': 'EmbedThumbnail',
'already_have_thumbnail': False,
}
],
'writethumbnail': True,
}
with YoutubeDL(ydl_opts) as ydl:
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])Custom Command Execution
ydl_opts = {
'postprocessors': [{
'key': 'ExecAfterDownload',
'exec_cmd': 'mv {} /final/destination/',
}],
}
with YoutubeDL(ydl_opts) as ydl:
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])Subtitle Processing
ydl_opts = {
'writesubtitles': True,
'writeautomaticsub': True,
'subtitleslangs': ['en', 'es'],
'postprocessors': [
{
'key': 'FFmpegSubtitlesConvertor',
'format': 'srt',
},
{
'key': 'FFmpegEmbedSubtitle',
}
],
}
with YoutubeDL(ydl_opts) as ydl:
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])Install with Tessl CLI
npx tessl i tessl/pypi-youtube-dl