메인 콘텐츠로 건너뛰기

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은 실시간 멀티모달 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

​
사전 요구 사항

시작하기 전에 다음을 준비하세요:
요구 사항버전
Python3.10+
Pipecatv0.0.94+
타입캐스트 API 키여기서 받기

​
설치

Pipecat용 Typecast TTS 서비스를 설치하세요: 
pip install pipecat-ai-typecast
uv를 사용하시나요? 대신 uv add 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(),  # 어시스턴트 응답 저장
    ])
환경 변수를 설정하세요:
  • TYPECAST_API_KEY — 타입캐스트 API 키 (필수)
  • TYPECAST_VOICE_ID — 사용할 음성 (선택 사항, 기본 음성으로 설정됨)

​
구성

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_intensity0.0 - 2.01.0 이상의 값은 표현력을 증가시킴
audio_pitch-12 ~ 12반음 조절
audio_tempo0.5 - 2.0권장: 0.85 - 1.15
volume0 - 200퍼센트로 표시되는 오디오 볼륨
seeduint32결정적 합성을 위한 부호 없는 정수 시드 (≥ 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 모델을 사용해야 하는 경우:
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 콘솔에서 키를 확인하세요
  • 키에 여분의 공백이 없는지 확인하세요
  • 전송이 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 이상인지 확인하세요

​
리소스

GitHub 저장소

소스 코드 및 예제

PyPI 패키지

pip로 설치

Pipecat 문서

Pipecat에 대해 더 알아보기

음성 라이브러리

사용 가능한 음성 둘러보기