diffusers-workflow 0.4.0__py3-none-any.whl

dw/tasks/task.py

@@ -0,0 +1,920 @@
+import logging
+from typing import Callable, Dict
+
+from .. import resolve_device
+from ..events import emit_log
+from .qr_code import get_qrcode_image
+from .image_utils import process_image
+from .video_utils import process_video
+from .gather import gather_images, gather_inputs, gather_videos
+from .format_messages import (
+    format_chat_message,
+    batch_decode_post_process,
+    get_dict_value,
+)
+
+# The model-backed handlers (upscale, restore_faces, segment, interpolate_frames,
+# image_to_text, text_generation, diffusion_upscale) are imported inside their
+# handlers - at module scope their transformers/model imports add seconds to
+# every startup for workflows that never run those tasks
+
+logger = logging.getLogger("dw")
+
+
+# Command registry: maps command names to handler functions
+_COMMAND_REGISTRY: Dict[str, Callable] = {}
+
+# What each command's arguments actually are. The handlers forward
+# **arguments into an implementation function, so that function's signature
+# is the command's argument schema - registering its dotted path here (a
+# string, to preserve the lazy-import discipline) lets the introspection
+# layer read the same signature the runtime calls. 'provided' names the
+# parameters the dispatch supplies itself, which are not workflow arguments.
+_COMMAND_INFO: Dict[str, dict] = {}
+
+
+def register_command(
+    command_name: str,
+    implementation=None,
+    provided=(),
+    consumes_device=False,
+    returns="artifact",
+    summary=None,
+    parameter_descriptions=None,
+):
+    """
+    Decorator to register a command handler function.
+
+    Args:
+        command_name: The command name to register
+        implementation: Dotted path to the function whose signature defines
+            the command's arguments (None for a command that consumes a
+            free-form dict)
+        provided: Parameter names the dispatch supplies itself
+        consumes_device: True for a handler that calls task.device_for(arguments)
+            itself, to pick the accelerator a model-backed task runs on. False
+            (the default) is for a task that runs no model and forwards
+            arguments straight to its implementation - device is introspected
+            as a universal, always-safe-to-pass argument (dw/introspection.py),
+            so a non-consuming handler must drop it itself rather than let it
+            reach the implementation as an unexpected keyword argument (#185).
+            Some commands (e.g. gather_inputs) receive a non-dict argument
+            value, which never carries a device to drop
+        returns: "artifact" (the default - an image/video/audio/frames object
+            `Result.save` knows how to write) or "scalar" for a command whose
+            return value is a bare number with no file to save (`judge`). A
+            `result` block on a "scalar" command is refused in
+            `validation_errors` (dw/scalar_result_validation.py, #212) rather
+            than reaching `save_artifact` at run time, where a float has
+            nothing left identifying which command produced it
+            - or "json" for a command answering a JSON-safe dict of
+            measurements (the assessment probes, `dw/tasks/assess.py`): its
+            `result` may only be `application/json`, since any other content
+            type would explode the dict key by key into files
+        summary: Overrides the command's `get_task` summary, which otherwise
+            reads the implementation function's docstring. For a command
+            whose handler dispatches its implementation per video frame
+            (`_per_frame`), that docstring describes the single-frame
+            function rather than the command a caller invokes - same reason
+            `_VIDEO_PROCESSOR_INFO` overrides `get_first_frame`/
+            `get_last_frame` (#366, #383)
+        parameter_descriptions: Overrides one or more of the implementation's
+            per-parameter `get_task` descriptions by name, for the same
+            single-frame-vs-command reason as `summary`
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if consumes_device:
+            handler = func
+        else:
+
+            def handler(task, arguments, previous_pipelines, _func=func):
+                if isinstance(arguments, dict):
+                    arguments.pop("device", None)
+                return _func(task, arguments, previous_pipelines)
+
+        _COMMAND_REGISTRY[command_name] = handler
+        info = {
+            "kind": "command",
+            "implementation": implementation,
+            "provided": tuple(provided),
+            "returns": returns,
+        }
+        if summary:
+            info["summary"] = summary
+        if parameter_descriptions:
+            info["parameter_descriptions"] = dict(parameter_descriptions)
+        _COMMAND_INFO[command_name] = info
+        logger.debug(f"Registered command handler: {command_name}")
+        return func
+
+    return decorator
+
+
+def task_command_info(command_name):
+    """Where a task command's argument schema lives: a dict with 'kind'
+    ('command', 'image_processor' or 'video_processor'), 'implementation'
+    (dotted path or None for free-form), 'provided', and 'returns'
+    ('artifact', the default, or 'scalar' for a bare-number command like
+    `judge` - missing entirely for an image/video processor, which is
+    always artifact-shaped). Raises ValueError for a name that is not a
+    task command at all."""
+    info = _COMMAND_INFO.get(command_name)
+    if info is not None:
+        return info
+    if command_name in _VIDEO_PROCESSOR_INFO:
+        return _VIDEO_PROCESSOR_INFO[command_name]
+    from .image_utils import available_processors
+
+    if command_name in available_processors():
+        return {"kind": "image_processor", "implementation": None, "provided": ()}
+    raise ValueError(f"Unknown task command: '{command_name}'")
+
+
+# Command handler functions
+@register_command("qr_code", implementation="dw.tasks.qr_code.get_qrcode_image")
+def _handle_qr_code(task, arguments, previous_pipelines):
+    """Generate QR code image"""
+    logger.debug("Generating QR code")
+    return get_qrcode_image(**arguments)
+
+
+@register_command("gather_images", implementation="dw.tasks.gather.gather_images")
+def _handle_gather_images(task, arguments, previous_pipelines):
+    """Gather multiple images"""
+    logger.debug("Gathering images")
+    return gather_images(**arguments)
+
+
+@register_command("gather_videos", implementation="dw.tasks.gather.gather_videos")
+def _handle_gather_videos(task, arguments, previous_pipelines):
+    """Gather multiple videos"""
+    logger.debug("Gathering videos")
+    return gather_videos(**arguments)
+
+
+# gather_inputs passes its whole dict through unchanged - free-form by design
+@register_command("gather_inputs")
+def _handle_gather_inputs(task, arguments, previous_pipelines):
+    """Gather inputs from various sources"""
+    logger.debug("Gathering inputs")
+    return gather_inputs(arguments)
+
+
+@register_command(
+    "concat_videos", implementation="dw.tasks.concat_videos.concat_videos"
+)
+def _handle_concat_videos(task, arguments, previous_pipelines):
+    """Concatenate videos - and the audio generated with them - into one"""
+    logger.debug("Concatenating videos")
+    from .concat_videos import concat_videos
+
+    return concat_videos(**arguments)
+
+
+@register_command(
+    "dissolve_videos", implementation="dw.tasks.dissolve_videos.dissolve_videos"
+)
+def _handle_dissolve_videos(task, arguments, previous_pipelines):
+    """Join videos with cross-dissolves, fading the whole from and to a colour"""
+    logger.debug("Dissolving videos")
+    from .dissolve_videos import dissolve_videos
+
+    return dissolve_videos(**arguments)
+
+
+@register_command("fade_audio", implementation="dw.tasks.audio_utils.fade_audio")
+def _handle_fade_audio(task, arguments, previous_pipelines):
+    """Fade an audio track in from silence and out to it"""
+    logger.debug("Fading audio")
+    from .audio_utils import fade_audio
+
+    return fade_audio(**arguments)
+
+
+@register_command(
+    "normalize_audio", implementation="dw.tasks.audio_utils.normalize_audio"
+)
+def _handle_normalize_audio(task, arguments, previous_pipelines):
+    """Scale an audio track so its peak sits at a given level"""
+    logger.debug("Normalizing audio")
+    from .audio_utils import normalize_audio
+
+    return normalize_audio(**arguments)
+
+
+@register_command("slice_audio", implementation="dw.tasks.audio_utils.slice_audio")
+def _handle_slice_audio(task, arguments, previous_pipelines):
+    """Cut a time- or frame-aligned slice out of an audio track"""
+    logger.debug("Slicing audio")
+    from .audio_utils import slice_audio
+
+    return slice_audio(**arguments)
+
+
+@register_command("gain_audio", implementation="dw.tasks.audio_utils.gain_audio")
+def _handle_gain_audio(task, arguments, previous_pipelines):
+    """Apply a gain to a time- or frame-aligned region of an audio track"""
+    logger.debug("Gaining audio region")
+    from .audio_utils import gain_audio
+
+    return gain_audio(**arguments)
+
+
+@register_command(
+    "resample_audio", implementation="dw.tasks.audio_utils.resample_audio"
+)
+def _handle_resample_audio(task, arguments, previous_pipelines):
+    """Resample an audio track to a different sample rate"""
+    logger.debug("Resampling audio")
+    from .audio_utils import resample_audio
+
+    return resample_audio(**arguments)
+
+
+@register_command("video_frames", implementation="dw.tasks.video_utils.frames_as_array")
+def _handle_video_frames(task, arguments, previous_pipelines):
+    """The frames of a generated video, as one array a later step can condition on"""
+    logger.debug("Extracting video frames")
+    from .video_utils import frames_as_array
+
+    return frames_as_array(**arguments)
+
+
+@register_command("loop_frames", implementation="dw.tasks.video_utils.loop_frames")
+def _handle_loop_frames(task, arguments, previous_pipelines):
+    """Repeat a still or a short clip into a run of a given length"""
+    logger.debug("Looping frames")
+    from .video_utils import loop_frames
+
+    return loop_frames(**arguments)
+
+
+@register_command("frame_grid", implementation="dw.tasks.video_utils.frame_grid")
+def _handle_frame_grid(task, arguments, previous_pipelines):
+    """Tile evenly sampled frames of a video into one contact-sheet image"""
+    logger.debug("Building frame grid")
+    from .video_utils import frame_grid
+
+    return frame_grid(**arguments)
+
+
+@register_command("pair_audio", implementation="dw.tasks.pair_audio.pair_audio")
+def _handle_pair_audio(task, arguments, previous_pipelines):
+    """Pair a video's frames with an audio track generated beside them"""
+    logger.debug("Pairing audio with video")
+    from .pair_audio import pair_audio
+
+    return pair_audio(**arguments)
+
+
+@register_command(
+    "crossfade_audio", implementation="dw.tasks.audio_utils.crossfade_audio"
+)
+def _handle_crossfade_audio(task, arguments, previous_pipelines):
+    """Join audio tracks with an equal-power crossfade"""
+    logger.debug("Crossfading audio")
+    from .audio_utils import crossfade_audio
+
+    return crossfade_audio(**arguments)
+
+
+@register_command("loop_audio", implementation="dw.tasks.audio_utils.loop_audio")
+def _handle_loop_audio(task, arguments, previous_pipelines):
+    """Loop a short recording into a bed of a given length"""
+    logger.debug("Looping audio")
+    from .audio_utils import loop_audio
+
+    return loop_audio(**arguments)
+
+
+@register_command(
+    "stabilize_video", implementation="dw.tasks.stabilize.stabilize_video"
+)
+def _handle_stabilize_video(task, arguments, previous_pipelines):
+    """Remove a generated clip's accumulated framing drift"""
+    logger.debug("Stabilizing video")
+    from .stabilize import stabilize_video
+
+    return stabilize_video(**arguments)
+
+
+@register_command("mix_audio", implementation="dw.tasks.audio_utils.mix_audio")
+def _handle_mix_audio(task, arguments, previous_pipelines):
+    """Layer audio tracks on top of one another, rather than end to end"""
+    logger.debug("Mixing audio")
+    from .audio_utils import mix_audio
+
+    return mix_audio(**arguments)
+
+
+@register_command(
+    "compress_audio", implementation="dw.tasks.audio_utils.compress_audio"
+)
+def _handle_compress_audio(task, arguments, previous_pipelines):
+    """Shape a track's dynamics with a compressor, limiter or gate"""
+    logger.debug("Compressing audio")
+    from .audio_utils import compress_audio
+
+    return compress_audio(**arguments)
+
+
+@register_command("filter_audio", implementation="dw.tasks.audio_utils.filter_audio")
+def _handle_filter_audio(task, arguments, previous_pipelines):
+    """Run a track through a single lowpass/highpass/bandpass/notch filter"""
+    logger.debug("Filtering audio")
+    from .audio_utils import filter_audio
+
+    return filter_audio(**arguments)
+
+
+@register_command("analyze_audio", implementation="dw.tasks.audio_utils.analyze_audio")
+def _handle_analyze_audio(task, arguments, previous_pipelines):
+    """Measure a track's levels and spectral balance without changing it"""
+    logger.debug("Analyzing audio")
+    from .audio_utils import analyze_audio
+
+    return analyze_audio(**arguments)
+
+
+@register_command(
+    "analyze_shots", implementation="dw.tasks.assess.analyze_shots", returns="json"
+)
+def _handle_analyze_shots(task, arguments, previous_pipelines):
+    """Measure each shot of a cut's soundtrack and how far apart they sit"""
+    from .assess import analyze_shots
+
+    return analyze_shots(**arguments)
+
+
+@register_command(
+    "analyze_seams", implementation="dw.tasks.assess.analyze_seams", returns="json"
+)
+def _handle_analyze_seams(task, arguments, previous_pipelines):
+    """Measure every seam of a cut - level step, hole, click, frame jump"""
+    from .assess import analyze_seams
+
+    return analyze_seams(**arguments)
+
+
+@register_command(
+    "analyze_sync_drift",
+    implementation="dw.tasks.assess.analyze_sync_drift",
+    returns="json",
+)
+def _handle_analyze_sync_drift(task, arguments, previous_pipelines):
+    """Measure how far a cut's soundtrack sits from its picture"""
+    from .assess import analyze_sync_drift
+
+    return analyze_sync_drift(**arguments)
+
+
+@register_command("compose_text", implementation="dw.tasks.compose_text.compose_text")
+def _handle_compose_text(task, arguments, previous_pipelines):
+    """Join parts written once into one block of text"""
+    logger.debug("Composing text")
+    from .compose_text import compose_text
+
+    return compose_text(**arguments)
+
+
+@register_command("select", implementation="dw.tasks.select.select")
+def _handle_select(task, arguments, previous_pipelines):
+    """Reduce a list of candidates to one by a deterministic rule"""
+    logger.debug("Selecting")
+    from .select import select
+
+    return select(**arguments)
+
+
+@register_command(
+    "format_chat_message", implementation="dw.tasks.format_messages.format_chat_message"
+)
+def _handle_format_chat_message(task, arguments, previous_pipelines):
+    """Format chat message for LLM input"""
+    logger.debug("Formatting chat message")
+    return format_chat_message(**arguments)
+
+
+@register_command(
+    "get_dict_value", implementation="dw.tasks.format_messages.get_dict_value"
+)
+def _handle_get_dict_value(task, arguments, previous_pipelines):
+    """Extract value from dictionary"""
+    logger.debug("Getting dictionary value")
+    return get_dict_value(**arguments)
+
+
+def _per_frame(image, process):
+    """Run an image command over a video, frame by frame.
+
+    A video bound to an image argument - an AudioVideo from a generation,
+    concat or dissolve step, or a frame array from video_frames - is processed
+    one frame at a time and comes back as one video artifact, its soundtrack
+    carried through untouched. A single image is processed as itself.
+    """
+    from ..result import AudioVideo
+    from ..shots import carried_shots
+    from .video_utils import frames_as_pil_list, is_video
+
+    if not is_video(image):
+        return process(image)
+    frames = [process(frame) for frame in frames_as_pil_list(image)]
+    audio = getattr(image, "audio", None)
+    sample_rate = getattr(image, "sample_rate", None)
+    # One frame out per frame in, so the shot boundaries carry through too
+    return AudioVideo(
+        frames,
+        audio,
+        sample_rate,
+        fps=getattr(image, "fps", None),
+        shots=carried_shots(image),
+    )
+
+
+@register_command(
+    "upscale", implementation="dw.tasks.upscale.upscale_image", consumes_device=True
+)
+def _handle_upscale(task, arguments, previous_pipelines):
+    """Upscale an image using a spandrel-compatible super-resolution model"""
+    logger.debug("Upscaling image")
+    image = arguments.pop("image")
+    model_name = arguments.pop("model_name")
+    from .upscale import upscale_image
+
+    device = task.device_for(arguments)
+    return _per_frame(
+        image,
+        lambda frame: upscale_image(frame, model_name, device=device, **arguments),
+    )
+
+
+@register_command(
+    "diffusion_upscale",
+    implementation="dw.tasks.diffusion_upscale.diffusion_upscale",
+    consumes_device=True,
+)
+def _handle_diffusion_upscale(task, arguments, previous_pipelines):
+    """Upscale an image using a diffusion-based upscale pipeline"""
+    logger.debug("Diffusion upscaling image")
+    image = arguments.pop("image")
+    from .diffusion_upscale import diffusion_upscale
+
+    device = task.device_for(arguments)
+    return _per_frame(
+        image, lambda frame: diffusion_upscale(frame, device=device, **arguments)
+    )
+
+
+@register_command(
+    "restore_faces",
+    implementation="dw.tasks.restore_faces.restore_faces",
+    consumes_device=True,
+)
+def _handle_restore_faces(task, arguments, previous_pipelines):
+    """Restore faces in an image using a spandrel-compatible face restoration model"""
+    logger.debug("Restoring faces")
+    image = arguments.pop("image")
+    model_name = arguments.pop("model_name")
+    from .restore_faces import restore_faces
+
+    device = task.device_for(arguments)
+    return _per_frame(
+        image,
+        lambda frame: restore_faces(frame, model_name, device=device, **arguments),
+    )
+
+
+@register_command(
+    "grade",
+    implementation="dw.tasks.grade.grade_image",
+    summary=(
+        "Adjust exposure, contrast, saturation and white balance of an "
+        "image or a video."
+    ),
+    parameter_descriptions={
+        "media": (
+            "Image or video to grade. An image is a PIL Image; a video is a "
+            "file path or an asset:/output: reference, read with its audio "
+            "and graded frame by frame, keeping its frame rate and audio "
+            "unchanged."
+        ),
+    },
+)
+def _handle_grade(task, arguments, previous_pipelines):
+    """Adjust exposure, contrast, saturation and white balance of an image or a video"""
+    logger.debug("Grading media")
+    media = arguments.pop("media")
+    from .grade import grade_image
+
+    if isinstance(media, str):
+        import os
+
+        from ..security import ALLOWED_VIDEO_EXTENSIONS
+        from .video_utils import load_audio_video
+
+        if os.path.splitext(media)[1].lower() in ALLOWED_VIDEO_EXTENSIONS:
+            media = load_audio_video(media)
+        else:
+            from ..arguments import fetch_image
+
+            media = fetch_image(media)
+
+    defaults = {
+        "exposure": 0.0,
+        "contrast": 1.0,
+        "saturation": 1.0,
+        "temperature": 0.0,
+        "tint": 0.0,
+    }
+    applied = {
+        name: arguments.get(name, default)
+        for name, default in defaults.items()
+        if arguments.get(name, default) != default
+    }
+    emit_log(
+        f"grade: applied {applied}"
+        if applied
+        else "grade: no adjustment (all identity)",
+        command="grade",
+        **applied,
+    )
+    return _per_frame(media, lambda frame: grade_image(frame, **arguments))
+
+
+@register_command(
+    "segment", implementation="dw.tasks.segment.segment_image", consumes_device=True
+)
+def _handle_segment(task, arguments, previous_pipelines):
+    """Segment objects in an image using text prompt"""
+    logger.debug("Segmenting image")
+    image = arguments.pop("image")
+    prompt = arguments.pop("prompt")
+    from .segment import segment_image
+
+    device = task.device_for(arguments)
+    return _per_frame(
+        image, lambda frame: segment_image(frame, prompt, device=device, **arguments)
+    )
+
+
+@register_command(
+    "interpolate_frames",
+    implementation="dw.tasks.interpolate_frames.interpolate_frames",
+    consumes_device=True,
+)
+def _handle_interpolate_frames(task, arguments, previous_pipelines):
+    """Interpolate video frames to increase frame rate"""
+    logger.debug("Interpolating frames")
+    video = arguments.pop("video")
+    from .interpolate_frames import interpolate_frames
+
+    return interpolate_frames(video, device=task.device_for(arguments), **arguments)
+
+
+@register_command(
+    "image_to_text",
+    implementation="dw.tasks.image_to_text.image_to_text",
+    consumes_device=True,
+)
+def _handle_image_to_text(task, arguments, previous_pipelines):
+    """Generate text caption from an image"""
+    logger.debug("Captioning image")
+    image = arguments.pop("image")
+    from .image_to_text import image_to_text
+
+    return image_to_text(image, device=task.device_for(arguments), **arguments)
+
+
+@register_command(
+    "judge",
+    implementation="dw.tasks.judge.judge",
+    consumes_device=True,
+    returns="scalar",
+)
+def _handle_judge(task, arguments, previous_pipelines):
+    """Score an image against a rubric with a vision-language model"""
+    logger.debug("Judging")
+    image = arguments.pop("image")
+    from .judge import judge
+
+    return judge(image, device=task.device_for(arguments), **arguments)
+
+
+@register_command(
+    "transcribe_audio",
+    implementation="dw.tasks.audio_transcription.transcribe_audio",
+    consumes_device=True,
+)
+def _handle_transcribe_audio(task, arguments, previous_pipelines):
+    """Transcribe spoken audio to text"""
+    logger.debug("Transcribing audio")
+    audio = arguments.pop("audio")
+    from .audio_transcription import transcribe_audio
+
+    return transcribe_audio(audio, device=task.device_for(arguments), **arguments)
+
+
+@register_command(
+    "text_generation",
+    implementation="dw.tasks.text_generation.generate_text",
+    consumes_device=True,
+)
+def _handle_text_generation(task, arguments, previous_pipelines):
+    """Generate text from a prompt using a local LLM"""
+    logger.debug("Generating text")
+    prompt = arguments.pop("prompt")
+    from .text_generation import generate_text
+
+    return generate_text(prompt, device=task.device_for(arguments), **arguments)
+
+
+@register_command(
+    "generate_speech",
+    implementation="dw.tasks.speech_generation.generate_speech",
+    consumes_device=True,
+)
+def _handle_speech_generation(task, arguments, previous_pipelines):
+    """Speak a line of text with a local text-to-speech model"""
+    logger.debug("Generating speech")
+    if ("text" in arguments) == ("messages" in arguments):
+        raise ValueError(
+            "generate_speech needs exactly one of 'text' (the line to speak) "
+            "or 'messages' (chat-templated input for a model such as VibeVoice)"
+        )
+    text = arguments.pop("text", None)
+    from .speech_generation import generate_speech
+
+    return generate_speech(
+        text,
+        device=task.device_for(arguments),
+        seed=task.seed_for(arguments),
+        **arguments,
+    )
+
+
+@register_command(
+    "extract_sections", implementation="dw.tasks.text_sections.extract_sections"
+)
+def _handle_extract_sections(task, arguments, previous_pipelines):
+    """Reduce generated text to a known set of labelled sections"""
+    logger.debug("Extracting sections")
+    from .text_sections import extract_sections
+
+    return extract_sections(**arguments)
+
+
+@register_command(
+    "batch_decode_post_process",
+    implementation="dw.tasks.format_messages.batch_decode_post_process",
+    provided=("processor",),
+)
+def _handle_batch_decode(task, arguments, previous_pipelines):
+    """Batch decode post-processing with pipeline reference"""
+    logger.debug("Performing batch decode post-processing")
+    pipeline_reference = task.task_definition["pipeline_reference"]
+    if pipeline_reference not in previous_pipelines:
+        raise KeyError(
+            f"Pipeline reference '{pipeline_reference}' not found in previous pipelines. "
+            f"Available pipelines: {list(previous_pipelines.keys())}"
+        )
+    processor = previous_pipelines[pipeline_reference].pipeline
+    return batch_decode_post_process(processor, **arguments)
+
+
+def _handle_image_processing(task, arguments, previous_pipelines):
+    """Handle image processing commands"""
+    logger.debug("Processing image")
+    device = task.device_for(arguments)
+    return _per_frame(
+        arguments.pop("image"),
+        lambda frame: process_image(frame, task.command, device, arguments),
+    )
+
+
+def _handle_video_processing(task, arguments, previous_pipelines):
+    """Handle video processing commands"""
+    logger.debug("Processing video")
+    device = task.device_for(arguments)
+    return process_video(
+        arguments.pop("video"),
+        task.command,
+        device,
+        arguments,
+    )
+
+
+# Command names process_video (video_utils.py) accepts, with the function
+# whose signature carries their arguments. video_utils dispatches via a plain
+# if-chain, so keep this in sync with the branches in process_video().
+# get_first/last_frame pin frame_index themselves, so it is 'provided'; they
+# share get_frame's implementation and so would share its generic docstring
+# summary too (#366) - 'summary' overrides that per command.
+_VIDEO_PROCESSOR_INFO = {
+    "get_frame": {
+        "kind": "video_processor",
+        "implementation": "dw.tasks.video_utils.get_frame",
+        "provided": (),
+    },
+    "get_first_frame": {
+        "kind": "video_processor",
+        "implementation": "dw.tasks.video_utils.get_frame",
+        "provided": ("frame_index",),
+        "summary": "The first frame of a video, as a PIL image.",
+    },
+    "get_last_frame": {
+        "kind": "video_processor",
+        "implementation": "dw.tasks.video_utils.get_frame",
+        "provided": ("frame_index",),
+        "summary": "The last frame of a video, as a PIL image.",
+    },
+}
+_VIDEO_PROCESSOR_COMMANDS = sorted(_VIDEO_PROCESSOR_INFO)
+
+
+class Task:
+    """
+    Represents a task that can be executed as part of a workflow.
+    Tasks are atomic operations like image processing, data gathering, or message formatting.
+    """
+
+    def __init__(self, task_definition, device, seed=None):
+        """
+        Initialize task with its configuration and device settings.
+
+        Args:
+            task_definition: Dictionary containing task configuration and parameters
+            device: Device to run task on (e.g., 'cuda', 'mps', 'cpu')
+            seed: The workflow/step-resolved seed, when one was set - None for
+                an unseeded run. Only a handler that calls seed_for(arguments)
+                consumes it; most tasks run no generator and ignore it
+        """
+        self.task_definition = task_definition
+        self.device = device
+        self.seed = seed
+        logger.debug(f"Initialized task: {self.name} for device: {device}")
+
+    @property
+    def name(self):
+        """Get task name from command property"""
+        return self.command
+
+    def device_for(self, arguments):
+        """Get the device this task runs on, consuming any override in its arguments.
+
+        A task can pin itself to a device - a captioning model on the CPU while the GPU
+        holds a pipeline, for instance. The argument is removed either way so it does
+        not reach the command as a duplicate.
+
+        Args:
+            arguments: Arguments for this run of the task
+
+        Returns:
+            Device identifier the task should run on
+        """
+        return resolve_device(arguments.pop("device", self.device))
+
+    def seed_for(self, arguments):
+        """Get the seed this task run should use, consuming any override in
+        its arguments.
+
+        A task step reproducible the way a pipeline step is: the
+        workflow/step-resolved seed by default, an explicit `seed` in the
+        step's own arguments taking precedence - and the argument is removed
+        either way so it does not reach the command as a duplicate. None
+        means no seed was ever set anywhere, so the task should run exactly
+        as it always did - unseeded and non-reproducible.
+
+        Args:
+            arguments: Arguments for this run of the task
+        """
+        return arguments.pop("seed", self.seed)
+
+    @property
+    def argument_template(self):
+        """
+        Get argument template for this task.
+
+        Returns:
+            Dictionary of arguments from inputs or arguments section
+        """
+        # A task will either be an input array or a dictionary of arguments
+        if "inputs" in self.task_definition:
+            logger.debug("Using inputs as argument template")
+            return self.task_definition["inputs"]
+
+        logger.debug("Using arguments as argument template")
+        return self.task_definition["arguments"]
+
+    @property
+    def command(self):
+        """Get command name or 'unknown' if not specified"""
+        return self.task_definition.get("command", "unknown")
+
+    def _check_required_arguments(self, arguments):
+        """Refuse a task whose required arguments are not all present, in the
+        validator's wording rather than Python's."""
+        if not isinstance(arguments, dict):
+            # An 'inputs' list template - consumed whole, no names to miss
+            return
+        from ..introspection import (
+            missing_task_argument_message,
+            missing_task_arguments,
+        )
+
+        missing = missing_task_arguments(self.command, arguments.keys())
+        if missing:
+            message = missing_task_argument_message(self.command, missing)
+            raise ValueError(message[0].upper() + message[1:])
+
+    def run(self, arguments, previous_pipelines={}):
+        """
+        Execute the task with given arguments using the command registry.
+
+        Args:
+            arguments: Dictionary of arguments for task execution
+            previous_pipelines: Dictionary of previously created pipelines
+
+        Returns:
+            Task output based on command type
+
+        Raises:
+            ValueError: If command is unknown
+            KeyError: If required arguments or pipeline references are missing
+        """
+        logger.debug(f"Running task: {self.command}")
+        logger.debug(f"Task arguments: {arguments}")
+
+        try:
+            # Cooperative cancellation reaches task steps too - without this
+            # a cancel during a long task waits for the whole task to finish
+            from ..events import emit_phase, get_context
+
+            get_context().check_cancelled()
+            # A task reports nothing of its own - a captioning model loading
+            # and decoding is otherwise indistinguishable from a hang
+            emit_phase("task", detail=self.command)
+
+            # A required argument that never arrived - because it was left
+            # out, or because a variable or an earlier step resolved to
+            # nothing - used to reach Python and come back as
+            # "resample_audio() missing 1 required positional argument:
+            # 'audio'", which names the calling convention rather than the
+            # workflow. The static pass in validation_errors refuses the
+            # literal case first; this is the backstop it cannot see (#141)
+            self._check_required_arguments(arguments)
+
+            # Look up command in registry
+            if self.command in _COMMAND_REGISTRY:
+                handler = _COMMAND_REGISTRY[self.command]
+                return handler(self, arguments, previous_pipelines)
+
+            # Not a registered command - check whether it names an image or
+            # video processor instead. Imported lazily here to preserve
+            # image_utils' lazy-import discipline for callers that never
+            # touch image processing.
+            from .image_utils import available_processors
+
+            if self.command in available_processors():
+                return _handle_image_processing(self, arguments, previous_pipelines)
+
+            if self.command in _VIDEO_PROCESSOR_COMMANDS:
+                return _handle_video_processing(self, arguments, previous_pipelines)
+
+            # Unknown command - not in the registry, and not a known image or
+            # video processor name either
+            error_msg = (
+                f"Unknown task command: '{self.command}'. "
+                f"Registered commands: {sorted(_COMMAND_REGISTRY.keys())}. "
+                f"Image processors: {available_processors()}. "
+                f"Video processors: {_VIDEO_PROCESSOR_COMMANDS}"
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        except KeyError as e:
+            # Missing required arguments or pipeline references
+            logger.error(
+                f"Missing required data for task {self.command}: {e}", exc_info=True
+            )
+            raise
+        except (ValueError, TypeError) as e:
+            # Invalid arguments or type mismatches
+            logger.error(
+                f"Invalid arguments for task {self.command}: {e}", exc_info=True
+            )
+            raise
+        except (OSError, IOError) as e:
+            # File operations, resource loading errors
+            logger.error(f"I/O error in task {self.command}: {e}", exc_info=True)
+            raise
+        except Exception as e:
+            # Catch-all for unexpected errors
+            logger.error(
+                f"Unexpected error ({type(e).__name__}) executing task {self.command}: {e}",
+                exc_info=True,
+            )
+            raise