livekit/python-sdks

LiveKit Python SDK

정의 – Python 프로그램을 LiveKit 서버(클라우드 호스팅 또는 자체 호스팅)에 연결하고 비디오/오디오 룸에서 실시간 참가자로 작동할 수 있게 해주는 Python 패키지 쌍입니다. 한 패키지(livekit)는 실시간 클라이언트 API를 제공하고, 다른 패키지(livekit-api)는 토큰 생성 및 REST 스타일 룸 관리와 같은 서버 측 헬퍼를 제공합니다.

중요성 – LiveKit은 저지연, 다자간 비디오, 오디오 및 데이터 스트림을 위한 플랫폼입니다. Python에서 이러한 기능을 노출함으로써 SDK는 다음을 쉽게 구축할 수 있게 합니다.

• AI 기반 음성 에이전트(음성-텍스트, LLM 기반 대화, 텍스트-음성, 턴 감지)가 실시간 통화 내에서 실행됩니다.
• Python 코드에서 미디어를 게시하거나 소비해야 하는 실시간 스트리밍 또는 브로드캐스팅 애플리케이션.
• 서버 API를 통해 룸, egress/ingress, SIP 다이얼링 또는 에이전트 디스패치를 조정하는 사용자 지정 백엔드.

주요 구성 요소

구성 요소	목적
livekit	LiveKit 룸에 연결하고, 오디오/비디오 트랙을 게시/수신하고, 이벤트를 처리하고, 참가자 간 RPC를 지원합니다.
livekit-api	JWT 액세스 토큰을 생성하고, 비동기 aiohttp를 사용하여 서버 엔드포인트(룸 생성/목록, egress, SIP, 에이전트 디스패치 등)를 호출합니다.
MediaDevices(livekit.rtc 내)	마이크 캡처 및 스피커 재생을 위한 sounddevice 라이브러리의 고급 래퍼로, 내장 음향 에코 제거, 노이즈 억제 등을 제공합니다.
RPC 시스템	Python 코루틴을 원격 메서드로 등록하고 다른 참가자에서 호출할 수 있습니다. LLM 함수 호출을 전달하는 데 유용합니다.
에이전트 통합	SDK는 별도의 LiveKit Agents 프레임워크와 결합하여 공급자 키를 관리하지 않고 내부적으로 STT, LLM, TTS, 턴 감지 및 도구 사용을 수행하는 음성 AI 봇을 실행할 수 있습니다.

일반적인 워크플로우

1. 설치 – pip install livekit livekit-api.
2. 토큰 생성(백엔드) api.AccessToken() 및 적절한 권한 사용.
3. 연결 – room = rtc.Room(); await room.connect(url, token).
4. 미디어 게시 – MediaDevices를 사용하여 마이크 또는 스피커를 열고, LocalAudioTrack/LocalVideoTrack으로 소스를 래핑하고 게시합니다.
5. 이벤트 처리 – room.on("track_subscribed", ...)과 같은 콜백을 등록하여 원격 스트림을 수신합니다.
6. 선택적 RPC – @room.local_participant.register_rpc_method로 메서드를 등록하고 다른 참가자에서 perform_rpc로 호출합니다.
7. 서버 측 관리 – LiveKitAPI를 사용하여 룸 생성, 참가자 목록, egress 녹화 시작, SIP 참가자 다이얼링 등을 수행합니다.

예시 코드 조각

# 토큰 생성(백엔드)
from livekit import api
token = api.AccessToken().with_identity("bot").with_grants(
    api.VideoGrants(room_join=True, room="demo")
).to_jwt()

# 연결 및 마이크 게시
from livekit import rtc
room = rtc.Room()
await room.connect(LIVEKIT_URL, token)

devices = rtc.MediaDevices()
mic = devices.open_input(enable_aec=True, noise_suppression=True)
track = rtc.LocalAudioTrack.create_audio_track("mic", mic.source)
await room.local_participant.publish_track(track)

다음 단계

• examples/ 폴더를 살펴보세요(기본 룸, 얼굴 랜드마크, hue 비디오, 전이중 오디오).
• STT/LLM/TTS를 포함한 음성 AI 봇을 원한다면 LiveKit Agents 문서를 읽어보세요.
• 도움말 및 기여를 위해 LiveKit Slack 커뮤니티에 참여하세요.

라이선스 – SDK는 MIT 라이선스로 배포됩니다(리포지토리에 명시됨).