Media Toolkit Builder

Convenience constructors for media toolkit components.

This module is the main user-facing entry point for building media toolkit components from declarative specs or a single class name. All construction delegates to MediaToolkit.build, which dispatches to each registered class's build_from_registry hook (backend-selectable families resolve a concrete backend; composites store backend for nested processor resolution).

When to use this module

Application code needs a simple API for toolkit construction.
Tests want deterministic class-name-based construction.
Contributors add new toolkit families registered under MediaToolkit.

Quick start

View all available components

To see the full list of available toolkit components, inspect MediaToolkit.registry or refer to the subclasses of MediaToolkit:

from gllm_multimodal.builder.media_toolkit_builder import build_media_toolkit
from gllm_inference.schema import Attachment

# Build and run a single processor
processor = build_media_toolkit("AudioExtractionProcessor", backend="gstreamer")
video = Attachment.from_path("clip.mp4")
audio = await processor.process(video)  # returns Attachment (audio)

`build_media_toolkit(class_name, backend=None, processor_backends=None, **kwargs)`

Build one media toolkit component by registered class name.

This is the primary factory function for creating media toolkit components. It resolves the class name against the MediaToolkit registry and instantiates the component with the provided arguments.

For composite components (segmenters, keyframe extractors), you can additionally supply processor_backends to pre-configure per-family backend overrides without needing to call MediaToolkit.set_processor_backend manually afterwards.

Parameters:

Name	Type	Description	Default
`class_name`	`str`	Registered class name, e.g. `"AudioExtractionProcessor"` or `"FixedDurationSegmenter"`.	required
`backend`	`MediaBackend \| str \| None`	Backend selector. `None` delegates to the family's registered default backend. Pass an explicit key (e.g. `"gstreamer"` or `"ffmpeg"`) to override. Defaults to `None`.	`None`
`processor_backends`	`dict[str, str] \| None`	Per-family backend overrides applied after construction for composite components, e.g. `{"VideoClipProcessor": "ffmpeg"}`. Silently ignored for non-composites. Defaults to `None`.	`None`
`**kwargs`	`Any`	Constructor keyword arguments forwarded to the component.	`{}`

Returns:

Name	Type	Description
`MediaToolkit`	`MediaToolkit`	An instance of the requested MediaToolkit component.

Raises:

Type	Description
`ValueError`	If `class_name` or `backend` lookup fails.

Examples:

Default backend

from gllm_multimodal.builder.media_toolkit_builder import build_media_toolkit
from gllm_inference.schema import Attachment

processor = build_media_toolkit("AudioExtractionProcessor")
audio = await processor.process(Attachment.from_path("clip.mp4"))

Explicit backend + process result

processor = build_media_toolkit(
    "FixedDurationSegmenter",
    backend="gstreamer",
    segment_durations=[2.0],
)
clips = await processor.process(Attachment.from_path("video.mp4"))
# clips is a list[Attachment]

`build_media_toolkit_bulk(specs)`

Build media toolkit components from declarative specs.

This function accepts a list of specification dictionaries and builds each component using build_media_toolkit. All specs are validated against the backend registry before any component is instantiated, so errors are reported immediately.

Spec format

Each spec dictionary must have a "name" key and optionally "kwargs" and "processor_backends".

Use case: loading a list of component specs from a YAML or JSON configuration file, where all components must be validated before any is instantiated (fail-fast, all errors reported at once).

[
    {"name": "AudioExtractionProcessor", "kwargs": {"backend": "gstreamer"}},
    {"name": "FixedDurationSegmenter", "kwargs": {
        "backend": "gstreamer",
        "segment_durations": [2.0]
    }}
]

For composite components you may additionally supply "processor_backends" to pre-configure per-family backend overrides:

{
    "name": "FixedDurationSegmenter",
    "kwargs": {"backend": "gstreamer", "segment_durations": [2.0]},
    "processor_backends": {"VideoClipProcessor": "ffmpeg"}
}

Notes

name must be a registered class name (family base, concrete, or composite).
kwargs.backend is consumed by the factory and not passed as a constructor argument to leaf backend classes. For composites it is stored for nested processor resolution.
processor_backends is silently ignored for non-composite components.