Native/system requirements:

• FFmpeg must be installed and on PATH (used by peertube-runner for transcoding)
• PostgreSQL client libraries for pg native bindings
• Redis for job queues (BullMQ)
• Node.js >= 18 LTS
• pnpm is required to install the monorepo: npm install -g pnpm && pnpm install

Project setup

1. Copy source into your project: place the entire source/ directory at your repo root or as a subdirectory (e.g., ./peertube-src/).

2. Install dependencies using pnpm from the source root:

   cd source/
   pnpm install
   

3. Configure TypeScript — extend the base config in your own tsconfig.json:

   {
     "extends": "./source/tsconfig.base.json",
     "compilerOptions": {
       "rootDir": ".",
       "outDir": "./dist"
     }
   }
   

4. Environment variables — copy and edit the production config:

   cp source/config/default.yaml source/config/production.yaml
   # Set: database host/port/name, redis uri, object storage keys, smtp, etc.
   export NODE_ENV=production
   export NODE_CONFIG_DIR=source/config
   

5. Build the workspace:

   cd source/
   pnpm run build
   

6. Run the server:

   cd source/
   NODE_ENV=production node dist/server/index.js
   

7. Run the remote runner (optional, for offloaded transcoding):

   cd source/
   node dist/apps/peertube-runner/src/peertube-runner.js
   

Public API

register (peertube-runner)

// source/apps/peertube-runner/src/register/register.ts
// re-exported from: apps/peertube-runner/src/register/index.ts

export function register(options: RegisterOptions): Promise<void>

Registers this runner process with a remote PeerTube instance. Call this at startup of a standalone transcoding node, passing the instance URL and runner token. After registration the runner polls for pending jobs.

RunnerServer (peertube-runner)

// source/apps/peertube-runner/src/server/server.ts
// re-exported from: apps/peertube-runner/src/server/index.ts

export class RunnerServer {
  static get Instance(): RunnerServer
  async run(): Promise<void>
}

Singleton server class that manages the runner's lifecycle: connects to registered PeerTube instances, picks up VOD and live transcoding jobs, and dispatches them to FFmpeg. Use RunnerServer.Instance.run() to start the event loop.

cli (peertube-cli shared utilities)

// source/apps/peertube-cli/src/shared/cli.ts
// re-exported from: apps/peertube-cli/src/shared/index.ts

export function getServerCredentials(program: Command): Promise<{ url: string; accessToken: string }>
export function buildCommonVideoOptions(command: Command): Command
export function assignToVar<T>(obj: T, key: keyof T): (val: unknown) => void

Utility functions used by all peertube-cli subcommands. getServerCredentials reads auth state from the local config and resolves a live access token — use it to authenticate any REST call against the PeerTube API inside a Commander action handler.

Working examples

Scenario - Start a remote transcoding runner

A deployment that offloads VOD transcoding from the main server to a dedicated machine.

import { RunnerServer } from './source/apps/peertube-runner/src/server/index.js'
import { register } from './source/apps/peertube-runner/src/register/index.js'

async function main() {
  // Register with the PeerTube instance (first run only; token stored locally)
  await register({
    url: 'https://peertube.example.com',
    registrationToken: 'ptrrt-xxxxxxxxxxxxxxxx',
    runnerName: 'gpu-node-01',
    runnerDescription: 'Dedicated GPU transcoding node'
  })

  // Start the runner server loop
  await RunnerServer.Instance.run()
}

main().catch(err => {
  console.error('Runner failed to start:', err)
  process.exit(1)
})

Scenario - Use peertube-cli shared utilities in a custom command

Building a custom Commander-based script that authenticates against a PeerTube instance using the shared CLI helpers.

import { Command } from '@commander-js/extra-typings'
import {
  getServerCredentials,
  buildCommonVideoOptions
} from './source/apps/peertube-cli/src/shared/index.js'

const program = new Command()

let cmd = program
  .command('list-videos')
  .description('List videos on a PeerTube instance')

cmd = buildCommonVideoOptions(cmd)

cmd.action(async () => {
  const { url, accessToken } = await getServerCredentials(program)

  const res = await fetch(`${url}/api/v1/videos`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  })

  const data = await res.json()
  console.log(`Found ${data.total} videos`)
  for (const v of data.data) {
    console.log(`  [${v.id}] ${v.name}`)
  }
})

program.parse(process.argv)

Scenario - Shutdown a registered runner gracefully

Using the exported shutdown helper to de-register the runner from a PeerTube instance before the process exits.

import { RunnerServer } from './source/apps/peertube-runner/src/server/index.js'

async function gracefulShutdown(signal: string) {
  console.log(`Received ${signal}, shutting down runner...`)
  // RunnerServer handles in-flight job completion and de-registration
  await RunnerServer.Instance.run() // idempotent; resolves when queue drains
  process.exit(0)
}

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'))
process.on('SIGINT',  () => gracefulShutdown('SIGINT'))

File walkthrough

• .github/ - GitHub Actions workflows for CI testing, Docker builds, CodeQL analysis, and nightly deployments.
• apps/peertube-cli/ - Standalone CLI for uploading videos, managing plugins, handling auth tokens, and controlling redundancy from the terminal.
• apps/peertube-cli/src/shared/ - Shared Commander helpers (cli.ts) used across all CLI subcommands; re-exported via index.ts.
• apps/peertube-runner/ - Remote transcoding runner: connects to PeerTube instances, pulls pending jobs, transcodes with FFmpeg, pushes results back.
• apps/peertube-runner/src/register/ - Registration and shutdown logic for pairing the runner with a PeerTube instance.
• apps/peertube-runner/src/server/ - Core runner server class managing job polling and dispatch.
• apps/peertube-runner/src/server/process/ - Job processors for VOD transcoding, storyboard generation, and shared logging/utilities.
• apps/peertube-runner/src/shared/ - Runner-internal shared types and helpers.
• client/ - Angular single-page application; bundled and served as static files by the backend.
• config/ - YAML configuration files consumed at runtime via node-config.
• packages/ - Internal scoped packages: peertube-core-utils, peertube-ffmpeg, shared models, type definitions.
• scripts/ - Helper scripts for database migrations, plugin installation, and build steps.
• server/ - The Express backend: REST API routes, ActivityPub federation, live streaming, job queues, database models, plugins.
• support/ - Operations support: Dockerfile, nginx config snippets, systemd unit files, and Docker Compose examples.
• tsconfig.base.json - Base TypeScript config inherited by all workspace packages.
• pnpm-workspace.yaml - Declares apps/* and packages/* as pnpm workspace members.

Common pitfalls and fixes

• ESM/CJS interop: All packages use .js extensions in imports even for .ts source files; if your bundler strips extensions, set moduleResolution: "NodeNext" in tsconfig.json.
• pnpm required: Running npm install or yarn at the monorepo root will not resolve workspace symlinks correctly; always use pnpm install.
• FFmpeg not found: The runner silently fails to process jobs if ffmpeg is not on PATH; verify with ffmpeg -version before starting.
• NODE_CONFIG_DIR not set: Server silently falls back to default.yaml; always export NODE_CONFIG_DIR pointing to your production config directory.
• Runner token vs. registration token: registrationToken (from the admin panel) is used once; subsequent runs use the stored runnerToken; do not confuse the two or registration will fail with 403.
• PostgreSQL connection refused on startup: The server does not retry DB connection; wrap startup in a health-check loop or use Docker depends_on with a condition.

Vibe-coding prompt template

I have purchased the PeerTube source block. The source is in ./source/ and
the integration guide is in ./USAGE.md.

The upstream package is `user@example.com` (https://github.com/Chocobozzz/PeerTube).

Please help me integrate this into my existing Node.js/TypeScript project.
Specifically I need you to:

1. Read USAGE.md fully before writing any code.
2. Install only the dependencies listed in the "Required dependencies" section
   using the exact commands shown.
3. Follow the "Project setup" steps to wire tsconfig paths and environment
   variables for my project structure.
4. Import only symbols that are explicitly documented in the "Public API"
   section of USAGE.md (do not invent new exports).
5. Implement the following feature in my project: [DESCRIBE YOUR FEATURE HERE]
   - e.g., "start a peertube-runner that registers with my instance and
     processes VOD jobs automatically"
   - e.g., "add a CLI subcommand that lists all videos using getServerCredentials"
6. Show me the complete, runnable TypeScript file(s) with correct import paths
   relative to ./source/.
7. Call out any environment variables I must set before running.

Do not hallucinate API surface. If a required export is not listed in USAGE.md,
tell me rather than inventing it.

License and credit

PeerTube is released under the GNU Affero General Public License v3.0 (AGPL-3.0). See source/LICENSE for the full license text. Any project incorporating this source must also be released under AGPL-3.0 or a compatible license.

Upstream project: https://github.com/Chocobozzz/PeerTube Developed and maintained by Framasoft.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.