Overview

Deinterlace processor family.

Progressive re-encode of interlaced video via pluggable backends.

Exported Classes

• DeinterlaceProcessor
• DeinterlaceConfig
• DeinterlaceProcessConfig
• FFmpegDeinterlaceProcessor
• FFmpegDeinterlaceConfig
• FFmpegDeinterlaceProcessConfig
• GstDeinterlaceProcessor
• GstDeinterlaceConfig
• GstDeinterlaceProcessConfig

DeinterlaceConfig

Bases: BaseModel

Backend-agnostic stable configuration for deinterlace processors.

Only knobs that apply across FFmpeg / GStreamer (and future engines) belong here. Engine-specific fields (yadif mode, x264 CRF, GST element props, …) live on backend subclasses that inherit this model.

Attributes:

Name	Type	Description
strip_audio	bool	Drop audio when producing progressive output. Defaults to True.

DeinterlaceProcessConfig

Bases: ProcessorProcessConfig

Backend-agnostic per-invocation overrides for deinterlace.

None fields fall back to the stable constructor config. Backend process-config models inherit this class and add engine-specific overrides.

DeinterlaceProcessor()

Bases: BackendSelectableProcessor[Attachment, Attachment], ABC

Family base for deinterlacing video attachments.

Why use this base class?

• Portability: Swap FFmpeg vs GStreamer without changing call sites.
• I/O boundary: Deinterlace is media transform I/O, not a segmenter algorithm.
• Tunable: Shared knobs on DeinterlaceConfig; backends extend for engine-specific settings via inheritance.

Usage

from gllm_multimodal.media_toolkit.processor.deinterlace_processor import (
    DeinterlaceConfig,
    DeinterlaceProcessor,
)

processor = DeinterlaceProcessor.build(
    backend="ffmpeg",
    config=DeinterlaceConfig(strip_audio=True),
)
progressive = await processor.process(video_attachment)

is_interlaced(attachment) staticmethod

Return whether ffprobe reports an interlaced field order for an attachment.

Writes attachment.data to a temporary file, probes field_order, then cleans up. Returns False when ffprobe is unavailable, the probe fails, or the field order is progressive or unknown (fail-open: unknown is treated as progressive so callers skip the deinterlace pass; a warning is logged whenever the probe cannot determine interlacing).

Callers that need fail-safe behavior (deinterlace when unknown) should check ffprobe availability separately instead of relying on this gate.

Parameters:

Name	Type	Description	Default
attachment	Attachment	Video attachment to probe.	required

Returns:

Name	Type	Description
bool	bool	True when field_order is one of tt, bb, tb, or bt.

is_interlaced_path(video_path) staticmethod

Return whether ffprobe reports an interlaced field order for a local path.

Public alias of is_interlaced_path kept on the family base so frame-extraction and other families do not reach into a private member.

Parameters:

Name	Type	Description	Default
video_path	str	Path to a local video file.	required

Returns:

Name	Type	Description
bool	bool	True when field_order is interlaced.

FFmpegDeinterlaceConfig

Bases: DeinterlaceConfig

FFmpeg-specific stable config (inherits shared DeinterlaceConfig).

Attributes:

Name	Type	Description
yadif_mode	int	Yadif mode (0=send_frame, 1=send_field, 2=send_frame_nospatial, 3=send_field_nospatial). Defaults to 0.
yadif_parity	int	Field parity (-1=auto, 0=tff, 1=bff). Defaults to -1.
yadif_deint	int	Deinterlace all frames (0) or only flagged (1). Defaults to 0.
video_codec	str	Video encoder name. Defaults to libx264.
preset	str	x264 preset. Defaults to ultrafast.
crf	int	Constant rate factor (0–51). Defaults to 23.
filter_override	str | None	Full -vf string; when set, yadif_* fields are ignored. Defaults to None.

validate_non_empty(value) classmethod

Reject blank codec/preset strings.

Parameters:

Name	Type	Description	Default
value	str	Candidate string.	required

Returns:

Name	Type	Description
str	str	Validated string.

Raises:

Type	Description
ValueError	If value is blank.

yadif_filter()

Build the -vf filter string.

Returns:

Name	Type	Description
str	str	Filter graph for FFmpeg -vf.

FFmpegDeinterlaceProcessConfig

Bases: DeinterlaceProcessConfig

Per-invocation FFmpeg overrides (inherits shared DeinterlaceProcessConfig).

Any field left as None falls back to the stable constructor config.

FFmpegDeinterlaceProcessor(config=None)

Bases: BaseFFmpegProcessor, DeinterlaceProcessor

Deinterlace video with FFmpeg yadif.

Attributes:

Name	Type	Description
config	FFmpegDeinterlaceConfig	Stable constructor configuration.

Initialize the FFmpeg deinterlace processor.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | DeinterlaceConfig | FFmpegDeinterlaceConfig | None	Shared DeinterlaceConfig, FFmpeg-specific config, or dict. Shared-only configs are promoted with FFmpeg defaults for engine fields. Defaults to None.	None

config_model() classmethod

Return the stable configuration model.

deinterlace_video(video_path, output_path=None, *, params=None)

Deinterlace a video path with FFmpeg yadif into a progressive file.

Parameters:

Name	Type	Description	Default
video_path	str	Source video path.	required
output_path	str | None	Destination path. When None, a temporary .mp4 path is created. Defaults to None.	None
params	FFmpegDeinterlaceConfig | None	Effective options for this call. Defaults to self.config.	None

Returns:

Name	Type	Description
str	str	Path to the progressive output video.

Raises:

Type	Description
FileNotFoundError	If ffmpeg is not on PATH.
RuntimeError	If FFmpeg deinterlace fails.

process(attachment, **kwargs) async

Deinterlace one video attachment.

Parameters:

Name	Type	Description	Default
attachment	Attachment	Input interlaced (or progressive) video.	required
**kwargs	Any	May include process_config overrides.	{}

Returns:

Name	Type	Description
Attachment	Attachment	Progressive video attachment.

process_config_model() classmethod

Return the per-invocation configuration model.

GstDeinterlaceConfig

Bases: DeinterlaceConfig, GstBaseConfig

GStreamer-specific stable config (inherits shared DeinterlaceConfig).

Yadif / encode defaults mirror FFmpegDeinterlaceConfig so both backends produce comparable progressive output.

Attributes:

Name	Type	Description
yadif_mode	int	Yadif mode (0–3). Defaults to 0.
yadif_parity	int	Field parity (-1=auto, 0=tff, 1=bff). Defaults to -1.
yadif_deint	int	Deinterlace all frames (0) or flagged-only (1). Defaults to 0.
crf	int	Quantizer passed to the video encoder (CRF analogue). Defaults to 23.
preset	str	x264 speed preset name. Defaults to ultrafast.
video_encoder	str | None	Inherited from GstBaseConfig; None auto-selects the first available encoder (x264enc preferred), matching sibling Gst backends.

validate_preset(value) classmethod

Reject blank preset strings.

Parameters:

Name	Type	Description	Default
value	str	Candidate preset name.	required

Returns:

Name	Type	Description
str	str	Validated preset name.

Raises:

Type	Description
ValueError	If value is blank.

yadif_filter()

Return an FFmpeg-style yadif filter label for metadata parity.

Returns:

Name	Type	Description
str	str	Filter description aligned with the FFmpeg backend.

GstDeinterlaceProcessConfig

Bases: DeinterlaceProcessConfig

Per-invocation GStreamer overrides (inherits shared DeinterlaceProcessConfig).

GstDeinterlaceProcessor(config=None)

Bases: BaseGstreamerProcessor, DeinterlaceProcessor

Deinterlace video with GStreamer yadif + x264enc.

Pipeline topology::

filesrc → decodebin → queue → videoconvert → yadif → videoconvert
    → x264enc → mp4mux → filesink

Audio pads are dropped when strip_audio is True.

Initialize the GStreamer deinterlace processor.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | DeinterlaceConfig | GstDeinterlaceConfig | None	Shared or GStreamer-specific config. Defaults to None.	None

config_model() classmethod

Return the stable configuration model.

process(attachment, **kwargs) async

Deinterlace one video attachment.

Parameters:

Name	Type	Description	Default
attachment	Attachment	Input interlaced (or progressive) video.	required
**kwargs	Any	May include process_config overrides.	{}

Returns:

Name	Type	Description
Attachment	Attachment	Progressive video attachment.

process_config_model() classmethod

Return the per-invocation configuration model.

is_interlaced_path(video_path)

Return whether ffprobe reports an interlaced field order for a local path.

General-purpose fail-open ffprobe helper shared by the deinterlace and frame-extraction families. Prefer DeinterlaceProcessor.is_interlaced for Attachment call sites.

Fail-open: returns False (with a warning) when ffprobe is missing or the probe fails, so callers skip deinterlacing rather than raising.

Parameters:

Name	Type	Description	Default
video_path	str	Path to a local video file.	required

Returns:

Name	Type	Description
bool	bool	True when field_order is one of tt, bb, tb, or bt.