Recipes

Concrete patterns from the workers catalog. Each recipe is the full main.py plus the matching component.yml excerpt. Drop into src/main.py, run ppl release, and the new component is live.

1. Draw bounding boxes on an image

Two inputs (an image and a list of detections), one output (the annotated image).

name: "Draw bounding boxes"
language: py
platform: linux/amd64
build_system: 2
tags: ["latest", "default"]
worker:
  input_types:
    - Image
    - "[BoundingBox]"
  output_type: Image

2. Mono-mix audio

Convert any AudioFrame down to mono.

name: "Mono-mix audio"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_type: AudioFrame
  output_type: AudioFrame

3. Stateful counter

Track running state across messages with initial_state.

name: "Running mean"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_type: Double
  output_type: Double

4. Virtual-input webcam producer

Pull frames in a side thread and push them into the backend graph via virtual_in.

name: "Webcam input"
language: py
platform: linux/amd64
build_system: 2
worker:
  output_type: Image

blocking=False drops frames when the backend is slower than the camera — the right behavior for live data. virtual_in.close() makes the worker exit cleanly when the camera stops.

5. Configurable image filter

Use config for all dynamic parameters; the user can adjust them in the App without redeploying.

name: "Gaussian blur"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_type: Image
  output_type: Image
  config_schema:
    radius:
      type: UInt64
      default: 5
      description: "Gaussian blur radius in pixels (rounded up to odd)."
    sigma:
      type: Double
      default: 0.0
      description: "Standard deviation; 0 means OpenCV's auto from radius."

6. Streaming-mode chunked audio processor

A worker that pulls 5 audio chunks at a time and emits one summary value per batch, regardless of how often upstream produces audio.

name: "Summarize audio chunks"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_type: AudioFrame
  output_type: Float

from_fixed(skip, min_pull, max_pull) = (0, 5, 5) means: skip nothing, require exactly 5 messages on the audio input. The runtime won't trigger your worker until 5 audio frames are available.

7. Two inputs, custom record output

Combine two streams into a structured output. Build the record type once at module scope and reuse the handle — passing the bare string on every call re-parses the type expression every tick, which is wasted work.

name: "Tag image with score"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_types:
    - Image
    - Double
  output_type: "{image: Image, score: Double}"

For named types you'll reference from multiple components, register them globally with register_named([(name, expr)]) and look them up with get_type(name) — same caching benefit, with a stable name across the workspace. See API: types.

8. Multi-output split

Declare multiple outputs in component.yml and return a tuple.

name: "Split image into channels"
language: py
platform: linux/amd64
build_system: 2
worker:
  input_type: Image
  output_types:
    - Image
    - Image
    - Image

What's next

• API: cv — the wrapper classes used in every recipe.
• API: worker — full run() reference (state, virtual streams, streaming mode).
• Footguns — what catches new authors out.