What is MediaMoth?

MediaMoth is an open-source platform for building custom media-processing workflows. You define a pipeline of processing steps, and MediaMoth creates jobs and sends them to the registered worker services.

It runs on infrastructure you operate, so you can connect media-processing jobs to your own storage, worker tools, and deployment environment.

Why MediaMoth Exists

Media processing often combines several dependent steps: validating an input, converting it, adding metadata, and delivering the result. MediaMoth models those steps as a pipeline instead of leaving each run as an isolated command.

Use it when you need repeatable processing for a media library, multiple output variants, or a custom processing tool that should participate in the same workflow.

The Pipeline Philosophy

MediaMoth's core concept is a pipeline: a directed graph of processing nodes that transforms media from input to output.

Single-step transcoding: A pipeline can contain one node that converts MP4 to WebM with FFmpeg.

Multi-step processing: A pipeline can extract frames, send them to a custom worker for enhancement, and reassemble them into a video.

Branching workflows: From one source, a pipeline can generate several outputs, such as a web version, a mobile version, and an audio-only file.

Independent nodes can run in parallel. A node with predecessors waits until every predecessor completes, and Job Service tracks the resulting sequence.

What You Can Build

MediaMoth supports workflows such as:

• Format standardization: Convert a library to a consistent format and codec.
• Quality enhancement: Run media through denoising, color correction, or custom enhancement workers.
• Multi-format delivery: Generate the resolutions and formats required by a distribution target from one source.
• Custom processing: Integrate a proprietary tool, third-party API, or machine-learning model through a custom worker.

The included workers handle FFmpeg and HandBrake conversion, fixed or ML-assisted chapter insertion, RF capture decoding, and TBC video export. You can build additional queue-backed workers from the shared go-libs/workerservice components.

How It Works

MediaMoth separates orchestration from execution. The platform coordinates workflows while worker services perform the media-specific operations.

The Orchestration Layer

Four core services manage the platform:

• Workflow Service stores pipelines and registered worker metadata.
• Job Service turns a pipeline into a concrete job sequence and advances downstream nodes when their dependencies finish.
• Media Service manages metadata about media and its file sources.
• Search Service indexes media, pipelines, jobs, and service information for search.

The Execution Layer

Workers process the media. Current worker types include:

• Video Service for FFmpeg and HandBrake conversion.
• Chapter Inserter for fixed and detected chapter plans.
• VHS Decode for RF capture decoding.
• TBC Decode for exporting TBC captures to video.
• Custom workers built on the shared queue and gRPC contracts.

Workers validate parameters, process queued jobs, and report status events. Their metadata includes a parameter JSON Schema, UI Schema, health, and version.

Scaling Your Processing Power

Start with the source-development environment on one machine. When a workload needs more processing capacity, run additional worker processes that use the same configured services and queues.

• Single machine: Run services locally for development or light workloads.
• Distributed processing: Run workers on multiple machines that can reach the shared Kafka, PostgreSQL, and storage services.

Worker processes consume queued jobs independently and report their results through the same service interfaces.

Technical Foundation

MediaMoth uses Go services, gRPC, Kafka, PostgreSQL, River queues, Redis, and Elasticsearch. Docker Compose and mise tasks support the checked-in source-development environment.

The command services persist state changes as events. Query and search services update projections from those events, and administrative commands can rebuild a projection when needed.

Requirements

MediaMoth is self-hosted. Plan for:

• Infrastructure: Hosts for services and workers, plus storage for media and temporary files.
• Dependencies: Docker for the provided development environment, along with Kafka, PostgreSQL, Redis, and Elasticsearch.
• Operational knowledge: Comfort with command-line tools, containers, and service configuration.

Next Steps

• Getting Started: Set up the source-development environment.
• Pipeline concepts: Learn how workflows are structured.
• Services and schemas: Understand worker-service metadata.
• Building Custom Workers: Extend MediaMoth with your own processing logic.
• API Reference: Explore the service surfaces for programmatic integrations.