Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/morteng/media-engine

Agent-based media production framework. Document management, video generation with voiceover & captions, diagram generation, professional HTML/PDF/PPTX output with theming.
https://github.com/morteng/media-engine

cli document-generation media-production python video-generation

Last synced: 5 months ago
JSON representation

Agent-based media production framework. Document management, video generation with voiceover & captions, diagram generation, professional HTML/PDF/PPTX output with theming.

Awesome Lists containing this project

README 

          
# Media Engine



**Agent-operated media production framework for automated content generation.**



Write content once in Markdown. Generate professional documents, presentations, videos, and interactive demos automatically.



[![CI](https://github.com/morteng/media-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/morteng/media-engine/actions/workflows/ci.yml)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)



---



## See It In Action





  

    Media Engine Walkthrough

  






  120-second walkthrough: Dashboard, content hierarchy, quality, brand system, build & publish, AI workspace, and video production


  This video was built with Media Engine - from YAML script to AI voiceover to motion graphics




---



## What It Does



Media Engine transforms your Markdown content into multiple output formats:



| Input | Outputs |

|-------|---------|

| Markdown chapters | HTML documents, PDF reports |

| YAML scripts | Voiceover audio, captions, video |

| YAML slide definitions | PowerPoint presentations |

| YAML data files | Excel spreadsheets with charts |

| YAML demo configs | Interactive HTML demos |

| YAML diagram specs | SVG/PNG diagrams |



All outputs are styled consistently using your theme configuration.



---



## Features



### Content Management

- **Markdown + YAML frontmatter** - Version tracking, status workflow, dependency graphs

- **Multi-language support** - Translation tracking with outdated detection

- **Full-text search** - Indexed search with relevance scoring



### Document Generation

- **HTML** - Responsive design, syntax highlighting, dark mode

- **PDF** - Print-ready documents

- **PowerPoint** - Slide decks from YAML definitions

- **Excel** - Spreadsheets with formulas and charts

- **Diagrams** - Multi-engine (matplotlib, d2, excalidraw) with theming



### Publications System

- **Deliverable-centric** - Define publications (book, deck, video, report, website, package)

- **Component-based** - Compose from chapters, slides, data sources

- **Multi-format** - Build to PDF, HTML, PPTX, XLSX per publication

- **Validation** - Automatic status tracking and freshness monitoring



### Brand System

- **Single source** - Colors, typography, logos in brand.yaml

- **Voice guidelines** - Tone profiles by document type and audience

- **Design tokens** - Semantic colors, spacing, borders, shadows

- **Dark mode** - Full support throughout all outputs



### Video Production

- **Voiceover** - ElevenLabs TTS with smart caching

- **Captions** - Auto-generated WebVTT

- **Motion graphics** - Remotion React components

- **Browser capture** - Playwright-based screen recording



### Quality Assurance

- **Readability scoring** - Flesch, Fog, SMOG indexes

- **Link validation** - Internal and external URL checking

- **Reference checking** - Cross-document reference validation

- **Schema validation** - Frontmatter structure enforcement

- **Security scanning** - API keys, PII, secrets detection



### AI Workspace

- **Session tracking** - Track AI agent work with progress and changes

- **Task queue** - Structured tasks with priorities

- **Research store** - Persist findings across sessions

- **Notes & decisions** - Human-AI collaboration with reasoning capture



### Integrations

- **CLI** - Full command-line interface (25+ command modules)

- **MCP Server** - 26 tool modules with 100+ tools for AI agents

- **Web Dashboard** - Real-time project management UI (7 pages, 15+ tabs)

- **GitHub Actions** - CI/CD workflow templates

- **Python API** - Programmatic access to all features



---



## Quick Start



```bash

# Clone and install

git clone https://github.com/morteng/media-engine.git

cd media-engine

uv sync



# Or with pip

pip install -e ".[all]"



# Initialize project

media-engine init my-project

cd my-project



# Build all outputs

media-engine build



# Launch dashboard

media-engine dashboard

```



---



## CLI Reference



```bash

# Project status

media-engine status              # Full dashboard

media-engine status docs         # Document status

media-engine status videos       # Video production status



# Build outputs

media-engine build               # Build all formats

media-engine build --only html   # HTML only

media-engine build --force       # Force rebuild



# Quality & validation

media-engine quality             # Run quality checks

media-engine validate            # Schema + reference validation

media-engine security            # Scan for secrets/PII

media-engine links               # Validate all links



# Translation tracking

media-engine translation status    # All translation pairs

media-engine translation outdated  # Outdated translations

media-engine translation missing   # Missing translations



# Content analysis

media-engine readability         # Readability scores

media-engine gaps                # Content gap analysis

media-engine search "query"      # Full-text search



# Interactive demos

media-engine demos list          # List available demos

media-engine demos build         # Build to HTML



# Publishing

media-engine publish             # Self-contained package

media-engine pack investor       # Curated audience pack



# Dashboard

media-engine dashboard           # Launch web UI

```



---



## Project Structure



```

my-project/

├── project.yaml          # Project configuration

├── brand.yaml            # Brand identity (colors, typography, voice)

├── theme.yaml            # Design tokens

├── schema.yaml           # Frontmatter validation

├── content/

│   ├── en/

│   │   ├── chapters/     # Markdown documentation

│   │   ├── publications/ # Publication definitions (book, deck, video)

│   │   ├── scripts/      # Video script YAML

│   │   ├── slides/       # Presentation YAML

│   │   ├── diagrams/     # Diagram definitions

│   │   ├── demos/        # Interactive demo configs

│   │   └── data/         # Spreadsheet data

│   └── no/               # Norwegian translations

├── assets/               # Images, fonts, media

└── output/               # Generated files

```



---



## Configuration



### project.yaml



```yaml

project:

  name: "My Project"

  description: "Project description"



localization:

  source_language: "en"

  languages:

    en:

      name: "English"

      locale: "en-US"

      voice_id: "your-elevenlabs-voice-id"

    "no":  # Quote "no" - YAML interprets bare 'no' as false

      name: "Norwegian"

      locale: "nb-NO"



voiceover:

  provider: "elevenlabs"

  stability: 0.5

  similarity_boost: 0.75



video:

  width: 1920

  height: 1080

  fps: 30



paths:

  content: "content"

  assets: "assets"

  output: "output"

```



### theme.yaml



```yaml

name: "My Theme"



colors:

  primary: "#1a365d"

  accent: "#3182ce"

  background: "#ffffff"

  text: "#1a202c"



typography:

  heading: "Inter"

  body: "Source Sans 3"

  code: "JetBrains Mono"

```



---



## Python API



```python

from media_engine import find_project, run_quality_checks



# Load project

project = find_project()



# List documents

for doc in project.list_chapters("en"):

    print(f"{doc.stem}: v{doc.metadata.get('version', '?')}")



# Run quality checks

report = run_quality_checks(project)

print(f"Found {report.error_count} errors, {report.warning_count} warnings")



# Build outputs

from media_engine.builders import HTMLBuilder

builder = HTMLBuilder(project)

builder.build_all()

```



---



## MCP Server (AI Agent Integration)



Connect Claude Desktop or any MCP-compatible agent:



```bash

# Run MCP server

media-engine-mcp --project /path/to/project

```



**Claude Desktop config** (`~/.claude/claude_desktop_config.json`):



```json

{

  "mcpServers": {

    "media-engine": {

      "command": "media-engine-mcp",

      "args": ["-p", "/path/to/project"]

    }

  }

}

```



**Key tool categories:**

- **Project** - `project_status`, `get_project_context`, `refresh_project`

- **Documents** - `list_chapters`, `read_document`, `create_document`, `update_document_content`

- **AI Context** - `get_ai_context`, `start_ai_session`, `record_session_progress`, `add_ai_note`

- **Quality** - `quality_check`, `quality_report_summary`, `publish_readiness`

- **Build** - `build_html`, `build_pptx`, `build_diagram`, `list_publications`

- **Translation** - `translation_status`, `outdated_translations`, `sync_all_translations`

- **Search** - `search_content`, `find_relevant_documents`, `natural_language_query`



Full list: 26 modules with 100+ tools for comprehensive AI agent integration.



---



## Web Dashboard



```bash

media-engine dashboard

# Opens http://localhost:8080

```



**Navigation:**

- **Overview** - Dashboard (health score, publications, AI workspace), Build & Publish

- **Content** - Documents, Hierarchy (4 view modes), Translations, Video, Media

- **Quality** - Overview (health score), Analysis (knowledge graph), Activity (audit log)

- **Brand** - Design System (colors, typography, logos), Voice & Guidelines

- **AI Workspace** - Sessions, Notes, Queue, Research, Decisions

- **Settings** - Theme, Project, Quality, Video, Paths



Features:

- Real-time updates via WebSocket

- Hierarchy visualization (panel, tree, flow, graph views)

- Publication management with format/language selection

- AI session tracking and task queue

- Brand system editor with live preview



---



## Video Production Pipeline



Define video scripts in YAML:



```yaml

id: product-demo

title: "Product Demo"

duration: 120

scenes:

  - type: title

    text: "Welcome to Our Product"

    duration: 5

  - type: demo

    action: "Show the dashboard"

    voiceover: "Let me show you the main dashboard."

    duration: 10

```



Build with voiceover and captions:



```bash

media-engine build --only video

```



Generates:

- `output/en/videos/product-demo.mp3` - Voiceover audio

- `output/en/videos/product-demo.vtt` - Captions

- `output/en/videos/product-demo/props.json` - Remotion render props



---



## Interactive Demos



Create 9 types of interactive demos: `calculator`, `code_playground`, `comparison`, `timeline`, `quiz`, `data_viz`, `form_demo`, `api_explorer`, `interactive_diagram`:



```yaml

# content/en/demos/pricing.yaml

id: pricing-calc

type: calculator

title: "Pricing Calculator"

data:

  formula: "(users * 10) + (storage * 0.05)"

  variables:

    - name: users

      label: "Number of Users"

      default: 100

    - name: storage

      label: "Storage (GB)"

      default: 500

```



Build demos:



```bash

media-engine demos build

# Creates interactive HTML in output/demos/

```



---



## Security Scanning



Detect sensitive content before publishing:



```bash

media-engine security

media-engine security --include-assets

```



Detects:

- API keys (AWS, GitHub, OpenAI, Anthropic, Stripe)

- PII (emails, phone numbers, SSN patterns)

- Internal URLs and private IPs

- Credentials and secrets



---



## Installation



```bash

# Clone repository

git clone https://github.com/morteng/media-engine.git

cd media-engine



# Install with uv (recommended)

uv sync



# Or with pip (editable install)

pip install -e "."              # Core only

pip install -e ".[web]"         # With dashboard

pip install -e ".[mcp]"         # With MCP server

pip install -e ".[pdf]"         # With PDF generation

pip install -e ".[all]"         # Everything

```



---



## Demo Project



The `demo/` directory is a comprehensive, self-documenting reference project:



- **17 chapters** covering all Media Engine features

- **4 publications** (documentation, presentation, quickstart, feature matrix)

- **Complete brand system** with Capy the Capybara mascot

- **Video scripts, diagrams, slides, and data files**

- **The walkthrough video** - built entirely with Media Engine



```bash

cd demo

media-engine dashboard    # Explore the demo project

media-engine build        # Build all outputs

```



---



## Repository Structure



```

media-engine/

├── python/

│   └── media_engine/        # Main Python package

│       ├── core/            # Config, Project, Theme, Hashing

│       ├── brand/           # Brand system

│       ├── cms/             # Document management

│       ├── video/           # Video production

│       ├── builders/        # Output generators (HTML, PDF, PPTX, XLSX)

│       ├── diagrams/        # Multi-engine diagrams (matplotlib, d2, excalidraw)

│       ├── publications/    # Publication registry, builder, tracker

│       ├── ai/              # AI context, sessions, research, notes, queue

│       ├── relationships/   # Unified document relationships

│       ├── quality/         # Quality checks

│       ├── security/        # Secret/PII detection

│       ├── web/             # Dashboard (FastAPI, 24 route files)

│       ├── mcp/             # MCP server (26 tool modules)

│       └── cli/             # CLI interface (25+ command modules)

├── dashboard/               # React dashboard (Vite + React 19)

├── remotion/                # Motion graphics (React)

├── demo/                    # Reference project

└── pyproject.toml

```



---



## License



MIT



---



## Contributing



Contributions welcome! Please read our contributing guidelines and submit PRs.



```bash

# Run tests

uv run pytest



# Lint

uv run ruff check python/

```