How to Enable Video Export in OpenMAIC Docker Deployment

Enable video export in OpenMAIC by setting NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true and starting Docker Compose with the --profile video-export flag to launch the render service container.

OpenMAIC treats MP4 video generation as an optional capability to keep resource usage minimal for users who only need ZIP downloads. When enabled, the render-service container—running Chromium and FFmpeg—assembles slide data into a downloadable MP4 file. This guide walks through the exact configuration steps, environment variables, and verification commands drawn from the OpenMAIC source code.

Prerequisites for Video Export

Video export requires Docker Compose profiles support (Docker Compose v1.28+ or v2.x). The feature consumes additional memory due to Chromium headless rendering; allocate at least 2GB RAM to the render-service container.

Verify your Docker Compose version:

docker compose version

Step 1: Configure the Frontend Environment Variable

The Next.js frontend reads NEXT_PUBLIC_ENABLE_VIDEO_EXPORT at build time. Without this variable, the Settings page hides the "Export as MP4" button entirely.

Create or edit .env.local in your project root:

cat <<EOF > .env.local
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true

# Your existing variables below

EOF

This variable propagates through the docker-compose.yml environment injection at lines 27-33, where the app service receives both NEXT_PUBLIC_ENABLE_VIDEO_EXPORT and RENDER_SERVICE_URL=http://render-service:9000【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/THU-MAIC/OpenMAIC/main/docker-compose.yml#L27-L33】.

Step 2: Start with the Video-Export Profile

The render-service container is conditionally attached via Docker Compose profiles. Lines 66-82 of docker-compose.yml define this profile explicitly:

  render-service:
    build: ./render-service
    profiles: ["video-export"]
    ports:
      - "9000:9000"

Launch the full stack including the render service:

docker compose --profile video-export up --build

Omitting --profile video-export starts only the core services; the UI will fall back to ZIP export with no MP4 option available.

Step 3: Verify the Render Service Health

Confirm the Chromium+FFmpeg pipeline is ready:

curl -s http://localhost:9000/health | jq .

Expected response:

{
  "status": "healthy",
  "chromium": "connected",
  "ffmpeg": "available"
}

Check Docker logs if the health endpoint fails:

docker compose logs render-service --tail 50

Step 4: Export Video from the Web UI

With services running:

1. Open OpenMAIC in your browser
2. Navigate to Settings → Export
3. Click Export as MP4

The frontend POSTs slide data to http://render-service:9000/render, which returns a generated MP4 file after processing.

Key Configuration Files

File	Purpose	Critical Lines
docker-compose.yml	Declares video-export profile and service dependencies	27-33 (env injection), 66-82 (profile definition)【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/THU-MAIC/OpenMAIC/main/docker-compose.yml#L27-L33】【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/THU-MAIC/OpenMAIC/main/docker-compose.yml#L66-L82】
render-service/README.md	Documents resource limits and API contract	Service isolation details
.env.local	User-supplied frontend flags	NEXT_PUBLIC_ENABLE_VIDEO_EXPORT

Disabling Video Export

To revert to ZIP-only export:

# Stop and remove containers

docker compose --profile video-export down

# Restart without the profile

docker compose up

Or clear the environment variable:

unset NEXT_PUBLIC_ENABLE_VIDEO_EXPORT
docker compose up --build

The render service will not launch, and the UI will suppress the MP4 export button.

Summary

• Set NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true in .env.local to expose the video export UI
• Use --profile video-export when running docker compose to start the Chromium+FFmpeg render pipeline
• Verify at localhost:9000/health before attempting MP4 generation
• The feature is fully opt-in—no resources are consumed unless both the variable and profile are active

Frequently Asked Questions

Why doesn't the "Export as MP4" button appear in my deployment?

The button is gated by NEXT_PUBLIC_ENABLE_VIDEO_EXPORT. If undefined or falsy, the Next.js build excludes the video export components entirely. Check your .env.local and ensure the variable is set before docker compose up --build, as Next.js reads public environment variables at build time, not runtime.

Can I run the render service on a separate host?

The RENDER_SERVICE_URL injected in docker-compose.yml hardcodes http://render-service:9000 for internal Docker networking. To externalize rendering, modify this variable to point to your remote render endpoint, then remove the profiles restriction from the render-service definition or delete the service block entirely.

What happens if the render service crashes during export?

The frontend handles render service timeouts gracefully. Failed MP4 requests surface as error notifications in the UI, and users can retry or fall back to ZIP export. Monitor the render-service container health; automatic restarts can be added via Docker Compose restart: unless-stopped if needed.

Does video export work with GPU acceleration?

The stock render-service configuration runs Chromium in CPU-only headless mode for maximum compatibility. GPU passthrough requires modifying the render-service/Dockerfile to install NVIDIA drivers and adding runtime: nvidia to the compose service definition—this is not enabled by default in OpenMAIC's distribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}