VideoSphere Documentation

VideoSphere is an open-source, self-hosted video distribution platform. Upload once to Cloudflare R2, then distribute to YouTube, Vimeo, Facebook, SermonAudio, Google Drive, SFTP, and SMB — with metadata drafts, labels, thumbnails, scheduling, YouTube import, livestream scheduling, and optional per-user live audio translation.

Start Here (deploy & operate)

For homelab or production use — no source checkout required if you use the published Docker image.

1. Deployment Guide — run the pre-built image with Docker Compose or Portainer (includes MongoDB mongodump / mongorestore backup steps)
2. R2 Storage — create a Cloudflare R2 bucket and API credentials (required for uploads)
3. Google OAuth — sign-in with Google, YouTube connection, and Google Drive connection (optional per integration)
4. Vimeo OAuth — Vimeo connection and Upload Access approval (single-account limitation; see guide)
5. Facebook OAuth — Facebook Page connection for Reels publishing
6. Password Recovery — reset accounts when SMTP is not configured (CLI, admin links, container access)

After the stack is running, connect platforms under Profile → Connections in the app. Setup guides: Google OAuth, Vimeo OAuth, Facebook OAuth, SermonAudio API. Optional live audio translation (per-user OpenRouter / Groq / GCP keys in Dashboard → Translation) can stream captions and spoken translations on a public /listen/{slug} page.

Want to smoke-test the production image on your machine before going live? See Local Docker Testing.

Development & contributing

Cloning the repo, changing code, or updating docs? Start with Local Setup, then see Development & Contributing.

Using the app

Full walkthrough: Uploads, Livestreams & Distribution — platform connections, draft metadata modal, file upload, YouTube import, livestream scheduling, and upload history.

Area	Route	Notes
Uploads	/dashboard/uploads	Draft list and metadata editor (DraftMetadataModal)
Upload history	/dashboard/uploads/history	Completed and failed jobs; retry and discard
Livestreams	/dashboard/livestreams	YouTube scheduled broadcasts (Facebook scheduling disabled for new schedules)
Translation	/dashboard/translation	Per-user live audio translation; public /listen/{slug}
Connections	/profile/connections	OAuth and credential setup per platform
Admin	/dashboard/users, /admin/dashboard	User management and stats

Draft data APIs remain under /api/drafts/*; the dashboard nav label is Uploads.