serialize ¶

Serialization utilities for FFmpeg filter graphs and components.

This module provides functions for serializing and deserializing FFmpeg filter graph components to and from JSON. It handles dataclasses, enums, and other custom types used in the typed-ffmpeg library, enabling filter graphs to be saved to disk and loaded back.

Functions:

Name	Description
`load_class`	Load a class from a string path.
`frozen`	Convert mutable data structures to immutable (frozen) equivalents.
`object_hook`	Custom JSON object hook for deserializing FFmpeg objects.
`loads`	Deserialize a JSON string into Python objects with proper class types.
`to_dict_with_class_info`	Convert Python objects to dictionaries with embedded class information.
`dumps`	Serialize a Python object to a JSON string with class information.

load_class ¶

load_class(path: str, strict: bool = True) -> Any

Load a class from a string path.

This function dynamically imports a class based on its fully qualified path (e.g., 'ffmpeg.dag.nodes.FilterNode'). It's used during deserialization to reconstruct objects from their class names.

Parameters:

Name	Type	Description	Default
`path`	`str`	The fully qualified path to the class (module.submodule.ClassName)	required
`strict`	`bool`	If True, only allow loading classes from the ffmpeg package as a security measure	`True`

Returns:

Type	Description
`Any`	The class object that can be instantiated

Raises:

Type	Description
`AssertionError`	If strict is True and the path doesn't start with 'ffmpeg.'
`ImportError`	If the module or class cannot be found

Example

# Load the FilterNode class
FilterNode = load_class('ffmpeg.dag.nodes.FilterNode')
# Create an instance
node = FilterNode(name='scale', ...)

frozen ¶

frozen(v: Any) -> Any

Convert mutable data structures to immutable (frozen) equivalents.

This function recursively converts lists to tuples and dictionaries to FrozenDict instances, ensuring that the resulting data structure is completely immutable. This is important for dataclasses that are marked as frozen, as they can only contain immutable data.

Parameters:

Name	Type	Description	Default
`v`	`Any`	The value to convert, which may be a list, dict, or any other type	required

Returns:

Type	Description
`Any`	An immutable version of the input value

Example

# Convert a nested structure to immutable form
frozen_data = frozen(
    {"options": ["option1", "option2"], "settings": {"key": "value"}}
)
# Result: FrozenDict with tuple instead of list and nested FrozenDict

object_hook ¶

object_hook(obj: Any, strict: bool = True) -> Any

Custom JSON object hook for deserializing FFmpeg objects.

This function is used by the JSON decoder to convert dictionaries into appropriate Python objects during deserialization. It looks for a special 'class' key that indicates the type of object to create.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	A dictionary from the JSON parser	required
`strict`	`bool`	If True, only allow loading classes from the ffmpeg package	`True`

Returns:

Type	Description
`Any`	Either the original dictionary or an instance of the specified class

Example

# A JSON object with class information
json_obj = {
    "__class__": "ffmpeg.dag.nodes.FilterNode",
    "name": "scale",
    "kwargs": {"width": 1280, "height": 720},
}
# Will be converted to a FilterNode instance

loads ¶

loads(raw: str, strict: bool = True) -> Any

Deserialize a JSON string into Python objects with proper class types.

This function parses a JSON string and reconstructs the original Python objects, including dataclasses and enums, based on class information embedded in the JSON.

Parameters:

Name	Type	Description	Default
`raw`	`str`	The JSON string to deserialize	required
`strict`	`bool`	If True, only allow loading classes from the ffmpeg package	`True`

Returns:

Type	Description
`Any`	The deserialized Python object with proper types

Example

# Deserialize a filter graph from JSON
json_str = '{"__class__": "ffmpeg.dag.nodes.FilterNode", "name": "scale", ...}'
filter_node = loads(json_str)
# filter_node is now a FilterNode instance

to_dict_with_class_info ¶

to_dict_with_class_info(instance: Any) -> Any

Convert Python objects to dictionaries with embedded class information.

This function recursively converts Python objects to dictionaries, lists, and primitive types suitable for JSON serialization. For dataclasses and enums, it adds a 'class' key with the fully qualified class name, allowing them to be reconstructed during deserialization.

Parameters:

Name	Type	Description	Default
`instance`	`Any`	The Python object to convert	required

Returns:

Type	Description
`Any`	A JSON-serializable representation with embedded class information

Example

# Convert a FilterNode to a serializable dict
filter_node = FilterNode(name='scale', ...)
serializable = to_dict_with_class_info(filter_node)
# serializable now contains class information and all attributes

dumps ¶

dumps(instance: Any) -> str

Serialize a Python object to a JSON string with class information.

This function converts a Python object (including dataclasses, enums, and other custom types) to a JSON string that includes class information, allowing it to be deserialized back into the original object types.

Parameters:

Name	Type	Description	Default
`instance`	`Any`	The Python object to serialize	required

Returns:

Type	Description
`str`	A JSON string representation of the object with class information

Example

# Serialize a filter graph to JSON
filter_node = FilterNode(name='scale', ...)
json_str = dumps(filter_node)
# json_str can be saved to a file and later deserialized
# with loads() to reconstruct the original object