Home

Welcome to the MuxCore Wiki

MuxCore is a distributed, media-agnostic, module-first media orchestration platform.

Why MuxCore

The *arr stack was built for a smaller world. It's monolithic — one process, one node, one ceiling. Each media type needs its own program. Your 1080p and 4K libraries? Two separate Sonarr instances. Content pipelines are rigid, the interface bogs down under a large library, and when a node goes down nothing takes over.

MuxCore is the distributed rewrite. Every capability is a module behind a contract. Modules communicate over an event bus, not direct calls. Fire up more nodes. Name any media type. The platform adapts.

Core Philosophy: The Core Must Never Change

If a new media paradigm requires a core change, the architecture is wrong.

Core defines zero domain concepts. It knows nothing about downloads, indexers, playback, transcoding, metadata, or media types. Those are defined in independent versioned contract repos (contracts-*) that core never imports. Modules import the contracts they need.

Five patterns ensure this:

1. Extra map[string]any — The universal escape hatch. DownloadTask.Extra carries Apple Music track IDs, Spotify URIs, or S3 presigned URLs. MediaFilter.Extra carries artist/album/BPM filters. TranscodeProfile.Extra carries audio-only flags and sample rates. Core never interprets these fields.

2. Services via discovery — ModuleDeps carries eight fabric services. Everything else (SecretsProvider, DatabaseProvider, CacheLayer, MetricsProvider) is discovered at runtime via Registry.FindByCapability(). New service types don't require ModuleDeps changes.

3. String kinds, not enums — Kinds: []string{"downloader"}. Modules define their own kind strings. A module can declare "vr180_processor" — core has never heard of it but FindByKind("vr180_processor") returns it.

4. Contract repos — Domain contracts live in 17 versioned repos under github.com/Muxcore-Media/contracts-*. When playback needs a StreamSource interface for Apple Music, contracts-playback gets a PR. Core never changes.

5. Contract declarations — Modules declare {Repo, Version, Interface} in Info().Contracts. The marketplace checks compatibility. Consumers verify before type-asserting. Core stores and returns — nothing more.

See the full philosophy in the README with worked code examples.

How It Works

• Every capability is a module behind a contract — downloading, indexing, transcoding, playback, storage are all interfaces in contract repos
• Modules communicate via an event bus — event types defined in contract repos, not in core
• Storage is fully abstracted — modules never touch filesystem paths, everything goes through object IDs
• HA-aware and horizontally scalable — add nodes, split the load, survive failures
• Multiple modules per capability — two downloaders, three transcoding agents, five storage backends, all active simultaneously

Quick Navigation

Page	Description
Architecture	High-level architecture and design decisions
Module System	How modules work, lifecycle, discovery, contract declarations
Module Types	All module kinds, contracts, infrastructure services
Storage Abstraction	Virtual filesystem, capability negotiation, storage layers
Event System	Fabric events vs domain events, pub/sub patterns
Workflow Engine	Orchestration, retries, idempotency, pipelines
Security Model	RBAC, API tokens, SSO/OIDC, sandboxing
Contracts	Fabric contracts (core) vs domain contracts (repos)
Marketplace	Module marketplace, catalog format, compatibility checking
Deployment	Phase 1-3 deployment strategy, build presets
Roadmap	MVP scope and long-term vision

Quick Start

go install github.com/Muxcore-Media/core/cmd/muxcored@latest
muxcored