} ; }; export const CustomDivider = ({color = "var(--lp-color-border-default)", middleText = "", spacing = "default", style = {}, className = "", ...rest}) => { const spacingPresets = { default: { margin: "24px 0" }, overlap: { margin: "-1rem 0 -1rem 0" }, tight: { margin: "0 0 -1rem 0" }, section: { margin: "0 0 -2rem 0" }, sectionOverlap: { margin: "-1rem 0 -2rem 0" }, deepOverlap: { margin: "-1rem 0 -1.5rem 0" } }; const spacingStyle = spacingPresets[spacing] || spacingPresets.default; return

{middleText && <> {middleText} }

; }; The Gateway's default Orchestrator selection works out of the box: it discovers available Orchestrators, filters by price, and routes jobs.
For production workloads, operators often need more control. Manual selection, quality tiering, and failover configuration. ## Selection Algorithm Before tuning selection, it helps to understand what the Gateway does by default. ```mermaid theme={"theme":{"light":"github-light","dark":"dark-plus"}} %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#18794E', 'primaryTextColor': '#fff', 'primaryBorderColor': '#3CB540', 'lineColor': '#3CB540', 'mainBkg': '#18794E', 'nodeBorder': '#3CB540', 'clusterBkg': 'transparent', 'clusterBorder': '#3CB540', 'titleColor': '#3CB540', 'edgeLabelBackground': 'transparent', 'textColor': '#3CB540', 'nodeTextColor': '#fff'}}}%% sequenceDiagram participant GW as Gateway participant Pool as Orchestrator Pool participant Scoring as Selection Algorithm participant Orch as Selected Orchestrator GW->>Pool: Query OrchestratorInfo (capabilities, price, hardware) Pool-->>GW: Candidate list GW->>GW: Filter: capabilities match + price within cap GW->>GW: Apply blocklist GW->>Scoring: Score candidates (stake x price x random x perf) Scoring-->>GW: Ranked list GW->>Orch: Dispatch job Orch-->>GW: Result + payment acknowledgement ``` The scoring algorithm is a weighted combination of four factors, each adjustable via flags: Factor Flag Default behaviour Randomness `-selectRandFreq` Prevents all traffic concentrating on one Orchestrator LPT stake `-selectStakeWeight` Favours Orchestrators with more stake Price `-selectPriceWeight` Favours lower-priced Orchestrators Price sensitivity `-selectPriceExpFactor` Controls how much small price differences matter For AI Gateways using an explicit Orchestrator list (`-orchAddr`), the selection algorithm is simpler: the Gateway round-robins across the listed Orchestrators while respecting capability and price filters. ## Workload Criteria Different workloads have different priorities: Criterion Video AI Dual Latency Critical for real-time Important for UX Both Price Important Important Both Codec capability Required Not applicable Video path AI model / pipeline Not applicable Required AI path GPU type Less critical Critical (VRAM) Critical Historical performance High weight Medium weight Both Minimum version `-orchMinLivepeerVersion` Optional Optional ## Orchestrator Settings ### Pinning Orchestrators For off-chain AI Gateways, the most reliable approach is to maintain an explicit list of known-good Orchestrators. The Gateway round-robins across this list and does not discover others. ```bash icon="terminal" -orchAddr theme={"theme":{"light":"github-light","dark":"dark-plus"}} -orchAddr https://orch1.example.com:8935,https://orch2.example.com:8935,https://orch3.example.com:8935 ``` This trades network-wide discovery flexibility for predictability: the operator knows exactly which Orchestrators handle jobs and can vet each one before adding it. This is the recommended approach for production AI workloads. To find AI-capable Orchestrators: * [Livepeer Explorer](https://explorer.livepeer.org) AI leaderboard * [tools.Livepeer.cloud](https://tools.livepeer.cloud) - community tool suite with Orchestrator performance data * The `/getNetworkCapabilities` endpoint on the Gateway, filtered by pipeline and model ### Dynamic Discovery For video Gateways and on-chain AI Gateways that draw from the full network, use webhook-based discovery instead of a static list. ```bash icon="terminal" -orchWebhookUrl theme={"theme":{"light":"github-light","dark":"dark-plus"}} -orchWebhookUrl https://discovery-service.example.com/orchestrators ``` The webhook endpoint returns a JSON array of Orchestrator URIs. The Gateway calls this URL at session start to get a fresh candidate list, then applies its scoring algorithm. This allows maintaining a curated Orchestrator pool externally, with the Gateway fetching updates dynamically. A simple webhook can be a static JSON file served by a web server. Update it when adding or removing Orchestrators from the preferred pool. ### Performance Scoring Beyond the built-in selection weights, the Gateway can use an external performance scoring service to influence Orchestrator selection. ```bash icon="terminal" -orchPerfStatsUrl -minPerfScore theme={"theme":{"light":"github-light","dark":"dark-plus"}} -orchPerfStatsUrl https://leaderboard.livepeer.org/api/aggregated_stats -minPerfScore 0.8 ``` `-orchPerfStatsUrl` points to a service that returns per-Orchestrator performance statistics. The Livepeer community leaderboard provides this data. `-minPerfScore` sets a minimum acceptable score; Orchestrators below this threshold are excluded regardless of price. Performance scores are calculated from live transcoding tests run by the leaderboard against each registered Orchestrator. Scores range from 0 to 1, where 1 represents consistently correct transcoding output within latency targets. For production video transcoding, a minimum score of 0.8 or higher is recommended. ### Blocklisting To exclude an Orchestrator producing incorrect results, charging unexpected prices, or behaving maliciously: ```bash icon="terminal" -orchBlocklist theme={"theme":{"light":"github-light","dark":"dark-plus"}} -orchBlocklist 0xAbCd1234...,0xEfGh5678... ``` Blocklisted Orchestrators are excluded from all selection regardless of price or capability. Pass Ethereum addresses as a comma-separated list. This flag takes effect at process start; to update it, restart the Gateway. The blocklist is a last resort, not a tier management tool. For tiering, use the performance score threshold and price caps instead. ## Tiering Strategy Operators running a Gateway-as-service with SLA commitments route different customer tiers to different Orchestrator quality levels. Since go-livepeer does not natively support named tiers, the pattern is to run separate Gateway instances per tier, each with a different configuration. ```icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} Tier 1 (premium) -> Gateway instance A -orchAddr -maxPricePerUnit 5000 # Higher cap = access to better Orchestrators -minPerfScore 0.95 Tier 2 (standard) -> Gateway instance B -orchAddr -maxPricePerUnit 2000 -minPerfScore 0.8 Tier 3 (budget) -> Gateway instance C -maxPricePerUnit 500 # No minPerfScore - accepts wider range ``` The middleware layer (see ) routes incoming requests to the correct Gateway instance based on the customer's tier. ## Failover Behaviour When an Orchestrator fails mid-job, the Gateway automatically swaps to the next candidate in its selection pool. For video transcoding, the stream continues on a new Orchestrator with segments re-attempted. For AI inference, the request is retried on a different Orchestrator. The number of retry attempts before the job fails is controlled by `-maxAttempts` (video transcoding). For AI jobs, the retry behaviour depends on the pipeline. High Orchestrator swap rates indicate instability in the Orchestrator pool, such as under-resourced machines or network issues. To reduce swaps: * Increase `-minPerfScore` to exclude poorly-performing Orchestrators proactively * Add `-orchMinLivepeerVersion` to exclude outdated nodes * Review `-maxPricePerUnit` or `-maxPricePerCapability` ceiling: if it is too low, the Gateway may be cycling through marginal Orchestrators Monitor the `livepeer_orchestrator_swaps` Prometheus counter to track swap frequency over time. If the Gateway cannot find a suitable Orchestrator within the discovery window, the job fails. The timeout is configurable: ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} -discoveryTimeout 10s ``` Increase this if jobs fail because no Orchestrator was found, particularly at startup or after a blocklist change. Decrease it for faster failure detection in latency-sensitive applications. ## AI Capability Matching For AI Gateways, Orchestrator selection is driven by capability matching before any price or performance scoring applies. The Gateway only considers Orchestrators that declare support for the requested pipeline and model. Capability information is returned by `/getNetworkCapabilities`. To inspect which Orchestrators support a specific model: ```bash icon="terminal" /getNetworkCapabilities theme={"theme":{"light":"github-light","dark":"dark-plus"}} curl http://localhost:8935/getNetworkCapabilities | \ jq '.orchestrators[] | select(.capabilities_prices[].model_id == "black-forest-labs/FLUX.1-dev")' ``` Set per-capability price caps to control costs per pipeline: ```bash icon="terminal" -maxPricePerCapability theme={"theme":{"light":"github-light","dark":"dark-plus"}} -maxPricePerCapability '[{"pipeline":"text-to-image","model_id":"black-forest-labs/FLUX.1-dev","price_per_unit":100,"pixels_per_unit":1000000}]' ``` If no Orchestrator in the pool meets both the capability requirement and the price cap, the job fails. To relax the price cap instead of fail the job: ```bash icon="terminal" -ignoreMaxPriceIfNeeded theme={"theme":{"light":"github-light","dark":"dark-plus"}} -ignoreMaxPriceIfNeeded ``` ## Monitoring Selection Track selection health in production: Signal Source What to watch Swap rate Prometheus `livepeer_orchestrator_swaps` Rising trend = instability Success rate Prometheus (calculated) Below 0.95 = investigate Connected Orchestrators `/getNetworkCapabilities` Fewer than expected = discovery issue Orchestrator status `livepeer_cli` Option 1 Active connection and pricing Performance scores leaderboard.livepeer.org Comparison vs network ## Related Pages Prometheus metrics for tracking Orchestrator swap rates and selection health. Session limits and when to scale horizontally. Full OrchestratorInfo data structure and discovery API reference. All selection and scoring flags in one place.