# VidcastX: open source video infrastructure you host yourself

URL: https://pixelactstudio.com/work/vidcastx

> VidcastX is open source, self-hostable video infrastructure by Pixelact Studio. See what works today, how its FFmpeg to HLS pipeline runs, and what V1 adds.

Label: Open Source. Status: In development.

- **Type:** Open source, self-hostable video infrastructure: an API, a transcoding worker, and a dashboard
- **Built by:** Pixelact Studio, as a studio project. It is not a Damn Labs tool
- **License:** MIT
- **Status:** In development toward V1, with no tagged release yet. Upload and transcoding work today; the public API, player, and webhooks are V1 work
- **Platform:** Built to run on your own servers with any S3-compatible storage, such as S3, R2, or MinIO. Today Docker Compose runs the local development infrastructure
- **Stack summary:** A TypeScript monorepo: Elysia on Bun, a TanStack Start dashboard, a Node worker running FFmpeg, PostgreSQL with Drizzle, and Redis with BullMQ
- **Data location:** Source videos, HLS output, and the database stay on servers and storage you choose, not in a video vendor's cloud

- [Source on GitHub](https://github.com/pixelactstudio/vidcastx)
- [Read the V1 scope](https://github.com/pixelactstudio/vidcastx/blob/main/IDEA.md)

VidcastX is open source, self-hostable video infrastructure built by Pixelact Studio under the MIT license. Today it sends uploads straight to your own S3-compatible bucket and transcodes them with FFmpeg into adaptive HLS, a poster, and a hover preview. The developer API, player, and webhooks that complete it are V1 work, still in development.

## Is VidcastX open source, and who is it for?

Yes. VidcastX is MIT-licensed, and its source, documentation, and V1 plan are public on GitHub, so anyone can read, fork, or self-host it. There is no tagged release yet.

It is written for two groups. The first is developers who embed video in a product, such as a course platform, a SaaS product's onboarding videos, or an internal tool, and want an API, webhooks, and a player on servers they control. The second is engineers who want to read a real upload, transcode, and playback pipeline, with docs that explain each step.

## What problem does VidcastX solve?

VidcastX gives teams the hosted video API model without handing their files to a vendor. Hosted APIs handle encoding and delivery well, but they run in the vendor's cloud and bill by usage. Mux, for example, bills per minute of video stored and delivered, and per minute encoded at quality levels above basic.

VidcastX follows the same API model and moves it onto servers and storage you run, with an FFmpeg pipeline you can read.

**Hosted video APIs compared with VidcastX**

| Concern | Hosted video APIs such as Mux | VidcastX |
| --- | --- | --- |
| Where it runs | The vendor's cloud | Your servers and your bucket, such as S3, R2, or MinIO |
| What you pay for | Usage, metered per minute of video | The servers and storage you run |
| The pipeline | Closed source | FFmpeg commands you can read and rerun, documented step by step |
| Where data lives | The vendor's regions | Wherever you deploy |

## What works in VidcastX today, and what is V1 work?

Uploads and transcoding work today. The public developer API, the player, webhooks, and a one-command deployment are V1 work, tracked phase by phase in the repository. Until then, VidcastX is not ready for production use.

**VidcastX status by area, as of November 2026**

| Area | Works today | V1 work |
| --- | --- | --- |
| Accounts | Email, GitHub, and Discord sign-in; organizations with Owner, Admin, and Member roles | Dashboard pages for team members, invites, and organization settings |
| Dashboard | Login, onboarding, a folder browser with thumbnails and hover previews, and upload | A video page with the player and pipeline status, and no placeholder pages |
| Uploads | Resumable multipart uploads from the dashboard, straight to storage | Upload and ingest-from-URL endpoints in the public API |
| Transcoding | HLS up to 1080p, a poster, and a hover preview | 8-bit output for 10-bit sources, rotated phone video, retries that never duplicate outputs, and storyboard thumbnails |
| Developer API | Session-authenticated video and folder routes with OpenAPI docs | API keys, playback IDs, signing keys, and webhooks |
| Playback | No player yet | A `vidcastx-player` web component with signed playback |
| Deployment | Docker Compose runs Postgres, Redis, and MinIO for development | One compose file for the whole stack |
| Tests and CI | Typecheck, lint, format, unit tests, build, and CodeQL on every pull request | An end-to-end smoke test of the pipeline |

V1 is done when these hold on a fresh clone of the repository.

- `docker compose up` brings the whole stack up healthy, and copying `.env.example` is the only manual step.
- A developer with an API key uploads a rotated phone video with audio, receives a signed `video.ready` webhook, and plays it through `<vidcastx-player>` with a signed token in current Chrome, Firefox, and Safari.
- The same flow works from the dashboard alone.
- Deleting a video removes its files, and an expired playback token is rejected.
- CI runs the API flow end to end, and the docs match shipped behavior.

## How do you run VidcastX locally?

VidcastX runs from a clone today. Docker Compose starts Postgres, Redis, and MinIO, and pnpm starts the apps. There is no production deployment path yet, because containerized services and one compose file for the whole stack are V1 work.

```bash
git clone https://github.com/pixelactstudio/vidcastx.git
cd vidcastx
cp .env.example .env
pnpm install
docker compose up -d
pnpm db:migrate
pnpm dev
```

`pnpm dev` starts the API, the dashboard, the transcoder worker, and the offline docs. The dashboard opens on port 4000, and the API on port 4001 serves its OpenAPI docs at `/openapi`. The example configuration is for local use only, so replace every secret before sharing an environment.

## How does VidcastX work?

VidcastX has three running parts: a TanStack Start dashboard, an Elysia API on Bun, and a Node worker that runs FFmpeg. PostgreSQL holds the records, Redis holds the job queue, and S3-compatible storage holds every file.

1. **Upload straight to storage.** The API reserves a storage key under the video's organization and signs one URL per upload part. The browser sends the parts directly to storage with Uppy, and an interrupted upload resumes.
2. **Queue fairly.** Completing the upload only marks the video `queued` in Postgres. The API's dispatcher, not the upload request, decides when the job enters BullMQ, so one busy organization cannot hold up the rest.
3. **Transcode.** The worker probes the source with `ffprobe` and builds a 1080p, 720p, and 480p ladder that never exceeds the source, except at the 480p floor. A single FFmpeg process decodes the source once and writes every rung as HLS with a 6-second segment target. The worker then makes a poster and a hover preview.
4. **Report back.** The worker has no database access. It reports results through the API's internal routes with a machine token that expires after an hour, so the API is the only writer to Postgres.

## What are the hard parts of building VidcastX?

Two problems take most of the engineering: output that plays in every browser, and private playback when an HLS stream is a folder of plain files. The third is discipline, which means writing down what is still broken.

### Output every browser can play

Sources arrive as HEVC in MOV containers, 4K at 60 fps, or variable-frame-rate screen captures. The worker re-encodes each one to H.264 video and AAC audio in MPEG-TS segments, which Safari plays natively and other browsers play through a library such as hls.js.

Each rung uses capped CRF. `-crf 23` sets a quality target, while `-maxrate` and `-bufsize` hold the bitrate within what the master playlist advertises. Frame-rate thresholds sit just below each target, so a 59.94 fps source still gets a 60 fps rung.

One fix is still open. A 10-bit source currently comes out as High 10 H.264, which not every browser can decode, so V1 forces 8-bit `yuv420p` output.

### Signed playback with a private bucket

A presigned URL authorizes one object, but an HLS master playlist points to its variant playlists and segments by relative path, and the player fetches them without a signature. That works locally only because the development bucket is public. V1 serves playlists from a playback route that checks the viewer's token and signs every playlist and segment URL, so the bucket can stay private.

### Writing down the gaps

The transcoding guide lists known defects beside the explanation, such as keyframes that are not aligned across renditions and a `CONCURRENT_JOBS` setting that is never read. Both are tasks in the V1 plan's transcoder hardening phase, to be fixed test-first against generated clips.

## What does VidcastX show about how Pixelact builds software?

VidcastX has the shape of many startup products: organizations with roles, a typed API, background jobs, object storage, and a dashboard. It is built with the habits we bring to [product development](https://pixelactstudio.com/services/product-development) for funded startups.

- **Scope is cut to what can be finished.** Earlier plans included AI transcription, dubbing, semantic search, and billing. In September 2026 the product was redefined around one V1 with a checkable definition of done, the approach in [how to scope an MVP](https://pixelactstudio.com/blog/how-to-scope-an-mvp).
- **Cleanup comes before features.** The first phase removed unused packages, pinned floating dependencies, repaired git hooks, added CI, and refreshed the lockfile, which took `pnpm audit` from 59 advisories, 3 of them critical, to 2 moderate dev-only ones. That is the order of [software rescue](https://pixelactstudio.com/services/software-rescue), and why we decide [whether to rebuild or refactor](https://pixelactstudio.com/blog/rescue-or-rebuild) only after reading the code.
- **Responses expose only what the client needs.** Response schemas name their fields with TypeBox `Pick` or `Omit` instead of returning whole database rows, so video responses leave out the raw storage key and internal metadata.
- **AI agents work inside written rules.** Agents read before editing, add no dependency without the owner's approval, and build nothing outside V1 without sign-off. A hook blocks an agent's `pnpm add` until the owner approves it.

These are the [engineering standards](https://pixelactstudio.com/about/engineering-standards) we apply to every build. VidcastX is a Pixelact Studio project, separate from the free tools on the [Damn Labs page](https://pixelactstudio.com/labs). If your product needs uploads, background jobs, or a multi-tenant API built this way, [start a project](https://pixelactstudio.com/start-a-project) and tell us what it has to do.

## The decisions behind VidcastX

### Follow Mux's model on your own servers

**What we chose:** When a resource, endpoint, event, or player option is undecided, V1 copies Mux's shape: direct uploads, playback IDs, public or signed playback, `passthrough` metadata, and signed webhooks.

**Why:** Developers who have used a hosted video API recognize the model, and open design questions are settled by a reference instead of a debate. VidcastX departs from it only for self-hosting or readability, and records why.

### The API never carries video bytes

**What we chose:** The browser uploads parts straight to storage through presigned URLs, and the worker reads and writes storage directly. The API only signs URLs and records state.

**Why:** Uploads of up to 50 GB never compete with API requests for memory or bandwidth, and an interrupted upload resumes from the parts that storage already holds.

### A fair dispatcher in front of the queue

**What we chose:** Finished uploads wait in Postgres. Every 5 seconds, a dispatcher takes a Redis lock and admits at most one active transcode per organization into BullMQ.

**Why:** If uploads went straight into the queue, one organization uploading 500 videos would make every other tenant wait behind it. BullMQ holds only work that should run now, and the lock stops two API instances from dispatching at once.

### The FFmpeg CLI, not bindings

**What we chose:** The transcoder builds FFmpeg commands that a reader can copy and run. A draft rewrite on libav bindings is parked until after V1.

**Why:** The pipeline is meant to be read and learned from. A CLI command can be pasted into a terminal and run as-is, so the docs print the exact command the worker builds for a 1080p source. The libav draft stays parked, and its useful findings moved into the V1 transcoder fixes.