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 MediaMoth Core 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

One mediamoth-core process hosts four modules behind one gRPC endpoint:

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

The modules retain their existing protobuf service contracts, but they are not separate deployable processes. Core also runs their event consumers and projection workers in the same process.

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 a container deployment on one machine. When a workload needs more processing capacity, run additional worker processes that use the same core endpoint and queues.

• Single machine: Run Core and workers together for 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 runs the released containers, while mise tasks support source development. The core modules share one PostgreSQL database with separate workflow, media, job, search, and event_store schemas.

Core persists state changes as events. Its query and search modules update projections from those events, and module-scoped 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 Compose deployment, along with Kafka, PostgreSQL, Redis, and Elasticsearch.
• Operational knowledge: Comfort with command-line tools, containers, and service configuration.

Next Steps

• Getting Started: Pull and run MediaMoth Core with Docker Compose.
• 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.