Metadata-Version: 2.4
Name: livekit-plugins-runway
Version: 1.5.12
Summary: Agent Framework plugin for Runway Characters Avatar
Project-URL: Documentation, https://docs.livekit.io
Project-URL: Website, https://livekit.io/
Project-URL: Source, https://github.com/livekit/agents
Author-email: LiveKit <support@livekit.io>
License-Expression: Apache-2.0
Keywords: ai,audio,avatar,livekit,realtime,runway,video,voice
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10.0
Requires-Dist: livekit-agents>=1.5.12
Description-Content-Type: text/markdown

# livekit-plugins-runway

[LiveKit Agents](https://docs.livekit.io/agents/) plugin for [Runway Characters](https://dev.runwayml.com/) avatar integration.

Your LiveKit agent owns the full conversational AI pipeline (STT, LLM, TTS). Runway provides the visual layer — audio in, avatar video out.

## Installation

```bash
pip install livekit-plugins-runway
```

## Usage

```python
from livekit.agents import AgentSession, Agent, RoomOutputOptions
from livekit.plugins import runway

async def entrypoint(ctx):
    session = AgentSession()

    avatar = runway.AvatarSession(
        avatar_id="your-custom-avatar-id",
        # api_key defaults to RUNWAYML_API_SECRET env var
    )
    await avatar.start(session, room=ctx.room)

    await session.start(
        agent=Agent(instructions="Talk to me!"),
        room=ctx.room,
        room_output_options=RoomOutputOptions(audio_enabled=False),
    )
```

### Using a preset avatar

```python
avatar = runway.AvatarSession(
    preset_id="runway-preset-slug",
)
```

### With a session duration limit

```python
avatar = runway.AvatarSession(
    avatar_id="your-custom-avatar-id",
    max_duration=300,
)
```

## Configuration

| Parameter | Env var | Description |
|-----------|---------|-------------|
| `api_key` | `RUNWAYML_API_SECRET` | Runway API key |
| `api_url` | `RUNWAYML_BASE_URL` | API base URL (default: `https://api.dev.runwayml.com`) |
| `avatar_id` | — | Custom avatar ID (mutually exclusive with `preset_id`) |
| `preset_id` | — | Preset avatar slug (mutually exclusive with `avatar_id`) |
| `max_duration` | — | Maximum session duration in seconds |

LiveKit credentials (`LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`) are read from environment variables or can be passed to `avatar.start()`.
