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.

Classes:

Name	Description
Serializable	A base class for all serializable classes.

Functions:

Name	Description
serializable	Register a class with the serialization system.
load_class	Load a class from its name.
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.

Attributes:

Name	Type	Description
CLASS_REGISTRY	dict[str, type[Serializable | Enum]]	A registry of classes that have been loaded, and can be deserialized.

CLASS_REGISTRY module-attribute

CLASS_REGISTRY: dict[str, type[Serializable | Enum]] = {}

A registry of classes that have been loaded, and can be deserialized.

Serializable

A base class for all serializable classes.

serializable

serializable(
    cls: type[Serializable] | type[Enum],
) -> type[Serializable] | type[Enum]

Register a class with the serialization system.

load_class

load_class(name: str) -> type[Serializable] | type[Enum]

Load a class from its name.

This function looks up a class by its name in the CLASS_REGISTRY. It's used during deserialization to reconstruct objects from their class names.

Parameters:

Name	Type	Description	Default
name	str	The simple class name (e.g., 'FilterNode')	required

Returns:

Type	Description
type[Serializable] | type[Enum]	The class object that can be instantiated

Raises:

Type	Description
AssertionError	If the class name is not found in the registry

Example

# Load the FilterNode class
FilterNode = load_class('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__": "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__": "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