인터랙티브 이야기
, 등장인물마다 다른 목소리로

Q: 이 템플릿의 단계별 가이드가 있나요?

네. 레시피 에서 코드를 따라가며 설명하고, README 에서 설정, 환경 변수, 배포를 다루며, TTS WebSocket context 문서 에서 Cartesia 쪽을 설명합니다.

테마와 분위기를 고르면 LLM이 세 장면짜리 이야기를 씁니다. Sonic 3.6이 등장인물마다 다른 목소리로 소리 내어 읽고, 읽는 단어가 하나씩 밝아집니다. 장면이 끝날 때마다 다음에 일어날 일을 탭하거나 말로 고릅니다.

GitHub에서 보기

Juniper and the Lost Signal의 첫 장면이 끝난 Story time 화면. 내레이터, 로봇 Bolt, Juniper가 각자 대사를 가지고 있고, 그 아래에 What happens next? 질문과 선택 버튼 두 개, Answer out loud 버튼이 있습니다

스크린샷. 로컬에서 실행 중인 템플릿입니다.

모델: sonic-3.6, ink-2
언어: 영어
라이선스: Apache-2.0
기술 스택: Next.js 16React 19AI SDKIndexedDBshadcn/ui
Cartesia 제품: Sonic 3.6Ink 2

하는 일

이야기는 짧은 장면 세 개로 이루어집니다. 고른 테마와 분위기에 맞춰 LLM이 장면을 쓰고, Sonic 3.6이 소리 내어 읽습니다. 내레이터와 각 등장인물은 저마다의 목소리로 말하고, 읽히는 단어마다 불이 들어옵니다.

장면이 끝나면 두 가지 선택지 중에서 다음 전개를 고릅니다. 하나를 탭하거나 소리 내어 말하면 됩니다. 콘텐츠 안전 기능은 기본으로 켜져 있고, 모든 장면은 재생 전에 검사됩니다.

직접 실행하기

1
설치
Node 22.22 이상에서 아래 명령어를 실행하세요. pnpm도 쓸 수 있습니다. 아래 표를 보고 .env.local을 채우세요. 빠진 키가 있으면 페이지가 무엇인지 알려 줍니다.
npx degit cartesia-ai/cookbook/examples/story-time story-time cd story-time # add CARTESIA_API_KEY, LLM_MODEL and the matching LLM key cp .env.example .env.local npm install npm run dev
환경 변수
CARTESIA_API_KEY
play.cartesia.ai/keys
LLM_MODEL
provider/model, 예를 들어 openai/gpt-5.4-mini
OPENAI_API_KEY
LLM_MODEL이 openai/로 시작할 때. 장면 moderation이 켜지므로 어떤 모델을 쓰든 권장
ANTHROPIC_API_KEY
LLM_MODEL이 anthropic/으로 시작할 때
AI_GATEWAY_API_KEY
그 밖의 제공업체
APP_PASSWORD
로컬에서는 선택 사항. Vercel에서는 필수이며, none으로 두면 앱이 공개됨
TRUST_PROXY
선택 사항. 자체 리버스 프록시 뒤에서는 1
이야기 시작
npm run dev가 출력한 URL을 여세요. 테마와 분위기를 고르고, 원하면 주인공 이름을 지은 뒤 Start the story를 누르세요. 장면이 끝나면 두 선택지 중 하나를 탭하거나 Answer out loud를 누르고 말하세요.

코딩 에이전트로 만들기

어디서 시작하고 무엇을 먼저 읽어야 하는지 코딩 에이전트에게 알려 주는 프롬프트입니다.

프롬프트

Claude Code Cursor Codex

Build an interactive story app with Cartesia. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/story-time and follow its AGENTS.md for the commands, files and rules. The AI SDK writes each scene. The browser gets a 60 second access token with the tts and stt grants, reads the scene with sonic-3.6 over the TTS WebSocket using one context per line (each with its own voice, emotion and add_timestamps), and hears the listener's choice with ink-2 on /stt/turns/websocket, opening the mic only when they press Answer out loud. Keep the content-safety rules in AGENTS.md. If I don't have a Cartesia API key yet, follow https://www.cartesia.ai/agent-quickstart.md to get one.

작동 방식

장면LLM이 화자와 감정이 붙은 대사를 4~7줄 쓰고, 이어서 안전 검사를 합니다

Sonic 3.6장면마다 연결 하나, 대사마다 별도 스트림

따라 읽기단어 타임스탬프로 강조 표시

Ink 2말한 선택을 듣습니다. 마이크는 답하는 동안에만 켜집니다

선택브라우저에서 매칭. 고른 선택지만 다시 보냄

이렇게 만든 이유

화자마다 새 목소리

Sonic은 연결 하나에서 여러 스트림을 돌릴 수 있고, 스트림마다 목소리와 감정을 따로 정합니다. 그래서 내레이터, 주인공, 말하는 용이 다시 연결하지 않고 번갈아 말합니다. 새 등장인물은 목록에서 다음 목소리를 받습니다.

내 말은 브라우저에 남습니다

Ink 2가 답을 텍스트로 바꾸고, 페이지는 브라우저 안에서 그 답을 선택지와 맞춰 봅니다. LLM에는 고른 선택지만 돌아가고, 내가 한 말은 가지 않습니다. 마이크는 Answer out loud를 누를 때만 열립니다.

다시 듣기에는 API 호출이 없습니다

각 장면은 오디오와 단어 타이밍과 함께 브라우저의 IndexedDB에 저장됩니다. 라이브러리에서 이야기를 다시 들으면 하이라이트와 함께 재생되고, 아무것도 호출하지 않습니다.

원하는 대로 바꾸기

다른 음성 사용

음성 id는 lib/story.ts에 있습니다. play.cartesia.ai/voices의 음성으로 바꾸세요.

더 긴 이야기 만들기

lib/story.ts의 TOTAL_SCENES를 기본값 3보다 크게 하세요. 장면이 하나 늘 때마다 LLM 호출 한 번과 그 낭독 비용이 듭니다.

다른 언어로 이야기하기

Ink 2와 Sonic은 스페인어, 프랑스어, 힌디어, 일본어도 지원합니다. lib/narrate.ts에서 낭독 언어를 정하고 이야기 프롬프트에도 그 언어를 넣으세요. 말한 선택을 맞추는 데와 안전 검사에 쓰는 단어 목록을 번역하세요. 감정 설정은 영어에서만 동작하니 끄세요.

Cartesia로 전환하는 팀들과 함께하세요

1위

Artificial Analysis의 Speech Arena 및 Speech to Text 리더보드에서

자주 묻는 질문

이야기를 어떻게 안전하게 지키나요?

테마와 분위기는 정해진 선택지이고, 프롬프트는 잔인한 폭력, 성적인 내용, 혐오를 금지합니다. 모든 장면은 단어 목록으로도 검사하고, OpenAI 키를 추가하면 OpenAI의 모더레이션 서비스로도 검사합니다. 완벽한 필터는 없으니 공유하기 전에 이야기를 몇 편 읽어 보세요.

내 선택과 목소리는 어디로 가나요?

이야기 설정, 주인공 이름, 내 선택은 내가 고른 LLM 제공자에게 갑니다. OpenAI 키를 추가하면 설정과 각 장면이 모더레이션을 위해 OpenAI로도 갑니다. 말로 한 답은 Cartesia로 스트리밍되고, 앱 서버는 오디오도 이야기도 저장하지 않습니다.

Cartesia API 키가 브라우저에 노출되나요?

아니요. 키는 서버에만 있습니다. 브라우저는 60초 동안만 유효하고 음성에만 쓸 수 있는 토큰을 받습니다.

단어 하이라이트는 어떻게 동작하나요?

Sonic은 오디오와 함께 단어마다 시작 시각을 보냅니다. 페이지는 프레임마다 재생 시각을 확인하고 지금 읽는 단어를 밝힙니다.

첫 장면은 왜 몇 초 걸리나요?

낭독이 시작되기 전에 LLM이 장면 전체를 쓰기 때문입니다. 더 작은 모델을 쓰면 기다림이 짧아집니다. 그 뒤로는 앞 대사가 재생되는 동안 다음 대사를 만듭니다.

이 템플릿의 단계별 가이드가 있나요?

네. 레시피에서 코드를 따라가며 설명하고, README에서 설정, 환경 변수, 배포를 다루며, TTS WebSocket context 문서에서 Cartesia 쪽을 설명합니다.