> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Pipecat
> Pipecat AI 음성 파이프라인에 표현력 있는 Typecast 음성을 추가하세요.
[Pipecat](https://github.com/pipecat-ai/pipecat)은 실시간 멀티모달 AI 음성 에이전트를 구축하기 위한 오픈 소스 프레임워크입니다. Typecast TTS 통합을 사용하면 감정 제어가 가능한 고품질 뉴럴 음성을 음성 AI 파이프라인에 추가할 수 있습니다.
## Pipecat이란?
Pipecat은 음성 AI 애플리케이션 구축을 단순화하는 Python 프레임워크입니다. 다양한 서비스(음성-텍스트 변환, LLM, 텍스트-음성 변환)를 통합 파이프라인으로 연결하여 실시간 오디오 스트리밍, 턴테이킹, 전송 프로토콜의 복잡성을 처리합니다.
일반적인 Pipecat 파이프라인은 다음과 같습니다:
```
사용자 오디오 → STT → LLM → TTS → 봇 오디오
```
Typecast TTS 서비스(`pipecat-ai-typecast`)는 이 파이프라인에 원활하게 통합되어 LLM 응답을 표현력 있는 음성으로 변환합니다.
***
## 할 수 있는 것
Typecast Pipecat 통합을 사용하면 다음을 할 수 있습니다:
* 자연스럽고 표현력 있는 음성으로 **음성 AI 에이전트 구축**
* 다양한 성별, 나이, 스타일의 **500개 이상의 음성 중 선택**
* **감정 적용** (happy, sad, angry, whisper 등)
* 문맥 인식 음성 합성을 위한 **스마트 이모션 사용**
* 어디서든 **배포** — Daily, Twilio, 또는 네이티브 WebRTC
***
## 사전 요구 사항
시작하기 전에 다음을 준비하세요:
| 요구 사항 | 버전 |
| ----------- | --------------------------------------------- |
| Python | 3.10+ |
| Pipecat | v0.0.94+ |
| 타입캐스트 API 키 | [여기서 받기](https://typecast.ai/developers/api/) |
***
## 설치
Pipecat용 Typecast TTS 서비스를 설치하세요:
```bash theme={null}
pip install pipecat-ai-typecast
```
uv를 사용하시나요? 대신 `uv add pipecat-ai-typecast`를 실행하세요.
***
## 빠른 시작
Pipecat 파이프라인에 Typecast TTS를 통합하는 최소 예제입니다:
```python theme={null}
import os
import aiohttp
from pipecat.pipeline.pipeline import Pipeline
from pipecat_typecast import TypecastTTSService
async with aiohttp.ClientSession() as session:
# Typecast TTS 초기화
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
voice_id=os.getenv("TYPECAST_VOICE_ID", "tc_672c5f5ce59fac2a48faeaee"),
)
# 파이프라인 구축
pipeline = Pipeline([
transport.input(), # 사용자 오디오 입력
stt, # 음성-텍스트 변환
context_aggregator.user(), # 문맥에 사용자 텍스트 추가
llm, # LLM이 응답 생성
tts, # Typecast TTS 합성
transport.output(), # 사용자에게 오디오 스트리밍
context_aggregator.assistant(), # 어시스턴트 응답 저장
])
```
환경 변수를 설정하세요:
* `TYPECAST_API_KEY` — 타입캐스트 API 키 (필수)
* `TYPECAST_VOICE_ID` — 사용할 음성 (선택 사항, 기본 음성으로 설정됨)
***
## 구성
`TypecastTTSService`는 프리셋 기반 및 문맥 인식 감정 제어를 모두 지원합니다.
### 기본 구성
```python theme={null}
from pipecat_typecast import TypecastTTSService
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
voice_id="tc_672c5f5ce59fac2a48faeaee",
model="ssfm-v30", # 최신 모델 (기본값)
)
```
### 이모션 프리셋 제어
일관된 음성 스타일링을 위해 미리 정의된 감정 중에서 선택하세요:
```python theme={null}
from pipecat_typecast import (
TypecastTTSService,
TypecastInputParams,
PresetPromptOptions,
OutputOptions,
)
params = TypecastInputParams(
prompt_options=PresetPromptOptions(
emotion_preset="happy", # normal | happy | sad | angry | whisper | toneup | tonedown
emotion_intensity=1.3, # 0.0 - 2.0
),
output_options=OutputOptions(
volume=110, # 0 - 200 (퍼센트)
audio_pitch=2, # -12 ~ 12 (반음)
audio_tempo=1.05, # 0.5 - 2.0 (재생 속도)
),
)
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
params=params,
)
```
### 스마트 이모션 (문맥 인식)
AI가 주변 텍스트에서 감정을 자동으로 추론하도록 합니다:
```python theme={null}
from pipecat_typecast import (
TypecastTTSService,
TypecastInputParams,
SmartPromptOptions,
)
params = TypecastInputParams(
prompt_options=SmartPromptOptions(
previous_text="방금 정말 좋은 소식을 들었어요!", # 최대 2000자
next_text="모두와 공유하고 싶어서 기다려지지 않아요!",
),
)
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
params=params,
)
```
7가지 감정 중에서 수동으로 선택합니다: Normal, Happy, Sad, Angry, Whisper, Tone Up, Tone Down.
일관된 음성 스타일링에 적합합니다.
AI가 텍스트 맥락에서 최적의 감정을 자동으로 감지합니다.
자연스러운 대화에 적합합니다.
### 매개변수 참조
| 매개변수 | 범위 | 설명 |
| ------------------- | --------- | ---------------------------------------------------------------------------- |
| `emotion_preset` | 음성에 따라 다름 | ssfm-v30: `normal`, `happy`, `sad`, `angry`, `whisper`, `toneup`, `tonedown` |
| `emotion_intensity` | 0.0 - 2.0 | 1.0 이상의 값은 표현력을 증가시킴 |
| `audio_pitch` | -12 \~ 12 | 반음 조절 |
| `audio_tempo` | 0.5 - 2.0 | 권장: 0.85 - 1.15 |
| `volume` | 0 - 200 | 퍼센트로 표시되는 오디오 볼륨 |
| `seed` | uint32 | 결정적 합성을 위한 부호 없는 정수 시드 (≥ 0) |
***
## 지원 전송 프로토콜
Pipecat은 여러 전송 프로토콜을 지원합니다. Typecast는 모든 프로토콜에서 작동합니다:
[Daily](https://www.daily.co/)는 WebRTC 기반 비디오 및 오디오 인프라를 제공합니다.
```python theme={null}
from pipecat.transports.daily.transport import DailyParams
transport_params = DailyParams(
audio_in_enabled=True,
audio_out_enabled=True,
vad_analyzer=SileroVADAnalyzer(),
)
```
[Twilio](https://www.twilio.com/)는 전화 네트워크를 통한 음성 통화를 가능하게 합니다.
```python theme={null}
from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams
transport_params = FastAPIWebsocketParams(
audio_in_enabled=True,
audio_out_enabled=True,
vad_analyzer=SileroVADAnalyzer(),
)
```
브라우저 기반 애플리케이션을 위한 네이티브 WebRTC.
```python theme={null}
from pipecat.transports.base_transport import TransportParams
transport_params = TransportParams(
audio_in_enabled=True,
audio_out_enabled=True,
vad_analyzer=SileroVADAnalyzer(),
)
```
***
## 전체 예제
음성 AI 에이전트를 생성하는 완전한 작동 예제입니다:
```python theme={null}
import os
import aiohttp
from dotenv import load_dotenv
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.daily.transport import DailyParams, DailyTransport
from pipecat_typecast import TypecastTTSService
load_dotenv()
async def main():
async with aiohttp.ClientSession() as session:
# 서비스 초기화
stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
)
# 대화 문맥 설정
messages = [
{
"role": "system",
"content": "당신은 유용한 AI 어시스턴트입니다. 응답은 간결하게 해주세요.",
},
]
context = LLMContext(messages)
context_aggregator = LLMContextAggregatorPair(context)
# 전송 구성
transport = DailyTransport(
room_url=os.getenv("DAILY_ROOM_URL"),
token=os.getenv("DAILY_TOKEN"),
params=DailyParams(
audio_in_enabled=True,
audio_out_enabled=True,
vad_analyzer=SileroVADAnalyzer(),
),
)
# 파이프라인 구축 및 실행
pipeline = Pipeline([
transport.input(),
stt,
context_aggregator.user(),
llm,
tts,
transport.output(),
context_aggregator.assistant(),
])
task = PipelineTask(pipeline, params=PipelineParams())
runner = PipelineRunner()
await runner.run(task)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
***
## 레거시 모델 (ssfm-v21)
레거시 ssfm-v21 모델을 사용해야 하는 경우:
```python theme={null}
from pipecat_typecast import (
TypecastTTSService,
TypecastInputParams,
PromptOptions,
)
params = TypecastInputParams(
prompt_options=PromptOptions(
emotion_preset="happy", # normal | happy | sad | angry
emotion_intensity=1.3,
),
)
tts = TypecastTTSService(
aiohttp_session=session,
api_key=os.getenv("TYPECAST_API_KEY"),
model="ssfm-v21",
params=params,
)
```
참고: ssfm-v21은 더 적은 감정 프리셋을 지원합니다 (`whisper`, `toneup`, `tonedown` 없음).
***
## 문제 해결
* `TYPECAST_API_KEY` 환경 변수가 설정되어 있는지 확인하세요
* [타입캐스트 API 콘솔](https://typecast.ai/developers/api/)에서 키를 확인하세요
* 키에 여분의 공백이 없는지 확인하세요
* 전송이 `audio_out_enabled=True`로 구성되어 있는지 확인하세요
* TTS 서비스가 파이프라인에 포함되어 있는지 확인하세요
* API 키에 충분한 크레딧이 있는지 확인하세요
* 권장 범위(0.85 - 1.15) 내에서 `audio_tempo`를 조절하세요
* 다른 `emotion_intensity` 값을 시도하세요
* 샘플 레이트가 전송 구성과 일치하는지 확인하세요
* `pipecat-typecast`가 아닌 `pipecat-ai-typecast`를 설치했는지 확인하세요
* Python 버전이 3.10 이상인지 확인하세요
* Pipecat 버전이 v0.0.94 이상인지 확인하세요
***
## 리소스
소스 코드 및 예제
pip로 설치
Pipecat에 대해 더 알아보기
사용 가능한 음성 둘러보기