Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Network Actors

The actors are the participants that run the off-chain layer and interact with the on-chain Protocol to coordinate, settle, and earn.
The protocol defines three core actors, and implements mechanisms to coordinate their interactions and align incentives for the desired network outcomes:
Function: Ingests source video or AI inference requests from end users and routes the work to Orchestrators.Purpose: Connects demand-side applications and users to the Livepeer Network.Economics: Pays for transcoding services using ETH through the ticket system.Technical role. Probably the most demanding integration work of the three. Run Gateway software, ingest video or AI requests from end users, handle Orchestrator discovery and selection, manage payment channels and ticket issuance, deal with failover, and bridge the protocol to whatever application is actually consuming the work. This is where most of the engineering surface area lives.Economic role. They’re the demand side and the only source of external revenue. They fund deposits and reserves to back probabilistic tickets, set their own quality/price tradeoffs by selecting Orchestrators, and ultimately decide whether the network’s pricing is competitive against centralised alternatives. If Gateways aren’t economically satisfied, no one else gets paid.Community role. Historically the quietest of the three, but increasingly important. Gateway operators are often building products on top – streaming platforms, AI apps, developer tools – and their feedback drives what capabilities Orchestrators add and what the protocol prioritises. The Livepeer AI subnet exists in large part because Gateway-side demand pulled it into existence.
Function: Bonds LPT to Orchestrators without running infrastructure directly.Purpose: Secures the network by delegating stake to Orchestrators.Economics: Earns rewards by sharing in the fees and inflationary rewards of the Orchestrator they delegate to.Technical role. Light but real – they need to evaluate Orchestrators (uptime, performance, fee history, reliability), manage their own wallet security, and periodically claim earnings or move stake. No infrastructure, but non-trivial diligence if they’re doing it well.Economic role. Capital allocators. They route LPT toward Orchestrators they believe will earn the most fees and rewards relative to risk, and away from underperformers. In aggregate this is the price signal that shapes the Active Set. They also bear the opportunity cost of locked stake and unbonding periods.Community role. Lower visibility than Orchestrators but real influence – they’re the constituency Orchestrators are courting. Active Delegators participate in governance polls, weigh in on Orchestrator behaviour, and (especially the larger ones) shape sentiment about which Orchestrators are trustworthy. They’re the network’s accountability layer.
Function: Runs the hardware that performs transcoding and AI inference work.Purpose: Registers on-chain, stakes LPT, and bids for work. The top-ranked subset by total stake forms the Active Set, which is eligible to receive jobs in a given round.Economics: Earns rewards and fees for performing work, after the Orchestrator’s configured fee share and Reward Cut are applied.Technical role. Operate the infrastructure. Run go-livepeer, manage transcoders and GPUs, maintain uptime, keep model containers current for AI work, advertise capabilities, and actually perform jobs. This is the only role in the protocol that requires running hardware.Economic role. Price the work (pricePerUnit), set the split with Delegators (feeShare, rewardCut), bond self-stake as collateral, redeem winning tickets, and call reward each round. They’re a small business inside the network – capex on hardware, opex on power and bandwidth, revenue in ETH and LPT.Community role. They’re the most visible public face of the network. Reputation matters because Delegators are choosing them – so Orchestrators run websites, publish stats, show up on Discord, write guides, help newer operators, and participate in governance discussions. The serious ones are effectively brands.
A fourth worker actor also contributes to the network’s overall Video and AI capabilities:
  • Transcoders and AI Workers are specialised nodes that execute video transcoding and AI inference tasks in Docker containers or as external endpoints, and are often co-located on the same hardware as Orchestrators.

​
Node Types and Network Architecture

The Network nodes that perform work and interact with the on-chain protocol are implemented by go-livepeer as different Node Types, which conditionally enable different functionality and components within the same codebase. A node can operate in multiple roles simultaneously by having multiple flags set during startup.

The Network’s three-layer topology in detail.

​
Node Type Details

A node can operate in multiple roles simultaneously by having multiple flags set during startup.

​
Node Type Details

Purpose: The OrchestratorNode coordinates transcoding work, manages payments, and serves as the intermediary between broadcasters and transcoders.Key Components
ComponentLocationPurpose
orchestrator structcore/orchestrator.goMain orchestrator implementation
Recipientcore/livepeernode.goProbabilistic micropayment recipient
SegmentChanscore/livepeernode.goMap of segment channels per manifest
Balancescore/livepeernode.goTrack broadcaster balances per session
lphttpserver/segment_rpc.goHTTP/RPC handler for segment transcoding
The Orchestrator node type is responsible for performing transcoding and AI inference work. Orchestrators claim jobs, execute them, and earn fees and rewards.Payment Processing Orchestrators validate and process probabilistic micropayments using the ticket system, which involves:
  • Receiving payment information via Livepeer-Payment header
  • Validating tickets with ProcessPayment
  • Crediting balances for the broadcaster session
  • Redeeming winning tickets with the TicketBroker on-chain
  • Managing deposits and reserves to ensure solvency
Capacity Management Orchestrators track capacity and reject work when at maximum sessions:
  • Maximum sessions controlled by MaxSessions variable
  • CheckCapacity verifies if manifest already has a channel or if capacity is available
  • Sessions tracked in SegmentChans map keyed by ManifestID
Segment Transcoding RPC The HTTP RPC endpoint for segment transcoding is implemented in ServeSegment:
  • Parse Headers: Extract payment and segment data from Livepeer-Payment and Livepeer-Segment headers
  • Process Payment: Call ProcessPayment to validate and credit tickets
  • Submit to Transcoder: Route segment to transcoder via TranscodeSeg
  • Return Results: Encode transcoded data in response
Purpose: The BroadcasterNode is responsible for ingesting live video streams and serving content to viewers. It acts as the entry point for content producers and coordinates with orchestrators for transcoding.Key Components
ComponentLocationPurpose
LivepeerServerserver/mediaserver.goMain media server handling RTMP/HTTP ingestion and HLS playback
RTMPSegmenterserver/mediaserver.goSegments RTMP streams into HLS
rtmpConnectionsserver/mediaserver.goMap of active stream connections
BroadcastSessionsManagerserver/broadcast.goManages sessions with orchestrators
SessionPoolserver/broadcast.goPool of available orchestrator sessions
Initialisation FlowHTTP Push Support Broadcasters can also accept HTTP push ingestion when started with -httpIngest flag:
  • Handler: HandlePush at /live/ endpoint in server/segment_rpc.go
  • Supports multipart responses for transcoded renditions
  • Implements watchdog timer to clean up inactive sessions after httpPushTimeout (60s)
Purpose: The Transcoder node type is responsible for executing video transcoding tasks.Key Components
ComponentLocationPurpose
RemoteTranscoderManagercore/orchestrator.goManages the pool of remote transcoders
LocalTranscodercore/transcoder.goPerforms local ffmpeg-based transcoding
Transcoder interfacecore/transcoder.goAbstracts transcoding operations
liveTranscodercore/orchestrator.goWraps remote transcoder RPC calls
Transcoder Registration Remote transcoders register with an orchestrator using the RegisterTranscoder RPC:The RemoteTranscoderManager maintains two data structures:
  • liveTranscoders (map for lookup) and
  • transcoders (slice for round-robin selection). Each liveTranscoder wraps a gRPC stream with channels for segment distribution (SegmentChan) and result collection (ResultChan).
Transcoding Workflow
  1. Orchestrator receives segment transcoding request via ServeSegment
  2. Orchestrator selects a liveTranscoder from the pool
  3. Segment sent to liveTranscoder’s SegmentChan
  4. Transcoder executes ffmpeg transcoding (local or remote)
  5. Transcoded result sent back via ResultChan
  6. Orchestrator returns transcoded segment to broadcaster
Hardware Acceleration Transcoders support hardware-accelerated transcoding through:
  • Nvidia GPUs: Enabled via -nvidia flag with device IDs
  • Netint VPUs: Enabled via -netint flag
The capabilities are reported during registration and used for session compatibility checking.
Purpose:The Gateway role (enabled via -gateway flag) adds AI inference capabilities to a broadcaster node, allowing it to accept AI requests and coordinate with AI-capable orchestrators.Key Components
ComponentLocationPurpose
AISessionManagerserver/mediaserver.go:117Manages AI orchestrator sessions
AIMediaServer handlersserver/ai_mediaserver.go:63-132Exposes HTTP endpoints for AI requests
AISessionserver/rpc.goRepresents a session with an AI-capable orchestrator
The Gateway node type extends the Broadcaster functionality to support AI inference workloads. It manages sessions with AI-capable orchestrators and exposes HTTP endpoints for AI requests, allowing it to route both video and AI work through the same infrastructure.AI Session SelectionThe AISessionManager selects orchestrators for AI jobs using capability-based filtering:The selection algorithm prioritizes orchestrators with:
  1. Compatible capabilities (correct pipeline and model)
  2. Available capacity
  3. Lowest latency score from previous requests
Live Video AI ProcessingGateway nodes can process live video streams through AI pipelines using the MediaMTX integration:
  1. Stream arrives at MediaMTX (via RTMP/WebRTC)
  2. MediaMTX calls gateway’s /live/video-to-video//start endpoint
  3. Gateway selects orchestrator with live AI capabilities
  4. Segments published to orchestrator via trickle protocol
  5. Processed segments written to output destination
Purpose: The AI Worker node type executes AI inference tasks, either in Docker containers or by routing to external endpoints.Key Components
ComponentLocationPurpose
RemoteAIWorkerManagercore/livepeernode.goManages the pool of remote AI workers
AIWorker interfacecore/livepeernode.goAbstracts AI inference operations
Docker containersExternalModel-specific inference runners
Worker RegistrationAI workers register with an orchestrator similar to transcoders:
  • The RemoteAIWorkerManager tracks workers in liveAIWorkers (map by worker ID) and aiWorkers (slice for selection).
  • Each liveAIWorker maintains a taskChans map keyed by request ID, allowing concurrent requests to the same worker.
Docker Container ManagementOrchestrators with AI worker capability manage Docker containers for model inference:
  1. Container Lifecycle: Containers started on-demand when jobs arrive
  2. GPU Allocation: Orchestrator assigns GPU devices to containers
  3. Health Monitoring: Containers checked for responsiveness
  4. Capacity Tracking: Available/busy container slots tracked per model
The container stop timeout is configurable via aiWorkerContainerStopTimeout (default 5s) to allow in-flight requests to complete before forcefully terminating.
Last modified on May 19, 2026