Livepeer Python SDK

The official Python SDK for the Livepeer network. Submit AI and video compute jobs directly to orchestrators, use a remote signer for payment, and stream media and control data over Livepeer's trickle protocol.

Requirements

• Python 3.12 or newer

Installation

Install the stable release from PyPI:

python -m pip install livepeer-gateway

The import package is named livepeer_gateway:

from livepeer_gateway import StartJobRequest, start_lv2v

Development

Install the locked development dependencies with uv:

uv sync --locked --group test

Generate protobufs after installing the code-generation extra:

uv sync --extra dev
uv run generate-lp-rpc

Tests

Install the locked test dependencies and run the complete pytest suite:

uv sync --locked --group test
uv run --group test pytest

Pass a test file or node ID to pytest for a focused run:

uv run --group test pytest tests/test_live_runner.py
uv run --group test pytest tests/test_live_runner.py::TestLiveRunnerHelpers::test_parse_go_duration

Run the suite with the configured line and branch coverage:

uv run --group test pytest --cov=livepeer_gateway --cov-branch --cov-report=term-missing

Usage Examples

First install dependencies for example code

uv sync --extra examples

Get orchestrator info, offchain mode

uv run examples/get_orchestrator_info.py localhost:8935

On-chain mode with a remote signer

uv run examples/get_orchestrator_info.py --signer "<signer-host:port>"

# Use a custom discovery endpoint to filter orchestrators
uv run examples/get_orchestrator_info.py --signer "<signer-host:port>" '<discovery-host>/discover-orchestrators?cap=streamdiffusion-sdxl-v2v'

Get orchestrator info using a token encoding signer / discovery parameters

uv run examples/get_orchestrator_info.py --token "<base64-token>"

Write raw frames to a LiveVideoToVideo job

uv run examples/write_frames.py localhost:8935

Capture MacOS camera frames and publish via write_frame

uv run examples/camera_capture.py localhost:8935

Capture MacOS camera frames and subscribe to media output (stdout or file)

uv run examples/camera_capture.py localhost:8935 --output - | ffplay -fflags nobuffer -flags low_delay -probesize 32 -i -
uv run examples/camera_capture.py localhost:8935 --output out.ts

Read demuxed media output packets without decoding

async with job.media_output() as output:
    async for packet in output.packets():
        print(packet.kind, packet.stream_index, packet.pts_time, packet.size)

Composite camera input and decoded output side-by-side with PTS delta

uv sync --extra examples
uv run examples/in_out_composite.py localhost:8935

Subscribe to a LiveVideoToVideo trickle events channel

uv run examples/subscribe_events.py localhost:8935

Start a LiveVideoToVideo job using a token (base64 JSON)

import base64
import json

from livepeer_gateway.lv2v import StartJobRequest, start_lv2v

payload = {
    "orchestrators": [
        "https://orch-1.example.com:8935",
        "https://orch-2.example.com:8935",
    ],
    "signer": "https://signer.example.com",
    "signer_headers": {"Authorization": "Bearer abcdef"},
    "discovery": "https://discovery.example.com",
    "discovery_headers": {"Authorization": "Bearer qwerty"},
}
token = base64.b64encode(json.dumps(payload).encode("utf-8")).decode("utf-8")

job = start_lv2v(
    orch_url=None,
    req=StartJobRequest(model_id="noop"),
    token=token,
    timeout=5.0,  # timeout for the initial /live-video-to-video request
    # signer_url="https://fallback-signer.example.com",  # used only if token omits signer
)

Token schema (base64-encoded JSON object)

Token values take precedence over explicit keyword arguments. Explicit keyword arguments are used only for fields missing in the token.

For token payloads, orchestrators must be a JSON array of non-empty strings. Comma-delimited string format is not supported in the token.

Selection/discovery precedence (highest -> lowest):

1. token orchestrators
2. explicit orch_url
3. token discovery
4. explicit discovery_url
5. signer-derived discovery endpoint

signer_headers are sent with requests to the signer service. discovery_headers are only used when an explicit discovery_url is provided (and not when using the signer service as a discovery fallback).