How chocobozzz/peertube works
Purpose and deployable entry points
PeerTube is a federated video-hosting platform: instances publish, stream, moderate, and exchange video/channel activity through ActivityPub, with browser P2P delivery and optional inter-instance redundancy. The primary Node.js server starts at server/server.ts; the Angular web client at client/src/main.ts. Separate Node executables provide automation and remote media workers: apps/peertube-cli/src/peertube.ts and apps/peertube-runner/src/peertube-runner.ts.
HTTP application and persistence boundary
The server is an Express-style application organized around controllers, authentication/validation middleware, domain libraries, and Sequelize-backed models. REST endpoints are grouped by concern—videos, users, search, administration, runners—under server/core/controllers/api/; request authorization, rate limiting, ActivityPub checks, and input validation occur before controller logic in server/core/middlewares/. Persistent entities include actors, users, videos/files, follows, jobs, runners, moderation, and statistics in server/core/models/. Startup loads configuration, database connectivity, installation state, and ordered migrations through server/core/initializers/.
Video ingest, media lifecycle, and asynchronous jobs
Upload/import/live endpoints create or update video state, then delegate expensive work to the internal job queue. The queue and handlers cover imports, HLS/web-video transcoding, studio edits, thumbnails/storyboards, transcription, ActivityPub delivery, storage moves, and notifications: server/core/lib/job-queue/job-queue.ts, server/core/lib/job-queue/handlers/, and server/core/lib/video-post-import.ts. Media processing is built around FFmpeg abstractions in packages/ffmpeg/src/, while the server’s transcoding orchestration selects local queued work or remote runner work under server/core/lib/transcoding/.
Distributed runners and transcription
Instances can offload media-heavy work to registered PeerTube runners. Server-side runner registration, job dispatch, and state handling live in server/core/lib/runners/ and server/core/controllers/api/runners/; the runner process exposes registration, job processing, and IPC coordination in apps/peertube-runner/src/server/ and apps/peertube-runner/src/shared/ipc/. Supported remote jobs include VOD and live transcoding, studio processing, storyboard generation, and transcription. Transcription has a standalone abstraction with Whisper/OpenAI and CTranslate2 implementations in packages/transcription/src/.
Federation, distribution, and storage
ActivityPub is a first-class protocol boundary: inbox/outbox HTTP controllers feed signed, validated activities into processors; outbound work is queued for delivery. Key paths are server/core/controllers/activitypub/, server/core/lib/activitypub/process/, and server/core/lib/activitypub/send/. Video distribution also includes WebTorrent support and tracker-facing endpoints (server/core/lib/webtorrent.ts, server/core/controllers/tracker.ts), plus redundancy between instances (server/core/lib/redundancy.ts). Files can reside on the local filesystem or object storage; object-storage URL/signing/proxy behavior is isolated in server/core/lib/object-storage/.
Client, player, and extension surfaces
The Angular SPA uses route-level feature areas for watching, publishing/managing videos, user libraries, and administration; app composition begins at client/src/app/app.routes.ts. Core client services centralize REST access, auth, routing, sockets, server configuration, and plugins in client/src/app/core/. Playback is independently built around Video.js and P2P/HLS plugins in client/src/standalone/player/src/, while embeddable-video bootstrapping and remote video/playlist retrieval reside in client/src/standalone/videos/. Server and client plugins are explicit extension boundaries, with server lifecycle/hooks in server/core/lib/plugins/, client hook rendering in client/src/app/core/plugins/, and shared plugin contracts in packages/models/src/plugins/.
Shared contracts and operations
packages/models/src/ defines cross-process and API data contracts, including ActivityPub, video, runner, plugin, moderation, and token models; packages/server-commands/src/ is the typed command layer consumed by the CLI. Runtime infrastructure includes Node.js/TypeScript, PostgreSQL via Sequelize models/migrations, Redis integration (server/core/lib/redis.ts), FFmpeg, WebTorrent/WebRTC delivery, Socket.IO-style notifications (server/core/lib/peertube-socket.ts), optional S3-compatible object storage, and Docker/Nginx production deployment assets in support/docker/production/.
Main entry points: peertube-runner.ts PeerTube runner · job-queue.ts Job queue · server.ts Server entry · main.ts Angular SPA
Components 23
PeerTube Server
Node.js API, media pipeline, and federation runtime.
- Server entry
server/server.ts - Startup & migrations · Loads configuration, database state, and ordered migrations.
- REST API controllers · Video, user, search, admin, and runner endpoints.
- Auth & validation · Authorization, rate limits, ActivityPub checks, and input validation.
- Domain models · Actors, videos, follows, jobs, runners, moderation, and statistics.
- Job queue · Runs imports, processing, delivery, storage, and notification work.
server/core/lib/job-queue/job-queue.ts - Job handlers
- Transcoding orchestration · Selects local queued processing or remote runner work.
- ActivityPub pipeline · Processes inbound activities and queues signed outbound delivery.
- ActivityPub HTTP
- P2P & redundancy · WebTorrent tracker integration and inter-instance redundancy.
server/core/lib/webtorrent.ts - Object storage · S3-compatible URL, signing, and proxy behavior.
- Server plugins
Client & Workers
Browser application, CLI, and remote execution runtime.
- Angular SPA · Watching, publishing, libraries, and administration routes.
client/src/main.ts - Client core services · REST, auth, routing, sockets, configuration, and plugins.
- Standalone player · Playback with P2P and HLS plugins.
- PeerTube runner · Registers with instances and processes media jobs through IPC.
apps/peertube-runner/src/peertube-runner.ts - PeerTube CLI
apps/peertube-cli/src/peertube.ts
Shared Services
Contracts and external runtime dependencies.
- Shared models · API, ActivityPub, runner, moderation, token, and plugin contracts.
- PostgreSQL · Persistent storage accessed through Sequelize.
- Redis
server/core/lib/redis.ts - FFmpeg package
- Transcription package · Whisper/OpenAI and CTranslate2 implementations.
Connections 28
- Server entry → Startup & migrations: boots
- Startup & migrations → Domain models: initializes
- Domain models → PostgreSQL: persists via Sequelize
- Server entry → Auth & validation: installs
- Auth & validation → REST API controllers: guards requests to
- REST API controllers → Domain models: reads and writes
- REST API controllers → Job queue: enqueues expensive work
- Job queue → Job handlers: dispatches
- Job handlers → Transcoding orchestration: orchestrates media work
- Transcoding orchestration → FFmpeg package: uses
- Transcoding orchestration → PeerTube runner: offloads jobs to
- PeerTube runner → FFmpeg package: executes media processing with
- PeerTube runner → Transcription package: runs transcription via
- Job handlers → Object storage: moves and stores files
- REST API controllers → P2P & redundancy: serves distribution endpoints
- REST API controllers → ActivityPub HTTP: exposes protocol endpoints
- ActivityPub HTTP → ActivityPub pipeline: feeds validated activities
- ActivityPub pipeline → Job queue: queues outbound delivery
- ActivityPub pipeline → Domain models: updates federation state
- Angular SPA → Client core services: composes
- Client core services → REST API controllers: calls
- Angular SPA → Standalone player: embeds
- Standalone player → P2P & redundancy: uses P2P/HLS delivery
- PeerTube CLI → REST API controllers: automates
- REST API controllers → Shared models: uses API contracts
- PeerTube runner → Shared models: uses runner contracts
- Server plugins → Shared models: implements plugin contracts
- REST API controllers → Redis: uses runtime cache/integration