StreamSouk

A video streaming platform I built to learn how video, uploads and background processing work end to end.

What you can do

  • Upload and resumeSend a large video and pick it up again after a dropped connection.
  • Processing with progressEvery upload is transcoded in the background, and the Studio shows how far along it is.
  • WatchAdaptive streaming that picks a quality for your connection, with a link you can share.
  • Comments and reactionsComment, reply, like and dislike, with moderation for the owner.
  • SubscriptionsSubscribe to Channels and keep a list of the ones you follow.
  • StudioManage your Videos: edit details, set visibility, change the thumbnail, retry or delete.

Engineering

Resumable uploads

Decision

The browser uploads straight to tusd, and Express only handles its hooks.

Why

Large files never pass through the API, and an upload can resume. The hooks are where I check ownership and reject a wrong-user finish.

Proof

Background processing

Decision

Jobs are queued with pg-boss in the app's own Postgres, with retries, a failed state and a retry endpoint.

Why

It needs no extra infrastructure to run or pay for, and a failed Video ends in a state the owner can see and retry.

Proof

Adaptive streaming

Decision

ffmpeg produces HLS renditions and reports progress, and playback goes through short-lived signed media tokens.

Why

HLS lets the player adapt to the connection, and tokens keep the storage bucket private.

Proof

How I used AI to build this

I built StreamSouk with an AI coding assistant, and I directed it the way I would a junior engineer: I decided what to build and why, and I reviewed everything it produced. Before any feature I worked through the design with it in a question-and-answer session, wrote the domain terms into a glossary and recorded significant decisions as ADRs. Each change then went through a ticket, a feature branch, a code review and a pull request. The project's guidance lives in CLAUDE.md, so the assistant works from the same written rules I do. The part I found hardest, and the part that stayed mine, was deciding what not to build.

Proof

Run it yourself

Pick one. Each shows the commands only; the guide on GitHub has the prerequisites, checks and troubleshooting.

Docker

Docker is the only prerequisite (about 4 GB of RAM allocated to it).

git clone https://github.com/azeemuddinaziz/streaming.git
cd streaming
docker compose up

Open http://localhost:3001. Full guide on GitHub

GitHub (manual)

You run a Postgres database and four processes: the API, the background worker, the upload server (tusd) and the web app.

git clone https://github.com/azeemuddinaziz/streaming.git
cd streaming
pnpm install

createdb streamsouk
createdb streamsouk_test

cp server/.env.example server/.env
cp web/.env.example web/.env.local

pnpm --filter server generate
pnpm --filter server exec prisma migrate deploy

Set DATABASE_URL, TEST_DATABASE_URL and JWT_SECRET in server/.env first, then start each process in its own terminal from the repo root:

pnpm --filter server dev
pnpm --filter server worker
pnpm --filter server tusd
pnpm --filter web dev

Open http://localhost:3001. Full guide on GitHub

Good to know

  • Transcoding speed depends on your machine.
  • Share links only work locally, because media and share links use localhost.

Why there's no live instance

StreamSouk is a video platform: it stores and serves video and transcodes every upload. That costs real money to host, and this is a learning project I fund myself, so there's no public instance right now. You can run the whole thing on your own machine in a few minutes, or watch the demo above.

Support

If you found this useful, you can leave a tip on GitHub Sponsors. It is a tip jar: no perks, and nothing is unlocked.

Tip on GitHub Sponsors