The Main Character Files

Appearance

Getting Started ​

Prerequisites ​

  • Bun >= 1.0
  • FFmpeg (system-installed)
  • CMake + build tools (for native ONNX deps)
  • A local LLM endpoint (e.g. Ollama + LiteLLM) if using the messages video format

Installation ​

bash
git clone https://github.com/tadeasf/themaincharacterfiles.git
cd themaincharacterfiles
bun install

Configuration ​

bash
cp .env.example .env

Edit .env with your settings. See the Configuration guide for all options.

At minimum, set:

  • TARGET_SUBREDDITS — which subreddits to scrape
  • VIDEO_FORMAT — classic (narrated) or messages (iMessage style)
  • TIKTOK_EMAIL / TIKTOK_PASSWORD — for publishing

TikTok Login ​

First-time setup requires interactive browser login to solve the CAPTCHA:

bash
BROWSER_HEADLESS=false bun run scripts/tiktok-login.ts

Session state is saved to ./data/browser-state/ and reused on subsequent runs.

Running ​

Development ​

bash
bun run dev

Opens http://localhost:3000/dashboard for the monitoring UI.

Production ​

bash
bun run build
bun run start

Testing a Pipeline Run ​

Use the e2e scripts to verify your setup:

bash
# Video generation only (no publish)
bun run scripts/e2e-video-test.ts

# Full pipeline including TikTok publish
bun run scripts/e2e-pipeline-test.ts

Both scripts prompt you to choose between classic and messages pipeline formats.

Project Structure ​

src/
├── app.module.ts          # Root NestJS module
├── main.ts                # Bootstrap
├── config/                # Zod-validated configuration
├── common/                # Shared types, utils, filters
└── modules/
    ├── browser/           # Camoufox lifecycle
    ├── dashboard/         # Monitoring UI + API
    ├── health/            # Health check endpoints
    ├── llm/               # LLM conversation rewriting
    ├── message-renderer/  # iMessage-style video rendering
    ├── pipeline/          # Orchestrator + scheduler
    ├── publisher/         # TikTok upload automation
    ├── reddit/            # Reddit scraping
    ├── storage/           # SQLite persistence
    ├── tts/               # Kokoro TTS + Whisper alignment
    └── video/             # FFmpeg video composition

Built with VitePress