diffusers-workflow 0.4.0__py3-none-any.whl

dw/slice_preflight.py

@@ -0,0 +1,148 @@
+"""A `slice_audio` step whose source duration validate can already learn,
+sliced past where that source ends, warned about before the run (#402).
+
+`slice_audio` zero-pads a slice that reaches past its source and only says so
+at run time (`_warn_on_slice_past_end`, `dw/tasks/audio_utils.py`) - a
+correct message, but late when the slice sits downstream of a long render
+(#402's repro: `assemble-and-score` scoring a 15.5 s cut with a 4.96 s
+`score` asset, `validate_workflow` answering clean). Mirrors
+`dissolve_frame_errors.py` (#400): walk the expanded definition,
+`resolve_path_references` an `asset:`/`output:` audio into a real path, and
+`probe_media` it - the same resolution and decode the run itself would do,
+just ahead of the queue.
+
+Deliberately narrower than the run-time check, same as #400's: a
+`previous_result:` audio (nothing written yet), a remote URL, a literal path
+outside the directories the run may read (`dw/probe_paths.py` - a literal
+inside them is resolved against the workflow's directory and probed), or a
+source `probe_media` cannot read, all answer "unknown" rather than
+guessing - silence here is correct, not a gap, since the run-time warning
+still fires once the file exists. `variable:` needs no hop of its own: by the
+time `validation_errors`/`adapter_warnings` hand this module the *expanded*
+definition, `replace_variables` has already substituted every `variable:`
+reference (or the run cannot start at all), so what is left unresolved is
+only a reference that genuinely cannot resolve yet. The threshold
+(`SLICE_PAD_WARN_MS`) and the requested-length arithmetic mirror
+`slice_audio`'s own two argument shapes, so the two agree on the same
+padding for the same arguments.
+"""
+
+from .for_each import MEMBER_SEPARATOR, render_path
+from .media_info import probe_media
+from .probe_paths import resolve_probe_path
+from .tasks.audio_utils import SLICE_PAD_WARN_MS
+
+
+def _source_seconds(path):
+    """The duration `slice_audio` would see for this file, or None when it
+    cannot be probed or carries no audio."""
+    info = probe_media(path)
+    if info is None or info.get("kind") != "audio":
+        return None
+    return info.get("duration_seconds")
+
+
+def _as_number(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _requested_region(task_args):
+    """The (start_seconds, length_seconds) `slice_audio` would compute for
+    these arguments, or None when the shape given cannot be resolved to a
+    length without running anything - mirrors `slice_audio`'s own branch
+    order in `dw/tasks/audio_utils.py`."""
+    start_seconds = _as_number(task_args.get("start_seconds"))
+    duration_seconds = _as_number(task_args.get("duration_seconds"))
+    start_frame = _as_number(task_args.get("start_frame"))
+    num_frames = _as_number(task_args.get("num_frames"))
+    fps = _as_number(task_args.get("fps"))
+
+    if (
+        task_args.get("start_seconds") is not None
+        or task_args.get("duration_seconds") is not None
+    ):
+        if duration_seconds is None:
+            # Runs to the source's own end - cannot overrun it
+            return None
+        return start_seconds or 0.0, duration_seconds
+    if (
+        task_args.get("start_frame") is not None
+        or task_args.get("num_frames") is not None
+    ):
+        if num_frames is None or not fps:
+            return None
+        return (start_frame or 0.0) / fps, num_frames / fps
+    return None
+
+
+def slice_past_end_warnings(workflow_definition, source_indices=None, base_dir=None):
+    """Every `slice_audio` step whose source's real duration is already
+    knowable and whose requested slice reaches past it, as messages.
+
+    Walks the substituted, expanded definition, the same convention
+    `dissolve_frame_errors` follows: `source_indices` maps an expanded step
+    back to the one the author wrote, and a path inside a `for_each` member
+    names the member.
+    """
+    steps = workflow_definition.get("steps")
+    if not isinstance(steps, list):
+        return []
+
+    warnings = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        task = step.get("task")
+        if not isinstance(task, dict) or task.get("command") != "slice_audio":
+            continue
+        task_args = task.get("arguments")
+        if not isinstance(task_args, dict):
+            continue
+
+        path = resolve_probe_path(task_args.get("audio"), base_dir, "an audio argument")
+        if path is None:
+            continue
+        source_seconds = _source_seconds(path)
+        if not source_seconds:
+            continue
+
+        region = _requested_region(task_args)
+        if region is None:
+            continue
+        requested_start, requested_length = region
+
+        available = max(0.0, min(source_seconds - requested_start, requested_length))
+        padded_seconds = requested_length - available
+        if padded_seconds * 1000.0 < SLICE_PAD_WARN_MS:
+            continue
+
+        source = (
+            source_indices[index]
+            if source_indices is not None and index < len(source_indices)
+            else index
+        )
+        name = step.get("name")
+        where = (
+            f" in member '{name}'"
+            if isinstance(name, str) and MEMBER_SEPARATOR in name
+            else ""
+        )
+        path_str = render_path(("steps", source, "task", "arguments", "audio"))
+        warnings.append(
+            f"{path_str}: slice_audio will run {padded_seconds:.2f} s past "
+            f"the end of a {source_seconds:.2f} s source ({task_args.get('audio')}), "
+            f"so that much of the {requested_start + requested_length:.2f} s "
+            f"requested will be digital silence{where}. If you meant to fill "
+            f"a cut of this length, make a bed with the 'loop_audio' task "
+            f"('target_frames' + 'fps' matches one exactly) and slice that; "
+            f"if you meant the tail pad, nothing is wrong."
+        )
+    return warnings
+
+
+__all__ = ["slice_past_end_warnings"]

dw/step.py

@@ -0,0 +1,187 @@
+import logging
+from .events import WorkflowCancelled, get_context
+from .result import Result
+from .previous_results import get_iterations, resolve_chain_prompts
+
+logger = logging.getLogger("dw")
+
+
+class Step:
+    """
+    Represents a single step in a workflow execution.
+    Manages execution of pipelines, tasks, or sub-workflows with their configurations.
+    """
+
+    def __init__(
+        self,
+        step_definition,
+        default_seed,
+        workflow_definition=None,
+        consumed_by_normalizer=False,
+    ):
+        """Initialize step with its configuration and seed value.
+
+        workflow_definition, when given, is the original (unsubstituted)
+        definition of the workflow this step belongs to - embedded metadata
+        carries it so a saved image can be reopened as the workflow that
+        made it.
+
+        consumed_by_normalizer is whether a later step resets this result's
+        level (normalize_audio/match_levels) before anything ships it - see
+        step_cache.normalized_downstream and result.py's headroom checks."""
+        self.step_definition = step_definition
+        self.workflow_definition = workflow_definition
+        self.consumed_by_normalizer = consumed_by_normalizer
+        self.iteration = None
+
+        # Get step-specific seed or use default if not specified
+        self.default_seed = self.step_definition.get("seed", default_seed)
+        logger.debug(f"Initialized step: {self.name} with seed: {self.default_seed}")
+
+    @property
+    def name(self):
+        return self.step_definition.get("name", "unknown")
+
+    def run(self, previous_results, previous_pipelines, step_action):
+        """
+        Execute the step's action with all possible argument combinations.
+
+        Args:
+            previous_results: Results from previous steps, used for argument generation
+            previous_pipelines: Previously created pipelines that might be referenced
+            step_action: The actual action to execute (Pipeline/Task/Workflow)
+        """
+        try:
+            step_name = self.step_definition["name"]
+            logger.debug(f"Starting execution of step: {step_name}")
+
+            # Create result container with any special configuration from step definition
+            # This handles how results should be saved/processed
+            result = Result(
+                self.step_definition.get("result", {}),
+                consumed_by_normalizer=self.consumed_by_normalizer,
+            )
+
+            # Collect metadata for embedding if enabled
+            result_def = self.step_definition.get("result", {})
+            if result_def.get("embed_metadata", False):
+                metadata = self._collect_metadata()
+                result.set_metadata(metadata)
+
+            # Log what type of action we're executing (Pipeline/Task/Workflow)
+            action_type = type(step_action).__name__
+            logger.info(f"Running {action_type} {step_name}:{step_action.name}...")
+
+            # A chained pipeline's per-segment prompts live outside the argument
+            # template, so they are resolved here rather than by the pass below
+            resolve_chain_prompts(step_action, previous_results)
+
+            # Get all possible argument combinations for this step
+            # This expands any references to previous results into concrete values
+            iterations = get_iterations(step_action.argument_template, previous_results)
+            logger.debug(f"Generated {len(iterations)} argument combinations")
+
+            # The metadata above was read from the definition, where an
+            # argument may still be a 'previous_result:' reference - now that
+            # the iterations exist, record what the step actually ran with
+            if result.metadata is not None:
+                _realize_metadata_arguments(result.metadata, iterations)
+
+            # Execute the action for each set of arguments
+            if not iterations:
+                logger.warning(f"Step {step_name} has no iterations to execute")
+                return result
+
+            run_context = get_context()
+            for i, arguments in enumerate(iterations, 1):
+                run_context.check_cancelled()
+                logger.debug(
+                    f"Running iteration {i}/{len(iterations)} with arguments: {arguments}"
+                )
+                run_context.emit(
+                    "iteration_start",
+                    step=step_name,
+                    iteration=i,
+                    total_iterations=len(iterations),
+                )
+                self.iteration = i
+                iteration_result = step_action.run(arguments, previous_pipelines)
+                result.add_result(iteration_result)
+
+            logger.debug(f"Successfully completed step: {step_name}")
+            return result
+
+        except WorkflowCancelled:
+            logger.info(f"Step {self.name} cancelled")
+            raise
+        except Exception as e:
+            # One log line with the full traceback - callers decide handling.
+            # (Configuration, I/O, runtime and unexpected errors all logged and
+            # re-raised identically, so one clause replaces the old four)
+            iteration = getattr(self, "iteration", None)
+            where = f"iteration {iteration} of " if iteration else ""
+            logger.error(
+                f"{type(e).__name__} in {where}step {self.name}: {e}",
+                exc_info=True,
+            )
+            raise
+
+    def _collect_metadata(self):
+        """Collect step metadata for embedding in saved images."""
+        metadata = {"step_name": self.name}
+
+        # The whole recipe, not just this step's slice of it - this is what
+        # lets a gallery open an image as the workflow that produced it,
+        # and the seed is what makes reopening it reproduce this exact image
+        if self.workflow_definition is not None:
+            metadata["workflow"] = self.workflow_definition
+            metadata["seed"] = self.default_seed
+
+        if "pipeline" in self.step_definition:
+            pipeline_def = self.step_definition["pipeline"]
+            pretrained_args = pipeline_def.get("from_pretrained_arguments", {})
+            if "model_name" in pretrained_args:
+                metadata["model_name"] = pretrained_args["model_name"]
+            metadata["arguments"] = dict(pipeline_def.get("arguments", {}))
+
+        elif "task" in self.step_definition:
+            task_def = self.step_definition["task"]
+            metadata["task_command"] = task_def.get("command", "unknown")
+            metadata["arguments"] = dict(task_def.get("arguments", {}))
+
+        return metadata
+
+
+# What json.dumps can embed without falling back to str() - anything else
+# (a PIL image, a tensor, a video's frames) keeps its reference in metadata
+JSON_SCALARS = (str, int, float, bool)
+
+
+def _realize_metadata_arguments(metadata, iterations):
+    """Replace the embedded arguments with the values the step really ran with.
+
+    Step metadata is collected from the definition, so an argument written as
+    "previous_result:expand" is still a reference there - a gallery showing it
+    would display the reference instead of the prompt the pipeline saw. The
+    iterations hold the resolved values, so lift the JSON-safe ones back into
+    the metadata. When iterations disagree (a step fanned out over several
+    prior results) every distinct value is kept, in order.
+    """
+    arguments = metadata.get("arguments")
+    if not arguments or not iterations:
+        return
+
+    for key in list(arguments):
+        values = []
+        for iteration in iterations:
+            if not isinstance(iteration, dict) or key not in iteration:
+                values = []
+                break
+            value = iteration[key]
+            if not isinstance(value, JSON_SCALARS):
+                values = []
+                break
+            if value not in values:
+                values.append(value)
+        if values:
+            arguments[key] = values[0] if len(values) == 1 else values