Nodes

Nodes are the atomic processing steps of MetaLoom. A pipeline is a graph of nodes, and Cortex workers execute the individual node tasks that Loom dispatches. Each node has a unique kind (name) used to reference it in a pipeline definition and to route its work to a worker that can run it.

A node writes its result back to Loom over the REST API — a typed component plus an asset_node_result ledger row. Downstream nodes read a dependency’s output keys.

Between them the built-in nodes cover any media file type — images, videos, audio and documents. What is actually analysed for a given asset depends entirely on which nodes the pipeline contains.

The built-in nodes fall into four categories.

Hashing & Deduplication

Node Applies to Purpose

Hashing (md5, sha256, sha512, chunk-hash)

Any file

Content hashes for identity and deduplication

Fingerprint (fingerprint)

Video

Perceptual video fingerprint for similarity search

Consistency (consistency)

Video, Audio

Detect incomplete / corrupt media

Deduplication (sha512-dedup, fingerprint dedup)

Any / Video

Detect and move duplicates

Extraction & AI

Node Applies to Purpose

Tika (tika)

Any

Extract format metadata + text with Apache Tika

OCR (ocr)

Image

Extract text with Tesseract

Speech-to-Text (whisper)

Video, Audio

Transcribe audio with Whisper

LLM Enrichment (llm)

Any

Enrich metadata with a language model

Captioning (captioning)

Image

Natural-language image captions

Face Detection (facedetect)

Image, Video

Detect faces + embeddings

Face Description (facedescription)

Image

Describe detected faces with a vision model

Media Analysis

Node Applies to Purpose

Thumbnail (thumbnail)

Video

Contact-sheet preview thumbnails

Quality (quality)

Image, Video

Resolution / blurriness / bitrate metrics

Scene Detection (scene-detection)

Video

Optical-flow scene boundaries

Pipeline

Node Applies to Purpose

Filesystem Source (filesystem-source)

— (source)

Enumerate media from disk

Filters (filter-*)

— (routing)

Route items down PASS/REJECT branches

Loom Sync (loom)

Any

Batch hash results back to Loom

Requirements at a Glance

Most nodes are pure CPU. A few need a native library or an external model service:

Requirement Nodes

OpenCV / video4j native runtime

fingerprint, thumbnail, quality, scene-detection

InspireFace native runtime (GPU optional)

facedetect

Whisper runtime (whisper.cpp; GPU optional)

whisper

Tesseract (Tess4J)

ocr

An LLM provider service

llm, facedescription

A vision-language model service

captioning

CPU only

md5/sha256/sha512/chunk-hash, consistency, tika, filesystem-source, loom, filters, dedup

Pin the heavy kinds to dedicated or GPU workers via CORTEX_NODE_WHITELIST — see Cortex Configuration.

Processing Capabilities

What the built-in node set gives you, and which node provides it:

Asset hashing

md5, sha256, sha512, chunk-hash run in parallel over any file. Hashes are the basis for exact deduplication and for skipping already-processed assets.

Video fingerprinting

fingerprint computes a perceptual multi-sector fingerprint using the video4j-fingerprint library. It survives transcoding, resolution changes and minor edits, which makes near-duplicate detection possible at scale via vector similarity search.

Face detection

facedetect finds faces in images and video with the InspireFace library, returning bounding boxes, facial embeddings and the optimal focal point for cropped thumbnails. facedescription then describes those faces with a vision model.

Thumbnail generation

thumbnail renders contact-sheet previews from video frames and source images and uploads them to Loom as asset binaries.

Metadata extraction

tika uses Apache Tika to pull structured and unstructured metadata out of any supported format — EXIF from images, codec information from video, full text from documents.

Scene detection

scene-detection splits video into scenes with an optical-flow detector, producing cut timestamps that can drive per-scene thumbnails or clips.

OCR and speech-to-text

ocr extracts text from images and document pages with Tesseract; whisper transcribes audio and video soundtracks with the Whisper model.

AI captioning and enrichment

captioning generates natural-language descriptions with a vision-language model (SmolVLM), and llm enriches metadata through an LLM provider such as Ollama.

Consistency checking

consistency validates that stored metadata — hashes, dimensions, codec information — still matches the file on disk, flagging inconsistencies for review or remediation.

Authoring Your Own Node

Cortex is designed to be extended. A custom node in Java is three steps:

  1. Extend AbstractMediaNode<YourOptions>.

  2. Implement name(), isProcessable() and compute().

  3. Register the node via a Dagger module.

Alternatively, write a worker in Python that speaks the wire protocol directly. Both routes have a complete working example in Cortex Examples.