Loom & Cortex Interaction

Loom and Cortex are complementary components that can be deployed together or used independently.

Architecture Overview

┌─────────────────────────────────────────────┐
│  Loom (Media Asset Management Server)        │
│                                             │
│  REST API (:8092)  gRPC (:8091)             │
│  PostgreSQL database                        │
│  Pipeline definitions (stored in DB)        │
│  WebSocket event bus (/pipelines/events/ws) │
└───────────────────┬─────────────────────────┘
                    │  REST API (LoomClient)
                    │  Pipeline definitions
                    │  Asset results (hashes, thumbs, ...)
                    ▼
┌─────────────────────────────────────────────┐
│  Cortex (Media Processing Engine)            │
│                                             │
│  Monitoring API (:8093)                     │
│  Pipeline executor (node graph)             │
│  Local meta-path cache                      │
└─────────────────────────────────────────────┘
        │
        │  reads media files
        ▼
   /media/assets/...

Online Mode

In online mode Cortex establishes a connection to Loom and performs the following steps at startup:

  1. Authenticate — Cortex logs in to Loom using configured credentials.

  2. Load pipelines — Cortex calls GET /api/v1/pipelines to retrieve the active pipeline definitions.

  3. Register node descriptors — Cortex posts its available node capabilities to GET /api/v1/node-descriptors so Loom knows what analyses are available.

  4. Process assets — For each asset in the configured source paths, Cortex runs the pipeline node graph.

  5. Push results — The built-in loom node posts extracted metadata (hashes, thumbnails, embeddings, captions, …) back to Loom via the REST API.

  6. Emit events — Processing progress is published over the WebSocket endpoint GET /api/v1/pipelines/events/ws.

Connecting Cortex to Loom

cortex --hostname loom.internal --port 7733 server start

Or via environment variables:

LOOM_HOST=loom.internal LOOM_PORT=7733 cortex server start

LoomNode

The loom node is the bridge between Cortex and Loom. It reads the outputs published by upstream nodes in the pipeline (hashes, thumbnail paths, embeddings, …) and writes them to the corresponding Loom REST endpoints:

  • POST /api/v1/assets — create or update the asset record

  • POST /api/v1/assets/:uuid/binary — upload thumbnail

  • POST /api/v1/embeddings — store face or video fingerprint embeddings

Offline Mode

In offline mode, Cortex operates without any network connection.

  • No Loom server required.

  • Extracted metadata is stored in the local meta-path directory (default: ~/.cache/metaloom/cortex/meta).

  • Extended file attributes (xattr) may also be written alongside the media files.

  • Useful for pre-processing large archives, air-gapped environments, or development.

# Offline batch processing — no Loom flags needed
cortex process run --actions sha256,sha512,tika,thumbnail /media/archive

Pipeline Events

While Cortex processes assets it publishes real-time events over a WebSocket:

ws://<loom-host>:8092/api/v1/pipelines/events/ws

Event payload example:

{
  "pipelineId": "550e8400-e29b-41d4-a716-446655440000",
  "nodeId": "sha256",
  "assetUuid": "7f3b2c10-...",
  "status": "COMPLETED",
  "duration": 42
}

These events are consumed by the Loom UI to show live processing progress per pipeline and node.

Deployment Patterns

Pattern Description

Side-car

Cortex runs as a container next to Loom in the same pod/compose stack and processes assets continuously.

CronJob

Cortex runs as a Kubernetes CronJob on a schedule, processes new files, and exits.

Manual batch

A developer runs cortex process run locally against a mounted share.

Standalone

Cortex runs offline with no Loom server; results stay local.