escaping

Utilities for escaping special characters in FFmpeg command arguments.

This module provides functions for properly escaping special characters in FFmpeg command-line arguments and converting Python dictionaries to FFmpeg command-line parameter formats.

Functions:

Name	Description
convert_kwargs_to_cmd_line_args	Convert a Python dictionary to FFmpeg command-line arguments.
escape	Escape special characters in a string for use in FFmpeg commands.

convert_kwargs_to_cmd_line_args

convert_kwargs_to_cmd_line_args(
    kwargs: dict[str, Any],
) -> list[str]

Convert a Python dictionary to FFmpeg command-line arguments.

This function takes a dictionary of parameter names and values and converts them to a list of strings in the format expected by FFmpeg command-line tools. Each key becomes a parameter prefixed with '-', and its value follows as a separate argument.

Parameters:

Name	Type	Description	Default
kwargs	dict[str, Any]	Dictionary mapping parameter names to their values	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

args = convert_kwargs_to_cmd_line_args(
    {"c:v": "libx264", "crf": 23, "preset": "medium"}
)
# Returns ['-c:v', 'libx264', '-crf', '23', '-preset', 'medium']

Note

If a value is None, only the parameter name is included. If a value is an iterable (but not a string), the parameter is repeated for each value in the iterable.

escape

escape(
    text: str | int | float, chars: str = "\\'=:"
) -> str

Escape special characters in a string for use in FFmpeg commands.

This function adds backslash escaping to specified characters in a string, making it safe to use in FFmpeg filter strings and command-line arguments where certain characters have special meaning.

Parameters:

Name	Type	Description	Default
text	str | int | float	The text to escape (will be converted to string if not already)	required
chars	str	A string containing all characters that should be escaped (default: "\'=:" which handles most common special chars in FFmpeg)	"\\'=:"

Returns:

Type	Description
str	The input text with all specified characters escaped with backslashes

Example

# Escape a filename with spaces for FFmpeg
safe_filename = escape("input file.mp4")  # "input\ file.mp4"

# Escape a filter parameter value
safe_value = escape("key=value", "=:")  # "key\=value"