Pipecat - Typecast Documentation

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 키	여기서 받기

설치

Pipecat용 Typecast TTS 서비스를 설치하세요:

pip install pipecat-ai-typecast

빠른 시작

Pipecat 파이프라인에 Typecast TTS를 통합하는 최소 예제입니다:

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(),  # 어시스턴트 응답 저장
    ])

구성

TypecastTTSService는 프리셋 기반 및 문맥 인식 감정 제어를 모두 지원합니다.

기본 구성

from pipecat_typecast import TypecastTTSService

tts = TypecastTTSService(
    aiohttp_session=session,
    api_key=os.getenv("TYPECAST_API_KEY"),
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model="ssfm-v30",  # 최신 모델 (기본값)
)

이모션 프리셋 제어

일관된 음성 스타일링을 위해 미리 정의된 감정 중에서 선택하세요:

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가 주변 텍스트에서 감정을 자동으로 추론하도록 합니다:

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는 WebRTC 기반 비디오 및 오디오 인프라를 제공합니다.

from pipecat.transports.daily.transport import DailyParams

transport_params = DailyParams(
    audio_in_enabled=True,
    audio_out_enabled=True,
    vad_analyzer=SileroVADAnalyzer(),
)

전체 예제

음성 AI 에이전트를 생성하는 완전한 작동 예제입니다:

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 사용

레거시 ssfm-v21 모델을 사용해야 하는 경우:

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 없음).