{"id":50145096,"url":"https://github.com/jurczykpawel/reelstack","last_synced_at":"2026-05-24T03:34:09.925Z","repository":{"id":339994924,"uuid":"1164094225","full_name":"jurczykpawel/reelstack","owner":"jurczykpawel","description":"Programmatic video pipeline — generate reels and social media images from text. Self-hostable, API-first, open source.","archived":false,"fork":false,"pushed_at":"2026-05-17T19:15:30.000Z","size":14581,"stargazers_count":3,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T03:34:01.425Z","etag":null,"topics":["bun","ffmpeg","image-generation","monorepo","nextjs","open-source","playwright","prisma","react","self-hosted","social-media","srt","subtitle","subtitles","typescript","video","video-editing"],"latest_commit_sha":null,"homepage":"https://reelstack.sellf.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jurczykpawel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-22T16:23:56.000Z","updated_at":"2026-05-20T11:53:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jurczykpawel/reelstack","commit_stats":null,"previous_names":["jurczykpawel/subtitle-burner","jurczykpawel/reelstack"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jurczykpawel/reelstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jurczykpawel%2Freelstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jurczykpawel%2Freelstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jurczykpawel%2Freelstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jurczykpawel%2Freelstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jurczykpawel","download_url":"https://codeload.github.com/jurczykpawel/reelstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jurczykpawel%2Freelstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33420660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","ffmpeg","image-generation","monorepo","nextjs","open-source","playwright","prisma","react","self-hosted","social-media","srt","subtitle","subtitles","typescript","video","video-editing"],"created_at":"2026-05-24T03:34:09.075Z","updated_at":"2026-05-24T03:34:09.912Z","avatar_url":"https://github.com/jurczykpawel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ReelStack\n\n**Programmatic video pipeline. Generate reels, YouTube videos, and captioned content from text. 40+ AI tools, CLI pipeline, self-hostable, API-first, no vendor lock-in.**\n\n[![CI](https://github.com/jurczykpawel/reelstack/actions/workflows/ci.yml/badge.svg)](https://github.com/jurczykpawel/reelstack/actions/workflows/ci.yml)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n[![Status: Beta](https://img.shields.io/badge/Status-Beta-orange.svg)](https://github.com/jurczykpawel/reelstack)\n[![Open Source](https://img.shields.io/badge/Open%20Source-100%25-brightgreen.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen.svg)](docs/CONTRIBUTING.md)\n\n[Live Demo](https://reelstack.sellf.app) | [Documentation](docs/) | [Pipeline Guide](docs/REEL_PIPELINE.md) | [Modules](docs/MODULES.md) | [API Reference](#public-api-v1) | [Report Bug](https://github.com/jurczykpawel/reelstack/issues)\n\n\u003c/div\u003e\n\n---\n\n## Demo Reels\n\nGenerated entirely by ReelStack. No editing software, no designer, just one API call.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=QSM9JQevxjw\"\u003e\u003cimg src=\"docs/assets/demo-meta-preview.gif\" width=\"200\" alt=\"AI Video Automation\"/\u003e\u003c/a\u003e\u003cbr/\u003e\n\u003cb\u003eAI Video Automation\u003c/b\u003e\u003cbr/\u003e\n\u003csub\u003etip-card + karaoke captions\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=fE48rRCLx7Y\"\u003e\u003cimg src=\"docs/assets/demo-science-preview.gif\" width=\"200\" alt=\"Science Facts\"/\u003e\u003c/a\u003e\u003cbr/\u003e\n\u003cb\u003eScience Facts\u003c/b\u003e\u003cbr/\u003e\n\u003csub\u003equote-card + single-word mode\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=pzi6JYb3Icc\"\u003e\u003cimg src=\"docs/assets/demo-iphone-preview.gif\" width=\"200\" alt=\"iPhone Tips\"/\u003e\u003c/a\u003e\u003cbr/\u003e\n\u003cb\u003eiPhone Tips\u003c/b\u003e\u003cbr/\u003e\n\u003csub\u003etip-card + karaoke captions\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e Click any preview to watch the full reel on YouTube.\n\n### Image Generator\n\nReelStack also generates standalone branded images for social media. No video required. Upload your brand CSS, pick a template and size, get a pixel-perfect PNG.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSee examples\u003c/b\u003e, 12 templates, 3 sizes, 2 built-in brands\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n**Dark theme** (`example` brand)\n\n| Post (1080x1080)                                              | Story (1080x1920)                                              | YouTube (1280x720)                                               |\n| ------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |\n| \u003cimg src=\"docs/assets/covers/dark-tip-post.png\" width=\"200\"/\u003e | \u003cimg src=\"docs/assets/covers/dark-tip-story.png\" width=\"120\"/\u003e | \u003cimg src=\"docs/assets/covers/dark-tip-youtube.png\" width=\"240\"/\u003e |\n| tip-card                                                      | tip-card                                                       | tip-card                                                         |\n\n**Light theme** (`example-light` brand)\n\n| Post (1080x1080)                                                 | Story (1080x1920)                                                 | YouTube (1280x720)                                                  |\n| ---------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |\n| \u003cimg src=\"docs/assets/covers/light-quote-post.png\" width=\"200\"/\u003e | \u003cimg src=\"docs/assets/covers/light-quote-story.png\" width=\"120\"/\u003e | \u003cimg src=\"docs/assets/covers/light-quote-youtube.png\" width=\"240\"/\u003e |\n| quote-card                                                       | quote-card                                                        | quote-card                                                          |\n\n**More templates:** ad-card, announcement, webinar-cover, webinar-point, webinar-cta-slide, webinar-countdown, webinar-lastcall, webinar-myth, webinar-program, webinar-question\n\n**Standalone image server:** `apps/image-gen-server`. One `docker compose up` for a self-hosted image API.\n\n\u003c/details\u003e\n\n---\n\n## Why ReelStack?\n\nMost video tools are either closed-source SaaS products with usage limits, or scattered scripts requiring manual assembly. ReelStack is a complete pipeline:\n\n- **Script to reel in seconds.** Write text, get a finished video with voiceover, karaoke captions, transitions, and effects\n- **40+ AI tools across 10+ providers.** AI video (Veo 3.1, Seedance, Kling), AI images (NanoBanana, Flux, Ideogram), stock footage (Pexels), avatars (HeyGen)\n- **CLI pipeline for step-by-step production.** Run each stage independently: TTS, plan, assets, assemble, render\n- **AI Director (Claude) for automated shot planning.** Selects tools, plans shots, writes prompts, reviews quality\n- **Configurable prompt system.** All LLM prompts are editable markdown templates. No code changes needed\n- **Transparent avatar overlay.** Greenscreen or background removal for talking-head-over-content layouts\n- **Asset management.** Regenerate or replace individual shots without re-running the whole pipeline\n- **11 composable effects.** Text cards, B-roll cutaways, punch-in zoom, highlight boxes, animated counters, lower thirds, CTAs, PiP, and more\n- **Two output formats.** 9:16 reels (Instagram/TikTok/Shorts) and 16:9 YouTube videos with the same effect library\n- **Real karaoke captions.** TTS voiceover + whisper.cpp word-level timestamps = pixel-accurate word-by-word highlighting\n- **API-first.** REST API with auth, rate limiting, and scoped permissions. Automate from your app or n8n workflow\n- **Fully self-hostable.** Deploy on your own VPS with Docker. Your data, your infrastructure\n\n### What It Does\n\nReelStack is a programmatic video pipeline. You provide a script (or video + subtitles), configure effects and style, and the pipeline generates a finished MP4: text-to-speech voiceover, whisper-based word timestamps, karaoke captions, B-roll transitions, overlays, and more. It includes a web app with wizard UI, dashboard, and REST API.\n\n### Who It's For\n\n- **Content creators** who want to generate reels and YouTube clips from scripts without editing software\n- **Developers** who need programmatic video rendering via API or CLI\n- **Agencies** who produce video content at scale with batch rendering\n- **Educators** who teach video production with code\n\n### Alternative To\n\nReelStack replaces manual editing workflows in tools like **Kapwing**, **Descript**, **VEED.io**, **Opus Clip**, or scattered **FFmpeg** scripts, with a single self-hosted pipeline.\n\n---\n\n## ReelStack + HeyGen, Veo, Seedance\n\nReelStack is the production pipeline. HeyGen, Veo, Seedance, and other AI tools are the content generators. ReelStack orchestrates them.\n\nInstead of competing with AI video platforms, ReelStack integrates them into a unified production workflow. You get the best of both worlds: AI-generated content (avatars, B-roll, images) with full pipeline control (timing, transitions, captions, effects, branding).\n\n|                          | AI Video SaaS alone                                  | ReelStack (orchestrating AI tools)                                       |\n| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------ |\n| **Control**              | Prompt in, video out. No timeline, no pacing control | Full programmatic control. Templates, effects, frame-level precision     |\n| **Tool choice**          | Locked to one platform's models                      | 40+ tools across 10+ providers. Swap freely per shot                     |\n| **Avatar support**       | Platform-specific avatars only                       | HeyGen Avatar III/IV/V + transparent overlay on any content              |\n| **Cost at scale**        | $1-5+ per reel (credit-based, credits expire)        | ~$0.10-0.50 per reel (self-hosted TTS + Remotion Lambda)                 |\n| **Automation**           | Limited API, no webhook pipeline                     | REST API + BullMQ + CLI + n8n webhooks. Zero-click batch production      |\n| **Data ownership**       | Your assets, their servers                           | Your infrastructure, your storage, your data. AGPL-3.0                   |\n| **Customization**        | Choose from their templates                          | Build your own Remotion compositions in React. 11 effects, 5 transitions |\n| **Offline / air-gapped** | Requires internet, their servers                     | Runs on a Raspberry Pi if you want                                       |\n\n### When to use AI Video SaaS directly\n\nIf all you need is a quick avatar video and you do not care about pipeline automation, tools like HeyGen are great standalone. ReelStack adds value when you need batch production, brand consistency, multi-tool orchestration, or cost predictability.\n\n\u003e ReelStack is video infrastructure. AI video tools are content engines. ReelStack connects them into a production line.\n\n---\n\n## CLI Pipeline\n\nReelStack includes a step-by-step CLI for local reel production. Each stage outputs a JSON file consumed by the next.\n\n### Pipeline A: Voiceover (TTS generates audio)\n\n```bash\nbun run rs tts \"Your script text here\"\nbun run rs plan out/tts.json\nbun run rs assets out/plan.json\nbun run rs assemble out/plan.json out/tts.json\nbun run rs render out/composition.json\n```\n\n### Pipeline B: HeyGen avatar (audio from talking head)\n\n```bash\nbun run rs heygen \"Your script text here\"\nbun run rs transcribe out/heygen.mp4\nbun run rs plan out/tts.json --director\nbun run rs assets out/plan.json\nbun run rs assemble out/plan.json out/tts.json\nbun run rs render out/composition.json\n```\n\nEach step can be re-run independently. Replace a single asset with `bun run rs regen \u003cshot-id\u003e` or `bun run rs replace \u003cshot-id\u003e \u003cfile\u003e`.\n\nFor full CLI reference, see [PRODUCTION-GUIDE.md](PRODUCTION-GUIDE.md).\n\n---\n\n## Tool Registry\n\nReelStack auto-discovers 40+ AI tools across 10+ providers based on which API keys are configured.\n\n| Category        | Providers                                                                      | Example tools                             |\n| --------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |\n| **AI Video**    | fal.ai, KIE, PiAPI, AIML, WaveSpeed, Replicate, Runway, Minimax, Google Vertex | Veo 3.1, Seedance 2.0, Kling, Wan, Hailuo |\n| **AI Images**   | fal.ai, KIE, WaveSpeed, Replicate                                              | NanoBanana, Flux, Ideogram, Recraft       |\n| **Stock**       | Pexels                                                                         | Stock footage search                      |\n| **Avatars**     | HeyGen                                                                         | Avatar III, IV, V                         |\n| **Self-hosted** | RunPod                                                                         | HuMo avatar                               |\n\nAdding a new model is one config object in the provider file. No other files need changes. See [PRODUCTION-GUIDE.md](PRODUCTION-GUIDE.md#adding-a-new-model) for details.\n\nEach tool has an editable markdown prompt guideline in `packages/agent/src/prompts/guidelines/`. The AI Director uses these when writing generation prompts.\n\n---\n\n## Features\n\n### Reel \u0026 YouTube Pipeline\n\n- **Script to video.** Write text, generate voiceover (Edge TTS / ElevenLabs / OpenAI), auto-caption with whisper.cpp, render with Remotion\n- **Two compositions.** 9:16 vertical reels and 16:9 horizontal YouTube, sharing the same effect library\n- **Karaoke captions.** Word-by-word highlighting with real whisper.cpp word-level timestamps\n- **11 composable effects.** Text cards, B-roll cutaways, punch-in zoom, highlight boxes, animated counters, lower thirds, CTAs, PiP, chapter cards, progress bar\n- **5 transition types.** Crossfade, slide-left, slide-right, zoom-in, wipe\n\n### AI Director \u0026 Tool Orchestration\n\n- **AI Director (Claude).** Automated shot planning: selects tools, plans B-roll, writes generation prompts, reviews quality\n- **40+ AI tools.** Video generation, image generation, stock footage, avatars. Auto-discovered from environment\n- **Configurable prompt system.** All LLM prompts are editable markdown files. Modify planning behavior without code changes\n- **Transparent avatar overlay.** Greenscreen chromakey or native background removal for talking-head-over-content layouts\n- **Asset management.** Regenerate or replace individual shots. Swap tools per shot\n\n### Subtitle Editor\n\n- **Visual timeline editor.** Drag and resize subtitle blocks with snap-to-grid\n- **8 built-in templates.** Classic, Cinematic, Bold Box, Modern, Minimal Top, Neon, Yellow Box, Typewriter\n- **Full style control.** Font family, size, color, outline, shadow, position, alignment\n- **SRT import/export.** Load existing subtitle files, edit visually, export back to SRT\n\n### Rendering\n\n- **Remotion-based.** React compositions rendered to MP4 with @remotion/renderer\n- **Remotion Lambda.** AWS serverless rendering for fast, scalable output\n- **Client-side rendering.** FFmpeg.wasm for subtitle burning in the browser\n- **Server-side rendering.** Queue jobs to server with BullMQ for longer videos\n- **3 render presets.** Speed, balanced, and quality modes\n\n### Public API v1\n\n- **REST API** with API key authentication (`Authorization: Bearer rs_...`)\n- **Reel pipeline endpoint.** POST /api/v1/reel/generate with script, TTS config, style\n- **Full CRUD.** Render jobs, projects, templates, API keys\n- **Zod-validated** requests and responses\n\n### Monetization\n\n- **Sellf webhook integration.** Tier upgrades (Free/Pro/Enterprise) and token purchases\n- **Token system.** Render credits with daily limits per tier + purchasable token packs\n- **API key scoping.** Granular permissions (render, reel, publish, templates, projects)\n\n### Self-Hosting\n\n- **Docker deployment.** PostgreSQL, Redis, MinIO, all in Docker Compose\n- **Cloud deployment.** Vercel + Supabase + Inngest alternative\n- **No vendor lock-in.** Swap storage or queue backends without code changes\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n| Requirement                               | Version                        |\n| ----------------------------------------- | ------------------------------ |\n| [Bun](https://bun.sh/)                    | 1.3+                           |\n| [Node.js](https://nodejs.org/)            | 20+                            |\n| [PostgreSQL](https://www.postgresql.org/) | 15+ (or use Docker)            |\n| OS                                        | macOS, Linux, or Windows (WSL) |\n\n### Run Locally (Docker, one command)\n\nThe fastest path: everything in Docker, hot-reload, sign in without SMTP.\n\n```bash\ngit clone https://github.com/jurczykpawel/reelstack.git\ncd reelstack\nbin/dev-up.sh                 # first run creates .env.dev, re-run after editing\n```\n\nWhat this starts:\n\n- Postgres, Redis, MinIO (S3-compatible storage) — all with auto-setup\n- `web` (Next.js) on `http://localhost:3001`\n- `worker` (reel pipeline) with hot reload from mounted source\n\nOn first run the script prints the path to `.env.dev`. Open it and add at least:\n\n```env\nANTHROPIC_API_KEY=sk-ant-...   # required — Claude plans the video\nOPENAI_API_KEY=sk-...          # required — Whisper transcribes for captions\n```\n\nThen re-run `bin/dev-up.sh`. Open `http://localhost:3001/login` and click **“Dev login”** to sign in with any email. No password, no SMTP.\n\nReset the environment (drop DB + storage): `docker compose -f docker-compose.dev.yml down -v`.\n\n### Run Locally (bare metal, no Docker)\n\nIf you prefer running Next.js on the host:\n\n```bash\nbun install\ndocker compose up -d postgres redis minio       # infra only\nbunx prisma db push --schema=packages/database/prisma/schema.prisma\nbun run dev                                     # web\nbun run worker --filter web                     # second terminal\n```\n\nSet `ALLOW_DEV_LOGIN=1` and `NEXT_PUBLIC_ALLOW_DEV_LOGIN=1` in `apps/web/.env` for the Dev login button.\n\n### Build for Production\n\n```bash\nbun run build\n```\n\nFor full deployment instructions:\n\n- **VPS (Docker)**: See [Self-host guide](docs/DEPLOYMENT_VPS.md). PostgreSQL, Redis, MinIO, all in Docker\n- **Cloud (Vercel)**: See [Vercel + Supabase guide](docs/DEPLOYMENT_CLOUD.md). Vercel for app, Supabase for storage, Inngest for queue\n\n---\n\n## Tech Stack\n\n| Layer                | Technology                                                                                                                                                                     | Role                                                                                                                                                                        |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Framework**        | [Next.js 16](https://nextjs.org/) (App Router)                                                                                                                                 | Server-side rendering, API routes, file-based routing                                                                                                                       |\n| **Language**         | [TypeScript](https://www.typescriptlang.org/)                                                                                                                                  | Type safety across all packages                                                                                                                                             |\n| **UI**               | [React 19](https://react.dev/)                                                                                                                                                 | Component framework                                                                                                                                                         |\n| **Styling**          | [Tailwind CSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/)                                                                                                 | Utility-first CSS with accessible component library                                                                                                                         |\n| **State**            | [Zustand](https://zustand-demo.pmnd.rs/)                                                                                                                                       | 4 client-side stores (project, engine, timeline, UI)                                                                                                                        |\n| **Auth**             | [Auth.js](https://authjs.dev/) (NextAuth v5)                                                                                                                                   | Email/password + magic links, JWT sessions                                                                                                                                  |\n| **Database**         | [PostgreSQL](https://www.postgresql.org/) + [Prisma ORM](https://www.prisma.io/)                                                                                               | Relational storage with type-safe queries                                                                                                                                   |\n| **Storage**          | [MinIO](https://min.io/) / [Supabase Storage](https://supabase.com/storage)                                                                                                    | Video and rendered file storage (adapter pattern)                                                                                                                           |\n| **Queue**            | [BullMQ](https://docs.bullmq.io/) + [Redis](https://redis.io/) / [Inngest](https://www.inngest.com/)                                                                           | Background render job processing (adapter pattern)                                                                                                                          |\n| **Client Rendering** | [FFmpeg.wasm](https://ffmpegwasm.netlify.app/)                                                                                                                                 | In-browser video processing via WebAssembly                                                                                                                                 |\n| **Server Rendering** | [Remotion](https://www.remotion.dev/) + [Remotion Lambda](https://www.remotion.dev/lambda)                                                                                     | React-based video rendering, local or AWS Lambda                                                                                                                            |\n| **Transcription**    | [whisper.cpp](https://github.com/ggerganov/whisper.cpp) / [Transformers.js](https://huggingface.co/docs/transformers.js/)                                                      | Word-level timestamps for karaoke captions                                                                                                                                  |\n| **AI Orchestration** | [Claude](https://www.anthropic.com/) (Opus/Sonnet/Haiku)                                                                                                                       | Shot planning, prompt expansion, quality review                                                                                                                             |\n| **TTS**              | [Gemini Flash TTS](https://ai.google.dev/) / [Edge TTS](https://github.com/niconiahi/edge-tts) / [ElevenLabs](https://elevenlabs.io/) / [OpenAI](https://platform.openai.com/) | Text-to-speech voiceover. Server-side resolver auto-picks the best provider from env (`GEMINI_API_KEY` \u003e `ELEVENLABS_API_KEY` \u003e `OPENAI_API_KEY` \u003e free edge-tts fallback). |\n| **Monorepo**         | [Turborepo](https://turbo.build/) + [Bun](https://bun.sh/) workspaces                                                                                                          | Build orchestration and dependency management                                                                                                                               |\n| **Testing**          | [Vitest](https://vitest.dev/) + [Playwright](https://playwright.dev/)                                                                                                          | 1200+ unit tests + E2E tests                                                                                                                                                |\n\n---\n\n## Architecture\n\n### Directory Structure\n\n```\nreelstack/\n├── apps/web/                  # Next.js application\n│   ├── src/\n│   │   ├── app/               # Pages \u0026 API routes (internal + v1)\n│   │   ├── components/        # React components (editor, timeline, video, UI)\n│   │   ├── lib/               # Auth, API helpers, bridges, hooks\n│   │   └── store/             # Zustand state management (4 stores)\n│   ├── worker/                # BullMQ render worker (standalone process)\n│   └── e2e/                   # Playwright E2E tests\n├── packages/\n│   ├── agent/                 # LLM planning, tool registry, CLI, orchestration\n│   ├── types/                 # Shared TypeScript interfaces\n│   ├── core/                  # Engines, action system, serializer, templates\n│   ├── remotion/              # Remotion compositions + video components\n│   ├── tts/                   # Text-to-speech (Edge TTS, ElevenLabs, OpenAI)\n│   ├── transcription/         # whisper.cpp wrapper + word grouping\n│   ├── ffmpeg/                # SRT parser, ASS generator, time utils\n│   ├── database/              # Prisma schema + query helpers\n│   ├── queue/                 # Queue adapters (Inngest, BullMQ)\n│   ├── storage/               # Storage adapters (Supabase, MinIO, R2)\n│   └── modules/               # Module system (private extensions)\n├── docker/                    # Dockerfiles + nginx config\n├── scripts/                   # Setup scripts\n└── docs/                      # Documentation\n```\n\n### Key Packages\n\n| Package                      | Purpose                                                                                                                                                                                                                               |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`packages/agent`**         | LLM-powered planning (AI Director), 40+ tool registry, CLI pipeline, prompt system (editable markdown), orchestration, supervisor. The brain of the reel pipeline.                                                                    |\n| **`packages/remotion`**      | Remotion compositions (Reel 9:16, YouTubeLongForm 16:9), 11 effect components (ZoomEffect, AnimatedCounter, HighlightBox, ChapterCard, etc.), schemas, and rendering helpers. See [COMPOSITION.md](packages/remotion/COMPOSITION.md). |\n| **`packages/tts`**           | Text-to-speech providers: Edge TTS (free), ElevenLabs, OpenAI. Unified interface for synthesis.                                                                                                                                       |\n| **`packages/transcription`** | whisper.cpp integration, audio normalization, BPE token merging, word-to-cue grouping. Produces karaoke-ready cues.                                                                                                                   |\n| **`packages/core`**          | Pure-function engines (SubtitleEngine, TemplateEngine, RenderEngine, ActionSystem, ProjectSerializer).                                                                                                                                |\n| **`packages/ffmpeg`**        | SRT parser, ASS generator (including karaoke timing tags), time-format utilities.                                                                                                                                                     |\n| **`packages/database`**      | Prisma schema (User, Video, RenderJob, ReelJob, Template, ApiKey, TokenTransaction, etc.) + query helpers.                                                                                                                            |\n| **`packages/queue`**         | Adapter: auto-detects Inngest (cloud) or BullMQ (VPS).                                                                                                                                                                                |\n| **`packages/storage`**       | Adapter: auto-detects Supabase Storage (cloud), MinIO (VPS), or Cloudflare R2.                                                                                                                                                        |\n| **`packages/types`**         | Shared TypeScript interfaces and API scope constants.                                                                                                                                                                                 |\n\nFor full architecture details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). For the reel generation pipeline, see [docs/REEL_PIPELINE.md](docs/REEL_PIPELINE.md).\n\n---\n\n## Usage\n\n### Local Mode (No Account Required)\n\n1. Open the app at `http://localhost:3000`\n2. Drop a video file (**MP4**, **WebM**, **MOV**, **MKV**, up to 500 MB)\n3. Add subtitles with the **+ Add Subtitle** button or import an **SRT** file\n4. Edit text, timing, and style in the right panel\n5. Use the timeline to drag and resize subtitle blocks\n6. Click **Render** then **Browser** to burn subtitles client-side\n7. Download the rendered video\n\n### Dashboard Mode (With Account)\n\n1. Sign up or sign in at `/login`\n2. Upload videos from the dashboard. They are stored in cloud/MinIO storage\n3. Edit subtitles. Changes auto-save every 2 seconds\n4. Render using **Server** mode for faster processing of long videos\n5. Download rendered videos from the dashboard\n\n### Keyboard Shortcuts\n\n| Key                    | Action                          |\n| ---------------------- | ------------------------------- |\n| `Space`                | Play / Pause                    |\n| `Left Arrow`           | Seek back 0.1s (`Shift`: 1s)    |\n| `Right Arrow`          | Seek forward 0.1s (`Shift`: 1s) |\n| `Delete` / `Backspace` | Remove selected subtitle        |\n\n### SRT Workflow\n\n1. Click **Import SRT** in the toolbar to load existing subtitles\n2. Edit timing and text visually\n3. Click **Export SRT** to save the result\n\n### API Usage Examples\n\nThe public API uses API key authentication. Generate a key from the dashboard or via the API.\n\n```bash\n# Create a render job\ncurl -X POST https://your-instance.com/api/v1/render \\\n  -H \"Authorization: Bearer rs_live_your_api_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"videoId\": \"uuid\", \"style\": { \"fontFamily\": \"Arial\", \"fontSize\": 48 }, \"cues\": [...] }'\n\n# Check render status\ncurl https://your-instance.com/api/v1/render/job-uuid \\\n  -H \"Authorization: Bearer rs_live_your_api_key\"\n\n# Download rendered video\ncurl -L https://your-instance.com/api/v1/render/job-uuid/download \\\n  -H \"Authorization: Bearer rs_live_your_api_key\" -o output.mp4\n```\n\nFor the full list of 21 API endpoints, see the [API Routes section in ARCHITECTURE.md](docs/ARCHITECTURE.md#public-api-v1).\n\n---\n\n## Development Commands\n\n```bash\nbun install                # Install all dependencies\nbun run dev                # Start dev server (http://localhost:3000)\nbun run build              # Production build\nbun run test               # Run all tests (1200+ across agent, remotion, and web)\nbun run lint               # Lint all packages\nbun run format             # Format with Prettier\nbun run format:check       # Check formatting without writing\n```\n\n---\n\n## Environment Variables\n\n| Variable                      | Required | Description                                                  |\n| ----------------------------- | -------- | ------------------------------------------------------------ |\n| `AUTH_SECRET`                 | Yes      | Random secret for JWT signing (`openssl rand -base64 32`)    |\n| `DATABASE_URL`                | Yes      | PostgreSQL connection string                                 |\n| `SMTP_HOST`                   | No       | SMTP server for magic link emails                            |\n| `SMTP_PORT`                   | No       | SMTP port (default: 587)                                     |\n| `SMTP_USER`                   | No       | SMTP username                                                |\n| `SMTP_PASS`                   | No       | SMTP password                                                |\n| `EMAIL_FROM`                  | No       | From address for emails                                      |\n| `REDIS_URL`                   | No       | Redis for BullMQ (VPS mode)                                  |\n| `MINIO_ENDPOINT`              | No       | MinIO endpoint (VPS mode)                                    |\n| `MINIO_ACCESS_KEY`            | No       | MinIO access key                                             |\n| `MINIO_SECRET_KEY`            | No       | MinIO secret key                                             |\n| `MINIO_BUCKET`                | No       | MinIO bucket name                                            |\n| `NEXT_PUBLIC_FFMPEG_CORE_URL` | No       | Custom CDN base URL for FFmpeg WASM core (defaults to unpkg) |\n| `NEXT_PUBLIC_SUPABASE_URL`    | No       | Supabase URL (cloud mode, storage only)                      |\n| `SUPABASE_SERVICE_ROLE_KEY`   | No       | Supabase service key (cloud mode)                            |\n\n---\n\n## Roadmap\n\nSee **[docs/ROADMAP.md](docs/ROADMAP.md)** for the full roadmap with phase details.\n\n### Completed\n\n- [x] Visual timeline editor with drag and resize\n- [x] 8 built-in subtitle templates, 6 caption animation styles\n- [x] Client-side + server-side rendering (FFmpeg.wasm / BullMQ)\n- [x] Auto-transcription with in-browser Whisper\n- [x] Public REST API v1 (21 endpoints)\n- [x] Remotion-based reel rendering (React video compositions)\n- [x] TTS voiceover (Edge TTS / ElevenLabs / OpenAI) + Whisper word alignment\n- [x] Remotion Lambda renderer (AWS serverless)\n- [x] AI Director (Claude) with 40+ tools across 10+ providers\n- [x] CLI pipeline (tts, plan, assets, assemble, render)\n- [x] HeyGen Avatar integration (III/IV/V)\n- [x] Transparent avatar overlay (greenscreen + native background removal)\n- [x] Reel creation API + Postiz multi-platform publishing\n- [x] Sellf payment webhook (tier upgrades + token packs)\n- [x] Docker deployment with optional reel-worker (Chromium + pre-bundled Remotion)\n- [x] 1200+ tests across agent, remotion, and web packages\n\n### Planned\n\n- [ ] Web UI reel editor (wizard, preview, publish flow)\n- [ ] Multi-language subtitle tracks\n- [ ] Batch reel rendering via API\n- [ ] Custom font uploads\n- [ ] GPU-accelerated server rendering\n\n---\n\n## Premium Modules\n\nReelStack is fully open source (AGPL-3.0). Premium montage templates and effects are available as optional closed-source modules for commercial use.\n\n---\n\n## Contributing\n\nContributions are welcome and appreciated. There are many ways to help:\n\n- **Report bugs.** Open an [issue](https://github.com/jurczykpawel/reelstack/issues) with steps to reproduce\n- **Suggest features.** Start a [discussion](https://github.com/jurczykpawel/reelstack/discussions) or open an issue tagged `enhancement`\n- **Submit pull requests.** Bug fixes, new features, documentation improvements\n- **Improve tests.** The project has 1200+ tests but more coverage is always welcome\n- **Write documentation.** Tutorials, guides, or translations\n\nPlease read **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)** for development setup, code style guidelines, commit conventions, and the PR process.\n\n---\n\n## License\n\nThis project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See the [LICENSE](LICENSE) file for details.\n\n### Security and Privacy\n\nReelStack can process user-uploaded video files and stores user accounts identified by email. Login is passwordless (magic link only). If you self-host this application:\n\n- Review the [SECURITY.md](SECURITY.md) file for the security policy and vulnerability reporting process\n- All video files are stored in your configured storage backend (MinIO, R2, or Supabase). No data is sent to third parties\n- Client-side rendering processes video entirely in the browser. The file never leaves the user's device\n- API keys are stored as SHA-256 hashes, never in plaintext\n- All database queries are scoped to the authenticated user (application-level row security)\n\n---\n\n## Support\n\n- **Bug reports and feature requests.** [GitHub Issues](https://github.com/jurczykpawel/reelstack/issues)\n- **Questions and discussions.** [GitHub Discussions](https://github.com/jurczykpawel/reelstack/discussions)\n- **Security vulnerabilities.** Email **security@reelstack.io** (see [SECURITY.md](SECURITY.md))\n\n---\n\n## Acknowledgments\n\nReelStack is built on top of these excellent open-source projects:\n\n| Project                                                                        | Role                                  |\n| ------------------------------------------------------------------------------ | ------------------------------------- |\n| [Next.js](https://nextjs.org/)                                                 | Full-stack React framework            |\n| [Remotion](https://www.remotion.dev/)                                          | React-based video rendering           |\n| [FFmpeg](https://ffmpeg.org/) / [FFmpeg.wasm](https://ffmpegwasm.netlify.app/) | Video processing (server and browser) |\n| [whisper.cpp](https://github.com/ggerganov/whisper.cpp)                        | Word-level speech transcription       |\n| [Zustand](https://zustand-demo.pmnd.rs/)                                       | Lightweight state management          |\n| [Auth.js](https://authjs.dev/)                                                 | Authentication framework              |\n| [Prisma](https://www.prisma.io/)                                               | Database ORM                          |\n| [BullMQ](https://docs.bullmq.io/)                                              | Redis-backed job queue                |\n| [Tailwind CSS](https://tailwindcss.com/)                                       | Utility-first CSS framework           |\n| [shadcn/ui](https://ui.shadcn.com/)                                            | Accessible UI components              |\n| [Turborepo](https://turbo.build/)                                              | Monorepo build system                 |\n| [Vitest](https://vitest.dev/)                                                  | Unit testing framework                |\n| [Playwright](https://playwright.dev/)                                          | End-to-end testing                    |\n\n![](https://stats.techskills.academy/pixels/github?url=/readme/reelstack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjurczykpawel%2Freelstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjurczykpawel%2Freelstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjurczykpawel%2Freelstack/lists"}