AutoMedia

Automated Media Production Pipeline — for content teams and AI coding agents.

This README serves both human developers and AI coding agents (OpenCode, Claude Code, Codex CLI, OpenClaw, Hermes Agent) as the primary entry point. For detailed agent-role context, constraints, and codebase map, read AGENTS.md.

Quick Overview

AutoMedia automates content production from topic selection through draft writing, video generation, subtitle rendering, and multi-platform publishing. It handles the repetitive parts of media production so you can focus on creative decisions.

33,619 LOC (core) · ~90,000+ LOC (total) · 442+ Python files · Python 3.11+ · 2,955 test functions across 145 files · MIT License

For AI Agents

If you are an AI coding agent entering this codebase:

1. Read AGENTS.md — agent-role context, constraints, directory layout, MCP/CLI references, red lines
2. Connect MCP — Start the MCP server (python -m automedia.mcp.server) or configure your tool's MCP client (see Three-Layer API)
3. Explore config files — .opencode/, .claude/, .env.example for tool-specific setup
4. Find tests — tests/ directory, run with make test or pytest

Features

• Three-layer API: SDK / CLI (17 commands) / MCP Server (59 tools)
• 29 quality gates: G0-G6 (copy), V0-V7 (video/quality), L1-L4 (lifecycle), plus pre-gate, CW, D1-D7 (distribution), and P1-P4 (repurpose)
• 6-layer configuration hierarchy: defaults → project → user → overrides → env vars
• Platform-aware customization: Platform-scoped prompt templates, per-platform media specs, gate modifier overrides
• Workflow system: Reusable workflows.yaml definitions with cascading config merge
• Director mode: Human-in-the-loop approval via GateEngine pause/resume with MCP approve/reject tools
• Topic pool: SQLite-backed with scoring, dedup, scheduling
• Platform adapter system: Extensible publish targets — 20 registered adapters (13 real API + 7 documented manual-only stubs)
• Account & credential management: AES-256-GCM encrypted store, OAuth2/Cookie/API Key auth flows, session management
• Omni Triad: OPP (extraction), OL (localization), ORF (format conversion)
• Human-in-the-loop: Review gates for content and video quality approval
• MCP-native: Works with Claude Desktop/Code, OpenCode, Codex CLI, Cline, OpenClaw, Hermes Agent

Table of Contents

• Installation
• Quick Start
• Agent Quickstart
• Three-Layer API
• Agent Configuration
• Architecture
• Configuration
• Deployment
• Gate System
• Security
• Development
• Testing
• Project Status
• License
• Documentation Index

Installation

Quick start with Docker

Start using AutoMedia without any local dependencies:

docker pull kevinzhow/automedia-pipeline:latest
docker run -it --rm kevinzhow/automedia-pipeline:latest automedia doctor

A devcontainer configuration is also available at .devcontainer/devcontainer.json for VS Code Remote.

Manual installation

License notice: Optional extras [omni-pdf] and [omni] install PyMuPDF, which is licensed under AGPL v3. Ensure compliance with the AGPL before using these extras in your project.

Prerequisites:

• Python 3.11+
• FFmpeg
• Bun
• edge-tts CLI
• Whisper (faster-whisper or openai-whisper)
• Chrome/Chromium (headless mode for video rendering)
• ComfyUI (optional, for custom video generation)

Tip: All external dependencies come pre-installed in the Docker image. Use that to skip local setup.

Python 3.11+

AutoMedia requires Python 3.11 or newer.

Verify: python3 --version (or python --version on Windows)

FFmpeg

Audio/video encoding, decoding, format conversion, and frame extraction.

Verify: ffmpeg -version

Bun

JavaScript runtime for HyperFrames subtitle rendering and video assembly.

Verify: bun --version

edge-tts CLI

Python-based text-to-speech engine using Microsoft Edge TTS service.

pip install edge-tts

Verify: edge-tts --help

Whisper

Speech-to-text engine for subtitle generation. Choose one:

# Recommended: faster-whisper (faster, lower memory)
pip install faster-whisper

# Alternative: openai-whisper
pip install openai-whisper

Verify:

# faster-whisper
python -c "import faster_whisper; print(faster_whisper.__version__)"

# openai-whisper
python -c "import whisper; print(whisper.__version__)"

Chrome/Chromium

Used headless for video rendering and screenshot capture.

Verify: google-chrome --version (or chromium-browser --version on Ubuntu)

ComfyUI (optional)

Custom video generation with AI models. Required only for pipelines that use AI-generated visuals.

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
pip install -r requirements.txt

See the ComfyUI repository for full setup.

Verify: Start the server (python main.py) and check http://localhost:8188 is reachable.

Docker alternative: All external dependencies are pre-installed in the Docker image. See Quick start with Docker.

pip install -e .

# With extras (recommended: use [all] for full functionality)
pip install -e ".[all]"       # full functionality (all extras)
pip install -e ".[dev]"       # development (LLM providers, mcp, rich, test)
pip install -e ".[mcp]"       # MCP server only
pip install -e ".[openai]"    # OpenAI provider
pip install -e ".[anthropic]" # Anthropic provider

Development installation

git clone <repo-url> && cd AutoMedia

# Create virtual environment
python -m venv .venv && source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

Or use the setup script:

bash scripts/setup.sh

Windows setup:

.\scripts\setup.ps1

See Windows Deployment for WSL2, Docker Desktop, and native Windows setup guides.

Quick Start

# Initialize configuration
automedia init

# Check dependencies
automedia doctor

# Run full pipeline (auto mode)
automedia run --topic "Your Topic Here" --brand my-brand

# Text-only mode (skip video generation)
automedia run --topic "..." --brand my-brand --mode text_only

Agent Quickstart

New to this codebase? Here's your orientation path:

Step 1: Read AGENTS.md       → Codebase map, constraints, red lines (10 MUST/MUST NOT)
Step 2: Review agent config  → .opencode/ (OpenCode), .claude/ (Claude Code)
Step 3: Start MCP server     → python -m automedia.mcp.server
Step 4: Verify setup         → automedia doctor
Step 5: Try a pipeline       → automedia run --topic "..." --brand my-brand --mode text_only

Files every agent should read:

Three-Layer API

AutoMedia exposes three interfaces to the same run_full_pipeline() implementation.

Python SDK

from automedia import run_full_pipeline

result = run_full_pipeline(
    topic="AI video tools comparison",
    brand="my-brand",
    mode="auto",
)

CLI (17 commands)

MCP Server (59 tools)

Start:

python -m automedia.mcp.server

SDK with Workflow and Director

from automedia import run_full_pipeline

# Run with a predefined workflow
result = run_full_pipeline(
    topic="AI tools comparison",
    brand="my-brand",
    workflow="daily-article",  # Reference a workflow from workflows.yaml
)

# Run with director mode (HITL approval gates)
result = run_full_pipeline(
    topic="AI tools comparison",
    brand="my-brand",
    director=True,  # Pause at H0 gate for human approval
)

MCP Client Configuration Examples

Claude Desktop / Claude Code:

{
  "mcpServers": {
    "automedia": {
      "command": "python",
      "args": ["-m", "automedia.mcp.server"],
      "env": {"AUTOMEDIA_LLM_API_KEY": "sk-xxx"}
    }
  }
}

Cursor (via .cursor/mcp.json at project root):

{
  "mcpServers": {
    "automedia": {
      "command": "python",
      "args": ["-m", "automedia.mcp.server"],
      "env": {"AUTOMEDIA_LLM_API_KEY": "${AUTOMEDIA_LLM_API_KEY}"}
    }
  }
}

OpenCode (configured via .opencode/package.json):

{
  "mcpServers": {
    "automedia": {
      "command": "python",
      "args": ["-m", "automedia.mcp.server"]
    }
  }
}

Codex CLI (in .codex/config.json or global config):

{
  "mcpServers": {
    "automedia": {
      "command": "python",
      "args": ["-m", "automedia.mcp.server"],
      "env": {"AUTOMEDIA_LLM_API_KEY": "sk-xxx"}
    }
  }
}

OpenClaw — supports MCP via its plugin system; configure in ~/.openclaw/ or use the Gateway dashboard.

Hermes Agent (in ~/.hermes/config.yaml):

mcp_servers:
  automedia:
    command: python
    args: ["-m", "automedia.mcp.server"]
    env:
      AUTOMEDIA_LLM_API_KEY: "sk-xxx"

Hermes also reads AGENTS.md from the project root as its primary project context — no additional config needed for project awareness.

Agent Configuration

The project ships agent-specific config files at the repository root:

All tools also read AGENTS.md for project context — it's the single source of truth for agent-role information. Hermes Agent additionally supports .hermes.md (highest priority), but since this project targets multiple agent types, AGENTS.md is the canonical choice (per Hermes docs: "Use AGENTS.md when the same project will also be worked on by other agents").

Architecture

  +------------------------------------------+
  |  Any MCP Client / SDK / CLI Terminal      |
  +-----------+-------------------+-----------+
              |                   |
  +-----------+----+     +--------+-----------+
  |  MCP Server    |     |  CLI (typer)       |
  |  59 tools      |     |  17 commands       |
  +-----------+----+     +--------+-----------+
              |                   |
  +-----------+-------------------+------------+
  |      automedia/ Python Package             |
  |  core/ pipelines/ gates/ adapters/         |
  |  accounts/ hooks/ manifests/ pool/ cron/   |
  |  mcp/ cli/ hitl/ omni/ prompts/           |
  +--------------------------------------------+

Core Subpackages

Configuration

Six-layer priority hierarchy (lowest to highest):

1. Built-in defaults: automedia/manifests/defaults.yaml
2. Project config: .automedia/ directory
3. User config: ~/.automedia/ directory
4. Override rules: ~/.automedia/overrides/rules/*.yaml
5. Override prompts: ~/.automedia/overrides/prompts/*.j2
6. Environment variables: AUTOMEDIA_* + explicit CLI/MCP overrides

Each layer merges with the one below it. See .env.example for all supported environment variables.

Deployment

AutoMedia supports four deployment methods: Docker, native pip install, systemd services, and native Windows. See Deployment Options for a comparison table, production checklist, and CI/CD integration guidance.

Gate System

Gates are quality checks that run at specific points in the pipeline. Each gate has a failure mode ("stop" halts the pipeline, "retry" triggers content regeneration).

Total: 33 gates. Gate order: pre-gate → CW → G0-G6 → V0-V7 → H0 → L1-L4. D-gates invoked via automedia distribute CLI/MCP (not in pipeline). P-gates run at end of repurpose pipeline mode.

Security

• Red Line 8: archive_project / automedia archive refuses unless status is "published" or force=True. Agents MUST NOT circumvent.
• Path allowlist: MCP server (mcp_allowlist.yaml) restricts file access to configured directories. Empty list = deny all paths. Do not modify without explicit user request.
• Encrypted credential store: Platform credentials encrypted at rest with AES-256-GCM; master key derived from AUTOMEDIA_MASTER_KEY via SHA-256. Credentials never appear in logs or MCP responses.
• Credential isolation: Credentials loaded from encrypted store, env vars, or system keyring, never persisted to config files.
• No production data in tests: Use synthetic fixtures from tests/fixtures/synth/ only.
• Git secrets: .env, credentials.yaml, *.pem, *.key, *.token all gitignored.

Development

Prerequisites (dev)

pip install -e ".[dev]"
pre-commit install

Makefile Targets

make install        # Install base package
make install-dev    # Install with dev dependencies
make test           # Run full test suite
make test-coverage  # Run with coverage report
make lint           # Run ruff
make typecheck      # Run mypy
make pre-commit     # Run pre-commit on all files
make doctor         # Check system dependencies
make clean          # Clean build artifacts

Scripts

Testing

# Full test suite
pytest

# With coverage
pytest --cov=src/automedia

# By marker
pytest -m e2e        # End-to-end tests
pytest -m redline    # Red line enforcement tests
pytest -m slow       # Slow tests (video/audio processing)

# Specific test directory
pytest tests/test_gates/ -v
pytest tests/test_cli/ -v
pytest tests/test_mcp/ -v

Project Status

Active development. 2,955+ test functions across 145+ files. ~90,000+ LOC across 442+ Python files (33,619+ LOC in automedia/ core).

License

MIT License. See LICENSE for details.

Documentation Index