Skip to content

Open Source · In development

VidcastX: open source video infrastructure you host yourself

VidcastX takes an uploaded video, transcodes it with FFmpeg into adaptive HLS with a poster and hover preview, and keeps every file in your own S3-compatible storage. Pixelact Studio builds it under the MIT license, and it is in development toward V1.

The VidcastX logo and the words Open source video infrastructure on a video frame marked In development, with its 720p and 480p renditions stacked behind the 1080p one and a playback bar split into 6-second HLS segments.
Open source, self-hostable video infrastructure that turns an upload into an adaptive HLS stream in your own S3-compatible storage, in development toward V1.

VidcastX at a glance

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

Decisions

The decisions behind VidcastX

The technical calls that shaped how it works: what we picked, and the trade-off that made it the right pick.

  • Decision 01

    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.
  • Decision 02

    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.
  • Decision 03

    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.
  • Decision 04

    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.

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.

ConcernHosted video APIs such as MuxVidcastX
Where it runsThe vendor's cloudYour servers and your bucket, such as S3, R2, or MinIO
What you pay forUsage, metered per minute of videoThe servers and storage you run
The pipelineClosed sourceFFmpeg commands you can read and rerun, documented step by step
Where data livesThe vendor's regionsWherever you deploy
Hosted video APIs compared with VidcastX

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.

AreaWorks todayV1 work
AccountsEmail, GitHub, and Discord sign-in; organizations with Owner, Admin, and Member rolesDashboard pages for team members, invites, and organization settings
DashboardLogin, onboarding, a folder browser with thumbnails and hover previews, and uploadA video page with the player and pipeline status, and no placeholder pages
UploadsResumable multipart uploads from the dashboard, straight to storageUpload and ingest-from-URL endpoints in the public API
TranscodingHLS up to 1080p, a poster, and a hover preview8-bit output for 10-bit sources, rotated phone video, retries that never duplicate outputs, and storyboard thumbnails
Developer APISession-authenticated video and folder routes with OpenAPI docsAPI keys, playback IDs, signing keys, and webhooks
PlaybackNo player yetA vidcastx-player web component with signed playback
DeploymentDocker Compose runs Postgres, Redis, and MinIO for developmentOne compose file for the whole stack
Tests and CITypecheck, lint, format, unit tests, build, and CodeQL on every pull requestAn end-to-end smoke test of the pipeline
VidcastX status by area, as of November 2026

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.

Run the current stack locally. It needs Node.js 22.13 or later, pnpm 11, Bun, Docker, and FFmpeg.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. 01Upload straight to storageThe 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. 02Queue fairlyCompleting 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. 03TranscodeThe 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. 04Report backThe 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 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.
  • 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, and why we decide whether to rebuild or refactor 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 we apply to every build. VidcastX is a Pixelact Studio project, separate from the free tools on the Damn Labs page. If your product needs uploads, background jobs, or a multi-tenant API built this way, start a project and tell us what it has to do.

Custom builds

Need something like this built?

The same engineers design and build products, internal tools, and AI systems for funded startups. Tell us what you need, or book a call to talk it through.

On the discovery call

  1. 01What prompted this now, and where things stand
  2. 02What a good outcome looks like
  3. 03Whether we're a fit, and what a next step could be

45 minutes. No slides, and no long questionnaire.