Metadata-Version: 2.5
Name: livekit-plugins-inworld
Version: 2.0.0b2
Summary: Agent Framework plugin for voice synthesis and speech-to-text with Inworld's API.
Project-URL: Documentation, https://docs.livekit.io
Project-URL: Website, https://livekit.io/
Project-URL: Source, https://github.com/livekit/agents
Author-email: LiveKit <hello@livekit.io>
License-Expression: Apache-2.0
Keywords: ai,audio,inworld,livekit,realtime,speech-to-text,stt,tts,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.11
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11.0
Requires-Dist: livekit-agents>=2.0.0b2
Description-Content-Type: text/markdown

# Inworld plugin for LiveKit Agents

Support for voice synthesis and speech-to-text with [Inworld TTS](https://docs.inworld.ai/tts/tts) and [Inworld STT](https://docs.inworld.ai/stt/overview).

See [Inworld TTS](https://docs.livekit.io/agents/integrations/tts/inworld/) and [Inworld STT](https://docs.livekit.io/agents/models/stt/inworld/) for more information.

## Installation

```bash
pip install livekit-plugins-inworld
```

## Authentication

Set `INWORLD_API_KEY` in your `.env` file ([get one here](https://platform.inworld.ai/login)).

## Usage

### TTS

Use Inworld TTS within a `VoiceSession` or as a standalone speech generator.

```python
from livekit.plugins import inworld

tts = inworld.TTS()
```

Or with options:

```python
from livekit.plugins import inworld

tts = inworld.TTS(
    voice="Hades",                 # voice ID (default or custom cloned voice)
    model="inworld-tts-1",         # or "inworld-tts-1-max"
    encoding="OGG_OPUS",           # LINEAR16, MP3, OGG_OPUS, ALAW, MULAW, FLAC
    sample_rate=48000,             # 8000-48000 Hz
    bit_rate=64000,                # bits per second (for compressed formats)
    speaking_rate=1.0,             # 0.5-1.5
    temperature=1.1,               # 0-2
    timestamp_type="WORD",         # WORD, CHARACTER, or TIMESTAMP_TYPE_UNSPECIFIED
    text_normalization="OFF",      # ON, OFF, or APPLY_TEXT_NORMALIZATION_UNSPECIFIED
)
```

### TTS Streaming

Inworld TTS supports WebSocket streaming for lower latency real-time synthesis. Use the
`stream()` method for streaming text as it's generated:

```python
from livekit.plugins import inworld

tts = inworld.TTS(
    voice="Hades",
    model="inworld-tts-1",
    buffer_char_threshold=100,     # chars before triggering synthesis (default: 100)
    max_buffer_delay_ms=3000,      # max buffer time in ms (default: 3000)
)

# Create a stream for real-time synthesis
stream = tts.stream()

# Push text incrementally
stream.push_text("Hello, ")
stream.push_text("how are you today?")
stream.flush()  # Flush any remaining buffered text
stream.end_input()  # Signal end of input

# Consume audio as it's generated
async for audio in stream:
    # Process audio frames
    pass
```

### STT

Use Inworld STT for streaming speech-to-text. Multiple models are supported.

```python
from livekit.plugins import inworld

session = VoiceSession(
   stt=inworld.STT()
   # ... llm, tts, etc.
)
```

With a specific model and voice profile detection:

```python
from livekit.plugins import inworld

session = VoiceSession(
   stt=inworld.STT(
       model="inworld/inworld-stt-1",
       enable_voice_profile=True,
   )
   # ... llm, tts, etc.
)
```

### Example

A full voice agent using Inworld for both STT and TTS:

```python
"""Inworld STT + TTS voice agent example.

Demonstrates using Inworld for both speech-to-text and text-to-speech
in a LiveKit voice agent. Save this as ``inworld_agent.py`` and run:

    uv run inworld_agent.py console   # local console mode
    uv run inworld_agent.py dev       # LiveKit Cloud (requires LIVEKIT_URL,
                                      # LIVEKIT_API_KEY, LIVEKIT_API_SECRET)

Then connect via https://agents-playground.livekit.io
"""

from dotenv import load_dotenv

from livekit.agents import (
    Agent,
    AgentServer,
    JobContext,
    VoiceSession,
    cli,
    inference,
    room_io,
)
from livekit.plugins import inworld

load_dotenv()


assistant = Agent(
    instructions=(
        "Your name is Nova. You interact with users via voice. "
        "Keep your responses concise and to the point. "
        "Do not use emojis, asterisks, markdown, or other special characters. "
        "You are helpful, curious, and friendly."
    ),
)


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    ctx.log_context_fields = {"room": ctx.room.name}

    session = VoiceSession(
        stt=inworld.STT(model="inworld/inworld-stt-1"),
        llm="openai/gpt-4.1-mini",
        tts=inworld.TTS(voice="Clive"),
        vad=inference.VAD(),
    )

    await session.start(
        agent=assistant,
        room=ctx.room,
        room_options=room_io.RoomOptions(),
    )
    await session.generate_reply()


if __name__ == "__main__":
    cli.run_app(server)
```

### Combined TTS + STT

```python
from livekit.plugins import inworld

session = VoiceSession(
   tts=inworld.TTS(voice="Hades"),
   stt=inworld.STT(),
   # ... llm, etc.
)
```
