{"id":47289598,"url":"https://github.com/spatialwalk/livekit-plugins-spatialreal","last_synced_at":"2026-03-16T06:46:07.514Z","repository":{"id":337482390,"uuid":"1149596083","full_name":"spatialwalk/livekit-plugins-spatialreal","owner":"spatialwalk","description":"LiveKit Agents Plugin for SpatialReal Avatar","archived":false,"fork":false,"pushed_at":"2026-03-01T05:07:26.000Z","size":207,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T07:33:39.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/project/livekit-plugins-spatialreal/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatialwalk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-04T09:47:14.000Z","updated_at":"2026-03-01T05:07:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spatialwalk/livekit-plugins-spatialreal","commit_stats":null,"previous_names":["spatialwalk/livekit-plugins-spatialreal"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/spatialwalk/livekit-plugins-spatialreal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatialwalk%2Flivekit-plugins-spatialreal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatialwalk%2Flivekit-plugins-spatialreal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatialwalk%2Flivekit-plugins-spatialreal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatialwalk%2Flivekit-plugins-spatialreal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatialwalk","download_url":"https://codeload.github.com/spatialwalk/livekit-plugins-spatialreal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatialwalk%2Flivekit-plugins-spatialreal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30570922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-16T06:02:37.763Z","status":"ssl_error","status_checked_at":"2026-03-16T06:02:14.913Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-16T06:46:06.664Z","updated_at":"2026-03-16T06:46:07.488Z","avatar_url":"https://github.com/spatialwalk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LiveKit Agents Plugin for SpatialReal Avatar\n\nThis plugin provides integration with [SpatialReal](https://spatialreal.com)'s avatar service for lip-synced avatar rendering in LiveKit voice agents.\n\n## Installation\n\n```bash\npip install livekit-plugins-spatialreal\n```\n\nOr install from source:\n\n```bash\npip install -e .\n```\n\n## Configuration\n\nSet the following environment variables:\n\n```bash\n# Required\nSPATIALREAL_API_KEY=your-api-key\nSPATIALREAL_APP_ID=your-app-id\nSPATIALREAL_AVATAR_ID=your-avatar-id\n\n# Optional\nSPATIALREAL_CONSOLE_ENDPOINT=\nSPATIALREAL_INGRESS_ENDPOINT=\n\n# LiveKit credentials\nLIVEKIT_URL=\nLIVEKIT_API_KEY=\nLIVEKIT_API_SECRET=\n```\n\n## Usage\n\n```python\nfrom livekit.agents import Agent, AgentSession, JobContext, cli, WorkerOptions\nfrom livekit.plugins import spatialreal\n\nclass VoiceAssistant(Agent):\n    def __init__(self):\n        super().__init__(\n            instructions=\"You are a helpful voice assistant.\"\n        )\n\nasync def entrypoint(ctx: JobContext):\n    await ctx.connect()\n\n    # Configure your pipeline components (VAD, STT, LLM, TTS)\n    session = AgentSession(\n        vad=vad,\n        stt=stt,\n        llm=llm,\n        tts=tts,\n    )\n\n    # Initialize and start the avatar session\n    avatar = spatialreal.AvatarSession()\n    await avatar.start(session, room=ctx.room)\n\n    # Start the agent session\n    await session.start(\n        agent=VoiceAssistant(),\n        room=ctx.room,\n    )\n\nif __name__ == \"__main__\":\n    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))\n```\n\nFor production agents, catch `SpatialRealException` so you can decide whether to fail the job or continue without avatar output:\n\n```python\ntry:\n    await avatar.start(session, room=ctx.room)\nexcept spatialreal.SpatialRealException as err:\n    logger.error(\"Avatar startup failed: %s\", err)\n    raise\n```\n\n## API Reference\n\n### `AvatarSession`\n\nMain class for integrating SpatialReal avatars with LiveKit agents.\n\n#### Constructor Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `api_key` | `str` | SpatialReal API key (or set `SPATIALREAL_API_KEY`) |\n| `app_id` | `str` | SpatialReal application ID (or set `SPATIALREAL_APP_ID`) |\n| `avatar_id` | `str` | Avatar ID to use (or set `SPATIALREAL_AVATAR_ID`) |\n| `console_endpoint_url` | `str` | Custom console endpoint URL |\n| `ingress_endpoint_url` | `str` | Custom ingress endpoint URL |\n| `avatar_participant_identity` | `str` | LiveKit identity for avatar participant |\n| `idle_timeout_seconds` | `int` | LiveKit egress idle timeout in seconds (`0` uses server defaults) |\n| `sample_rate` | `int \\| None` | Optional avatar audio sample rate override |\n\n#### Methods\n\n- `start(agent_session, room, *, livekit_url, livekit_api_key, livekit_api_secret)`: Start the avatar session and hook into the agent's audio output. Raises `SpatialRealException` with actionable context if startup fails.\n- `aclose()`: Clean up avatar session resources.\n\nWhen starting, the plugin automatically sets `lk.publish_on_behalf` to the\nagent participant identity for avatar worker association in LiveKit frontends.\n\n### `SpatialRealException`\n\nException raised for SpatialReal-related errors.\n\n## How It Works\n\n1. The plugin intercepts TTS audio output from the agent session\n2. Audio frames are forwarded to SpatialReal's avatar service\n3. SpatialReal generates lip-synced video and audio\n4. The avatar joins the LiveKit room and publishes the synchronized streams\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatialwalk%2Flivekit-plugins-spatialreal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatialwalk%2Flivekit-plugins-spatialreal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatialwalk%2Flivekit-plugins-spatialreal/lists"}