Your face. Any meme.

AI face swapping for GIFs — running 100% locally on your Mac.
No cloud. No uploads. Just memes.

⬇️ Download for Mac · 🌐 Landing page · Installation · Architecture · Contributing

meme-swap wraps the FaceFusion AI engine in a fully typed TypeScript pipeline, and ships it as three apps that share one local engine:

• 🔒 Private by design — models, processing and results all live in ~/.meme-swap/ on your machine. Your face never leaves your Mac, and swapping works fully offline once installed.
• ⚡ Apple Silicon fast — inference runs through CoreML (Neural Engine + GPU) via ONNX Runtime, with CPU and CUDA fallbacks.
• 🧠 A real AI pipeline — not just a swap: inswapper_128 for identity transfer, CodeFormer face restoration, Real-ESRGAN ×2 frame upscaling, expression restorer and lip syncer, orchestrated per-frame.
• 🎞️ GIF-native — FFmpeg handles GIF ↔ MP4 both ways with palette-optimized output, so memes stay memes.
• 🔎 Giphy, plugged in — search trending memes right inside the app with hashtag shortcuts; pick a GIF and it's fetched and converted automatically (with a curated offline library when no API key is set).

Giphy built in — search, click, swap. No downloads, no tabs.

Ready to swap — target GIF, source face, quality presets. One button.

• Architecture
• Project Structure
• Prerequisites
• Installation
• Running the Apps
• Packages
• Environment Variables
• Landing Page & Docs
• Contributing
• Responsible Use

graph TB
    subgraph "Applications"
        FE["Web Frontend\n(Next.js 16)"]
        DE["Desktop App\n(Electron)"]
        MCP["MCP Server\n(HTTP/SSE)"]
    end

    subgraph "Shared Packages"
        FC["@meme-swap/faceswap-core\nFaceFusion wrapper"]
        VP["@meme-swap/video-processor\nFFmpeg wrapper"]
        AC["@meme-swap/api-client\n(Giphy client)"]
        I18N["@meme-swap/i18n\nTranslations"]
    end

    subgraph "Local engine — ~/.meme-swap/"
        FF["FaceFusion\n(Python venv + ONNX models)"]
        FFMPEG["FFmpeg\n(system)"]
    end

    FE --> FC
    FE --> VP
    DE --> FC
    DE --> VP
    MCP --> FC
    MCP --> VP

    FC --> FF
    VP --> FFMPEG

sequenceDiagram
    participant U as User
    participant App as App (Web/Desktop/MCP)
    participant VP as video-processor
    participant FC as faceswap-core
    participant FF as FaceFusion

    U->>App: Upload face image + target GIF
    App->>VP: gifToMp4() if target is GIF
    VP-->>App: MP4 video
    App->>FC: runFaceSwap(source, target.mp4)
    FC->>FF: spawn python3 facefusion.py (headless-run)
    FF-->>FC: processed MP4 (+ live progress)
    FC-->>App: result path
    App->>VP: mp4ToGif() if output should be GIF
    VP-->>App: final GIF
    App-->>U: Download URL

Execution providers: coreml (default on Apple Silicon) → cpu fallback, cuda supported.

meme-swap/
├── apps/
│   ├── frontend/             # Next.js 16 web application
│   ├── desktop/              # Electron desktop application
│   └── mcp-server/           # MCP server (HTTP/SSE transport)
│
├── packages/
│   ├── faceswap-core/        # TypeScript wrapper for FaceFusion
│   ├── video-processor/      # FFmpeg wrapper (GIF ↔ MP4)
│   ├── api-client/           # Giphy API client (search + trending, with localStorage/IPC/env fallback chain)
│   └── i18n/                 # Shared translations (EN/FR)
│
├── website/                  # Landing page (GitHub Pages)
│
├── scripts/
│   └── setup-facefusion.mjs  # FaceFusion one-time installer (CLI wrapper around @meme-swap/installer-core)
│
├── docs/
│   ├── architecture.md       # Detailed architecture notes
│   ├── development.md        # Local development guide
│   └── adr/                  # Architecture Decision Records
│
├── .github/workflows/        # CI — auto-deploys website/ to GitHub Pages
├── turbo.json                # Turborepo pipeline
└── pnpm-workspace.yaml       # pnpm workspace config

Note: FaceFusion is installed globally at ~/.meme-swap/facefusion/ and is never bundled inside the repo. All apps resolve it from that path at runtime. Deleting ~/.meme-swap/ removes every model, cache and result.

Grab the latest .dmg (Apple Silicon) from the Releases page, open it and drag Meme Swap.app into Applications. The guided first-run setup installs FaceFusion into ~/.meme-swap/ for you.

The build has no Apple Developer ID (that's a paid Apple program), so it is only ad-hoc signed and not notarized. On first launch macOS will block it with a message like "Apple could not verify 'Meme Swap' is free of malware." This is expected — the app is safe, macOS just can't verify an unnotarized developer. To allow it:

1. Try to open Meme Swap.app once (double-click) — you'll get the warning. Click Done.
2. Open System Settings → Privacy & Security.
3. Scroll down to the Security section — you'll see ""Meme Swap" was blocked to protect your Mac."
4. Click Open Anyway, then confirm with your password or Touch ID.

macOS remembers this, so subsequent launches open normally.

xattr -cr "/Applications/Meme Swap.app"

# 1. Clone & install the monorepo
git clone https://github.com/Tlahey/meme-swap.git && cd meme-swap
pnpm install

# 2. One-time: install FaceFusion + Python venv into ~/.meme-swap
pnpm install:facefusion

# 3. Configure environment (optional)
cp .env.example .env.local

# 4. Build all packages
pnpm build

pnpm frontend:dev
# → http://localhost:3010

pnpm desktop:dev

pnpm build            # 1. Build all shared packages
pnpm desktop:build    # 2. Compile the desktop TypeScript + copy assets
pnpm desktop:package  # 3. Package into a .dmg via electron-builder

The .dmg is output to apps/desktop/dist/. Double-click it to install Meme Swap.app into your Applications folder.

Note: gatekeeperAssess is disabled in the build config, so macOS may show an unverified developer warning. Right-click → Open to bypass it, or sign the app with an Apple Developer certificate.

# Build first
pnpm build --filter=mcp-server

# Start
cd apps/mcp-server && pnpm start
# → http://localhost:3001

To use the MCP server with an AI client (e.g. Cursor), add to your MCP config:

{
  "mcpServers": {
    "meme-swap": {
      "command": "node",
      "args": ["<absolute-path>/apps/mcp-server/build/index.js"]
    }
  }
}

Available MCP tools:

• run_faceswap — perform a face swap given a source image and target media path

See apps/mcp-server/README.md for the full API reference.

TypeScript wrapper around the FaceFusion Python CLI.

import { runFaceSwap } from '@meme-swap/faceswap-core';

const result = await runFaceSwap({
  sourcePath: './face.jpg',
  targetPath: './target.mp4',
  outputPath: './output.mp4',
  executionProviders: ['coreml', 'cpu'], // Apple Silicon
  faceSwapperModel: 'inswapper_128_fp16',
  faceEnhancerModel: 'codeformer',
  threadCount: 4,
  logLevel: 'info',
  onProgress: ({ step, percent }) => console.log(step, percent),
});

if (result.success) {
  console.log('Output:', result.outputPath);
}

FFmpeg wrapper for format conversion.

import { gifToMp4, mp4ToGif } from '@meme-swap/video-processor';

// GIF → MP4 (required before running FaceFusion)
await gifToMp4({ inputPath: './input.gif', outputPath: './input.mp4' });

// MP4 → GIF (for final output)
await mp4ToGif({
  inputPath: './output.mp4',
  outputPath: './output.gif',
  fps: 10,
  maxWidth: 480,
});

Copy .env.example to .env.local and configure:

# Optional — used by the Giphy API client for GIF search; falls back to a curated GIF list if unset
GIPHY_API_KEY=your_key_here

# FaceFusion execution providers (default: coreml,cpu on Apple Silicon)
FACEFUSION_EXECUTION_PROVIDERS=coreml,cpu

# Thread count for FaceFusion (default: auto-detected)
FACEFUSION_THREAD_COUNT=8

# Port for the web frontend dev server
PORT=3010

The project landing page lives in website/ and is deployed automatically to tlahey.github.io/meme-swap by the deploy-pages GitHub Actions workflow on every push to main that touches website/**.

One-time setup: in the repo settings, set Settings → Pages → Source to GitHub Actions.

More docs:

• docs/FEATURES.md — summary of what the app can do
• docs/architecture.md — detailed architecture notes
• docs/development.md — local development guide
• docs/adr/ — Architecture Decision Records

Meme Swap is free, open-source, and built in my spare time. If it's useful to you, consider sponsoring on GitHub — it helps keep the project maintained and moving forward.

See CONTRIBUTING.md for the full guide.

Quick summary:

1. Fork the repo and create a branch: feature/<name> or fix/<name>
2. Follow the code style rules — TypeScript strict mode, named exports, async/await
3. Open a pull request with a clear description

Meme Swap is built for entertainment and creative use. Always get consent before swapping someone's face, and never use it to deceive, impersonate or harm anyone. You are responsible for the content you create.

MIT © Tlahey

• FaceFusion — AI face manipulation platform
• InsightFace — inswapper face swap model
• CodeFormer — face restoration
• Real-ESRGAN — super-resolution
• FFmpeg — media conversion