Skip to content

Backend Selectable Processor

Backend registry mixin for processor families.

This module provides BackendSelectableProcessor, the abstract base class for processor families that support multiple backend implementations (e.g. GStreamer, FFmpeg).

How it works

Each processor family owns its backend registry. Concrete backend classes are auto-registered via __init_subclass__ by declaring:

  • BACKEND: backend key, e.g. gstreamer or ffmpeg
  • IS_DEFAULT: whether this backend is the family default

Minimal contributor pattern

# In base.py — family base class
class ImageTilingProcessor(BackendSelectableProcessor):
    ...

# In pil_backend.py — concrete backend
class PilImageTilingProcessor(ImageTilingProcessor):
    BACKEND = "pil"
    IS_DEFAULT = True

# In cv2_backend.py — another concrete backend
class Cv2ImageTilingProcessor(ImageTilingProcessor):
    BACKEND = "cv2"

Usage

# Build by family name + backend
processor = MediaToolkit.build("ImageTilingProcessor", backend="pil")

# Or use the default backend
processor = MediaToolkit.build("ImageTilingProcessor")

BackendSelectableProcessor()

Bases: MediaToolkit[T_in, T_out], ABC

Abstract base for a processor family with pluggable backends.

Each family owns its backend registry. Concrete backend classes are auto-registered via __init_subclass__ by declaring:

  • BACKEND: backend key, e.g. gstreamer or ffmpeg
  • IS_DEFAULT: whether this backend is the family default
Why this exists

It lets callers construct by stable family class name while deferring runtime selection of backend implementation.

Minimal contributor pattern

class ImageTilingProcessor(BackendSelectableProcessor): ... in base.py, then concrete backends such as class PilImageTilingProcessor(ImageTilingProcessor): BACKEND = "pil" and class Cv2ImageTilingProcessor(ImageTilingProcessor): BACKEND = "cv2".

Then callers can use

MediaToolkit.build("ImageTilingProcessor", backend="pil").

__init_subclass__(**kwargs)

Automatically register concrete backend implementations.

Family base classes reset their own registry; abstract intermediate classes are ignored; concrete classes must declare BACKEND.

build(backend=None, **kwargs) classmethod

Build a backend implementation for this processor family.

Parameters:

Name Type Description Default
backend str | None

Backend key. Uses the family default when omitted.

 None
**kwargs Any

Constructor kwargs forwarded to the backend class.

 {}

Returns:

Name Type Description
BackendSelectableProcessor BackendSelectableProcessor

Instantiated backend processor.

Raises:

Type Description
ValueError

If the backend is unknown or no default is configured.
Example

For a family class AudioExtractionProcessor, AudioExtractionProcessor.build(backend="gstreamer") returns the registered GStreamer implementation class instance.

build_from_registry(backend=None, **kwargs) classmethod

Build a family backend or instantiate a concrete backend class.

Parameters:

Name Type Description Default
backend str | MediaBackend | None

Backend key for family resolution. Defaults to None.

 None
**kwargs Any

Constructor kwargs forwarded to the backend class.

 {}

Returns:

Name Type Description
BackendSelectableProcessor BackendSelectableProcessor

Instantiated processor.

is_family_base(processor_cls) classmethod

Return whether processor_cls is a family abstract base.

Parameters:

Name Type Description Default
processor_cls type[BackendSelectableProcessor]

Candidate processor class.

 required

Returns:

Name Type Description
bool bool

True when the class directly subclasses BackendSelectableProcessor.

list_available_backends() classmethod

Return registered backend keys for backend-selectable family bases.

Returns:

Type Description
list[str]

list[str]: Backend keys available for build. Empty for concrete backend implementations and non-family classes.

list_backends() classmethod

Return registered backend keys for this processor family.

Returns:

Type Description
list[str]

list[str]: Backend keys available for build.