Metadata-Version: 2.5
Name: livepeer-gateway
Version: 1.0.0
Summary: Official Python SDK for submitting AI and video jobs to the Livepeer network
Project-URL: Homepage, https://livepeer.org
Project-URL: Repository, https://github.com/livepeer/livepeer-python-gateway
Project-URL: Issues, https://github.com/livepeer/livepeer-python-gateway/issues
Project-URL: Changelog, https://github.com/livepeer/livepeer-python-gateway/blob/main/CHANGELOG.md
Author: Livepeer Foundation
License: MIT License
        
        Copyright (c) 2026 Livepeer Foundation
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,livepeer,sdk,video
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: av>=11.0.0
Requires-Dist: grpcio>=1.76.0
Requires-Dist: protobuf>=6.31.1
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.76.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: numpy>=2.2.6; extra == 'examples'
Requires-Dist: opencv-python-headless>=4.13.0.90; extra == 'examples'
Description-Content-Type: text/markdown

# 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:

```bash
python -m pip install livepeer-gateway
```

The import package is named `livepeer_gateway`:

```python
from livepeer_gateway import StartJobRequest, start_lv2v
```

## Development

Install the locked development dependencies with
[uv](https://docs.astral.sh/uv/):

```bash
uv sync --locked --group test
```

Generate protobufs after installing the code-generation extra:

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

## Tests

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

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

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

```bash
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:

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

## Usage Examples

First install dependencies for example code
```bash
uv sync --extra examples
```

Get orchestrator info, offchain mode
```bash
uv run examples/get_orchestrator_info.py localhost:8935
```

On-chain mode with a remote signer

```bash
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
```bash
uv run examples/get_orchestrator_info.py --token "<base64-token>"
```

Write raw frames to a LiveVideoToVideo job
```bash
uv run examples/write_frames.py localhost:8935
```

Capture MacOS camera frames and publish via write_frame
```bash
uv run examples/camera_capture.py localhost:8935
```

Capture MacOS camera frames and subscribe to media output (stdout or file)
```bash
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
```python
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
```bash
uv sync --extra examples
uv run examples/in_out_composite.py localhost:8935
```

Subscribe to a LiveVideoToVideo trickle events channel
```bash
uv run examples/subscribe_events.py localhost:8935
```

Start a LiveVideoToVideo job using a token (base64 JSON)
```python
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)

| Field | Type | Description |
|---|---|---|
| `orchestrators` | `string[]` (optional) | Ordered orchestrator addresses to try before discovery |
| `signer` | `string` (optional) | Signer base URL |
| `signer_headers` | `{"key": "value"}` (optional) | Extra HTTP headers sent to all signer endpoints |
| `discovery` | `string` (optional) | Discovery endpoint URL |
| `discovery_headers` | `{"key": "value"}` (optional) | Extra HTTP headers sent to the discovery endpoint |

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).
