How connective-solutions/openshorts works
1. Overall shape
OpenShorts is a self-hosted, containerized video-creation platform split into three main runtime pieces: a Python backend, a React/Vite dashboard, and a separate Node/Remotion render service. The backend orchestrates AI/video jobs; the dashboard is the user control plane; the render service handles isolated video composition/rendering.
2. User-facing dashboard
The dashboard/ app is a single-page React frontend with tabs and modals for Clip Generator, AI Shorts, YouTube Studio, gallery browsing, scheduling, subtitles, translations, and thumbnail work. It also includes browser-side preview logic and shared Remotion composition code for local previewing before server-side render.
3. Backend orchestration layer
The Python side (main.py, app.py, and feature modules like editor.py, hooks.py, subtitles.py, thumbnail.py, translate.py, saasshorts.py) is the core orchestration layer. It coordinates uploads, job state, AI calls, media processing, publishing, and storage. This is where the product’s business workflows live rather than in the frontend.
4. Clip Generator pipeline
The clip-generation flow ingests long-form video, transcribes it, detects scenes, asks Gemini to pick viral moments, cuts clips with FFmpeg, then reframes them for vertical output. It adds subtitles, hook overlays, and optional video effects before backing up or publishing the result. This pipeline depends heavily on FFmpeg, Whisper, scene detection, and vision models for framing.
5. AI Shorts pipeline
The AI Shorts path is a separate content-generation pipeline: analyze a URL or prompt, generate a script, create/select an avatar, synthesize voice, generate talking-head and b-roll assets, then composite the final short. The final video is assembled with subtitles and hook overlays, then stored and optionally published to social platforms. This pipeline is more generative and API-driven than the clip generator.
6. YouTube Studio pipeline
The YouTube Studio tool is another backend workflow focused on thumbnails, titles, descriptions, and direct YouTube publishing. It uses AI for copy and image generation, but its output is metadata and thumbnail assets rather than long render pipelines. In the architecture diagram, it should be treated as a separate product path with lighter media processing.
7. Rendering boundary
Rendering is intentionally separated from orchestration. The top-level remotion/ package and the render-service/ container host Remotion compositions and a render worker/server, so video rendering can run in an isolated Node environment. The dashboard also has its own Remotion preview components under dashboard/src/remotion, which are used for in-browser preview rather than production rendering.
8. Shared composition model
The Remotion compositions (ShortVideo, Subtitles, HookOverlay, VideoEffects) appear both in the standalone Remotion package and the dashboard-side preview implementation. This indicates the same visual template system is reused across preview and production render paths, keeping the final video layout consistent.
9. Storage, gallery, and SEO pages
Generated videos and avatars are persisted to S3, with a private bucket for clip backups and a public bucket for gallery/SEO assets. The README indicates the backend serves public gallery pages and individual video pages with metadata like og:video and JSON-LD, so storage is not just archival—it is also part of the public distribution layer.
10. External service dependencies
The platform’s main external integrations are Google Gemini for analysis/script generation, ElevenLabs for voice and dubbing, fal.ai for avatar/video generation, Upload-Post for multi-platform publishing, and AWS S3 for storage. These services materially shape the architecture because most AI-heavy steps are delegated outward rather than implemented locally.
11. Job execution and operational limits
The backend enforces concurrency with a semaphore-based queue (MAX_CONCURRENT_JOBS) and retention/cleanup policies. That means the system behaves like an asynchronous media-processing worker farm rather than a simple request/response API, which is important when drawing the architecture diagram.
12. Deployment topology
Docker Compose is the primary deployment unit. The repo includes separate Dockerfiles for the backend, dashboard, and render-service, which suggests each is independently built and run as a container while sharing environment configuration from .env/.env.example. The dashboard is exposed as the user entrypoint, while the backend and render service are internal services supporting it.
Main entry points: saasshorts.py AI Shorts · editor.py Editor flow · main.py Main app · App.jsx Dashboard UI
Components 24
Python backend
Orchestrates media workflows, AI calls, storage, and publishing.
- Main app · Backend entrypoint and job coordination layer.
main.py - API app · Backend application surface and request handling.
app.py - Editor flow · Core clip generation and editing pipeline.
editor.py - AI Shorts · Generative short-form video workflow.
saasshorts.py - Thumbnail studio · Thumbnail and title/description generation path.
thumbnail.py - Subtitles · Captioning, subtitle timing, and subtitle rendering support.
subtitles.py - Hooks · Hook selection and overlay generation.
hooks.py - Translate · Translation and dubbing support.
translate.py - S3 storage · Uploads and retrieval for private/public media assets.
s3_uploader.py
Dashboard
React/Vite control plane and browser preview UI.
- Dashboard UI · Main React control plane for all product tabs and modals.
dashboard/src/App.jsx - Gallery · Video browsing and asset presentation.
dashboard/src/components/Gallery.jsx - AI Shorts tab · Dashboard entry for AI Shorts generation workflow.
dashboard/src/components/SaaShortsTab.jsx - Thumbnail studio UI · Dashboard tooling for thumbnails and SEO assets.
dashboard/src/components/ThumbnailStudio.jsx - Browser preview · In-browser Remotion preview and local render simulation.
dashboard/src/components/RemotionPreview.jsx - Preview comps · Dashboard-side Remotion compositions for local preview.
dashboard/src/remotion/compositions/ShortVideo.tsx
Rendering
Standalone Remotion packages for production render and preview.
- Remotion root · Standalone Remotion composition registry and entrypoint.
remotion/src/Root.tsx - Render worker · Isolated render execution and server-side composition handling.
render-service/src/render-worker.ts - Render server · Service boundary for rendering requests.
render-service/src/server.ts
External services
Third-party AI, storage, and publishing dependencies.
- Gemini · Analysis, scripting, and decision support for content generation.
- ElevenLabs · Voice synthesis and dubbing.
- fal.ai · Avatar and AI video generation.
- AWS S3 · Private backups and public gallery asset storage.
- YouTube · Direct publishing destination for video workflows.
- Upload-Post · Multi-platform publishing integration.
Connections 28
- Main app → API app: serves · Application entrypoint initializes the backend surface.
- Main app → Editor flow: orchestrates · Coordinates clip generation jobs and media processing.
- Main app → AI Shorts: orchestrates · Coordinates AI Shorts generation jobs.
- Main app → Thumbnail studio: routes · Dispatches thumbnail and metadata work.
- Editor flow → Subtitles: uses · Adds captions to generated clips.
- Editor flow → Hooks: uses · Applies hook overlays during clip assembly.
- Editor flow → S3 storage: stores · Persists generated outputs and backups.
- AI Shorts → Subtitles: uses · Subtitles are part of the final short composition.
- AI Shorts → Hooks: uses · Hook overlays are applied to generated shorts.
- AI Shorts → Thumbnail studio: feeds · Thumbnail and metadata outputs support publishing.
- Thumbnail studio → Gemini: calls · Generates copy and content suggestions.
- Editor flow → Gemini: calls · Selects scenes and viral moments.
- AI Shorts → fal.ai: calls · Generates avatar or b-roll assets.
- AI Shorts → ElevenLabs: calls · Synthesizes narration and dubbing.
- Thumbnail studio → AWS S3: uploads · Stores public thumbnail and asset outputs.
- S3 storage → AWS S3: writes · Backend storage adapter targets S3 buckets.
- API app → YouTube: publishes · Backend exposes publishing workflows to YouTube.
- AI Shorts → Upload-Post: publishes · Supports multi-platform publishing.
- Dashboard UI → Gallery: contains · Gallery browsing is part of the main UI.
- Dashboard UI → AI Shorts tab: contains · AI Shorts workflow is exposed as a tab.
- Dashboard UI → Thumbnail studio UI: contains · Thumbnail tooling is exposed in the dashboard.
- Dashboard UI → Browser preview: contains · Dashboard includes browser-side preview controls.
- Browser preview → Preview comps: renders · Preview UI consumes shared compositions locally.
- Preview comps → Remotion root: mirrors · Dashboard preview compositions mirror production templates.
- Remotion root → Render server: served by · Production render service loads the composition bundle.
- Render server → Render worker: dispatches · Server delegates actual render execution to worker logic.
- Render worker → Preview comps: shares model · Shared compositions keep preview and production consistent.
- Render worker → AWS S3: reads/writes · Rendered media is persisted to object storage.