Metadata-Version: 2.5
Name: alpha-avatar-rtc
Version: 0.6.8
Summary: RTC transport adapters for AlphaAvatar.
Project-URL: Source, https://github.com/AlphaAvatar/AlphaAvatar
Project-URL: Issues, https://github.com/AlphaAvatar/AlphaAvatar/issues
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.13
Requires-Dist: alpha-avatar-core
Provides-Extra: livekit
Requires-Dist: alpha-avatar-core[video]; extra == 'livekit'
Requires-Dist: livekit<2,>=1.0.12; extra == 'livekit'
Description-Content-Type: text/markdown

# AlphaAvatar RTC

`alpha-avatar-rtc` owns transport-specific adapters. Its base package depends only on `alpha-avatar-core`; the `livekit` extra enables LiveKit codecs and adapters.

```python
from alphaavatar.rtc.livekit.audio.codec import from_livekit_audio_frame, to_livekit_audio_frame
from alphaavatar.rtc.livekit.audio.input import LiveKitAudioInput
from alphaavatar.rtc.livekit.audio.output import LiveKitTransientAudioOutput
from alphaavatar.rtc.livekit.status.output import LiveKitStatusOutput
from alphaavatar.rtc.livekit.text import LiveKitTextInput
from alphaavatar.rtc.livekit.transcript.output import LiveKitTranscriptOutput
from alphaavatar.rtc.livekit.video.codec import from_livekit_video_frame, to_livekit_video_frame
from alphaavatar.rtc.livekit.video.input import LiveKitVideoInput
```

Transport-neutral image conversion lives in `alphaavatar.core.media.codecs.video` and is available through `alpha-avatar-core[video]`.

## 📦 Package structure

```text
alphaavatar/rtc/livekit/
├── audio/                # PCM codecs, audio ingress and output transport.
├── video/                # Video codecs and video ingress.
├── text/                 # Bounded text-stream ingress.
├── transcript/           # Transcript delivery.
├── status/               # User-facing status delivery.
└── utils/                # LiveKit event-binding helpers.
```

Selected files and feature directories are shown; ordinary package initializers are omitted.

## Lifecycle and ownership

Media inputs receive a LiveKit room and shared PerceptionRuntime. Text input receives an injected submit callback; Host binds it to Engine admission without introducing an RTC-to-Agents dependency. Output adapters receive a room and shared OutputRuntime.

Adapters expose `on_start()` and `on_stop()` for Core lifecycle coordination. Each owns its subscriptions, callbacks, tasks and transport resources. It must not close the shared room, PerceptionRuntime or OutputRuntime. Host SessionManager orders attachment outputs, Engine and inputs in the execution child. SessionAttachment releases adapters and its connection; HostExecution separately settles Engine and AvatarRuntime. LiveKitConnection reports transport events and never closes an execution or deletes a room.

Partial startup triggers owned cleanup. Concurrent shutdown callers share cleanup, and caller cancellation is propagated after it settles. Closed input adapters are not restarted. Video conversion remains off the event-loop thread, with source-generation checks before publication.

The package root does not import a backend. RTC adapters must not depend on `alphaavatar.agents`, concrete perception plugins or `livekit.agents`.

## Native input and output

`LiveKitTextInput` consumes the `lk.chat` text stream, checks the transport-supplied sender identity and bounded complete content, then invokes the injected submit callback. It does not pre-publish a second perception copy. Attached byte streams are not implemented by this text adapter.

Despite its retained class name, `LiveKitTransientAudioOutput` serves both ASSISTANT and TRANSIENT output on one audio track. It does not own a model or a second TTS pipeline. Host supplies the audio format declared by the selected TTS provider.

Consumers read `event.output` and its typed scope, source and payload. Interruptions use Runtime-fixed exact targets, not a new broad match against a later output. Playback feedback and final transcript delivery remain distinct from generation completion. Internal status decisions and canonical records are not projected as client status content.

## Migration status

Codecs, media/text inputs and audio/status/transcript outputs live here. Application assembly lives in Host. Engine/Loop own native generation; Router owns synthesis and transcript synchronization. The obsolete SDK model/turn/response and record bridges are removed, not alternative supported paths.

Voice provides native async PCM synthesis; RTC only converts/delivers the resulting Core frames. Native Host owns application and execution-process hosting; it does not use the Agents SDK worker. Native Character presentation is assembled by Host. Audio/video input adapters accept an immutable snapshot of `excluded_participant_identities`; filtering happens before creating a source generation or stream reader, for both existing and newly subscribed tracks. Host excludes only the exact renderer identity, without feeding Character output back into perception. This migration does not yet provide connection-independent execution or persistent task recovery.
