EPUB을
오디오북으로

EPUB 전자책을 장마다 MP3 하나로 바꿉니다. 명령줄에서도, 로컬 웹 페이지에서도 할 수 있습니다. 목소리 하나가 책을 내레이션하고, 따옴표 안에서 말하는 인물마다 다른 목소리가 붙습니다. 장마다 단어별 타이밍과 자막도 함께 만들어지므로, 들으면서 본문을 따라 읽을 수 있습니다.
alice_sample.epub을 미리 보기로 실행한 뒤의 Audiobook 웹 앱. Preview only가 체크되어 있고, 배역 모드는 Per speaker, 내레이터는 Archie, 언어는 영어이며, 로그에는 약 15065 Cartesia 크레딧, Alice = Maya와 Mouse = Leo 음성 배정, 두 챕터 처리 완료가 표시되어 있습니다

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

모델
sonic-3.6
언어
기본값은 영어, --language로 다른 언어
라이선스
MIT
기술 스택
PythonGradioEbookLibffmpeguv
Cartesia 제품
Sonic 3.6

하는 일

명령줄 도구와 웹 앱은 같은 변환을 실행합니다. 이 프로젝트는 p0n1의 오픈 소스 epub_to_audiobook을 포크한 것입니다.

함께 들어 있는 따라 읽기 페이지가 재생에 맞춰 단어를 하나씩 강조하고, 단어를 클릭하면 그 위치로 이동합니다. 자막 파일은 대부분의 플레이어에서 쓸 수 있습니다.

직접 실행하기

  1. 키 없이 미리 보기

    아래 명령어를 실행합니다. Python 3.10~3.12와 함께 uv와 ffmpeg가 설치되어 있어야 합니다. --preview 실행은 오디오를 만들지 않고 키도 필요 없습니다. 샘플 책을 장으로 나누고, 15,065자(약 15,000크레딧)를 세고, 인물마다 고른 목소리를 적은 out/cast.json을 씁니다.

    npx degit cartesia-ai/cookbook/examples/audiobook audiobook
    cd audiobook
    uv sync
    uv run python main.py samples/alice_sample.epub out --preview --no_prompt
    

    환경 변수
    CARTESIA_API_KEY
    play.cartesia.ai/keys. --preview에는 필요 없음
  2. 오디오 만들기

    .env.example을 새 .env 파일로 복사합니다. 거기에 CARTESIA_API_KEY를 추가합니다. set -a; . ./.env; set +a로 셸에 불러옵니다. 그다음 --preview를 빼고 같은 명령어를 실행합니다. 스크립트에서는 -y를 붙이면 비용 확인을 건너뜁니다.

  3. 웹 앱 사용

    uv run python main_ui.py를 실행합니다. 그다음 http://127.0.0.1:7860을 엽니다. 그 셸에 CARTESIA_API_KEY가 설정되어 있어야 합니다. 기본값인 로컬 호스트를 그대로 두세요. 앱에는 로그인이 없어서, 접속할 수 있는 사람은 누구나 내 크레딧을 씁니다.

  4. 따라 읽기

    프로젝트의 readalong.html을 브라우저에서 엽니다. 장의 MP3를 고른 다음, 그 옆의 .timings.json 파일을 고릅니다. 재생에 맞춰 지금 단어에 불이 들어옵니다.

코딩 에이전트로 만들기

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

프롬프트

Claude CodeCursorCodex

Convert an EPUB into an audiobook with Cartesia. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/audiobook and follow its AGENTS.md for the commands, files and rules. It uses the cartesia Python SDK to stream sonic-3.6 from /tts/sse with add_timestamps and use_normalized_timestamps=False, joins the raw PCM with ffmpeg into one MP3 per chapter, and writes .timings.json and .vtt files for read-along. Run a --preview first, which needs no key, to check the character count and out/cast.json. If I don't have a Cartesia API key yet, follow https://www.cartesia.ai/agent-quickstart.md to get one.

작동 방식

EPUB챕터와 문단으로 나눔
배역각 인용문의 화자를 찾아 음성을 배정
Sonic 3.6단어 타임스탬프와 함께 /tts/sse 스트리밍, 요청당 최대 1,500자
ffmpegPCM을 이어 붙이고 ID3 태그를 넣어 MP3로 인코딩
따라 읽기챕터마다 .timings.json과 .vtt 파일

이렇게 만든 이유

단어별 타이밍은 스트리밍에서 나온다

Cartesia의 일반 음성 합성 엔드포인트는 오디오만 돌려줍니다. 따라 읽기 파일에는 단어마다 시각이 필요하고, 이를 돌려주는 것은 스트리밍 엔드포인트뿐입니다. 앱은 use_normalized_timestamps=False도 설정해 $5 같은 단어를 쓰인 그대로 두므로, 강조 표시가 책의 문장과 맞습니다.

음성은 챕터 변환 전에 정해집니다

배역은 변환을 시작하기 전에 한 번만 정하므로, 병렬 작업이나 다시 실행해도 어느 인물을 어느 목소리가 읽는지가 바뀌지 않습니다. said Alice 같은 화자 표시가 없는 대사는 마지막에 말한 인물에게 가고, 두 인물이 이어지는 문단에서 대사를 주고받을 때는 다른 쪽 인물에게 갑니다.

대화 단서가 감정을 정합니다

영어 대화에서 대사 옆에 whispered, shouted, sobbed 같은 단어가 있으면 Sonic은 그 대사를 차분하게, 화난 듯이, 슬프게 읽습니다. laughed가 있으면 대사 앞에 웃음소리가 들어갑니다.

원하는 대로 바꾸기

음성 고르기

out/cast.json을 고치고 다시 실행합니다. 배역을 다시 쓰려면 --cast_file로 내 파일을 넘깁니다. 값은 Archie 같은 기본 제공 목소리 이름입니다. play.cartesia.ai/voices의 아무 음성 ID도 쓸 수 있습니다.

음성 하나만 사용

--cast_mode narrator로 실행하면 대화까지 포함해 책 전체를 목소리 하나로 읽습니다. 그 목소리는 --voice_name으로 고릅니다.

다른 언어 변환

--language fr처럼 Sonic 언어 코드를 넘깁니다. 인물마다 목소리가 붙는 것은 그대로입니다. 감정과 웃음 표시는 영어에서만 작동합니다.

자주 묻는 질문

책 한 권을 변환하는 데 비용이 얼마나 드나요?

Sonic은 한 글자당 약 1크레딧을 청구하며, 문단 사이의 쉼은 로컬에서 무료로 추가됩니다. 먼저 --preview로 실행해 글자 수를 확인하세요. 크레딧 가격은 요금제에 따라 다르므로 도구는 달러 금액을 출력하지 않습니다.

인물마다 맞는 목소리가 붙나요?

said Alice처럼 화자를 표시하는 책이라면 대부분 맞습니다. 암시만 된 화자는 놓치고, 표시 없이 두 사람이 주고받는 대사는 뒤바뀔 수 있습니다. 미리보기 뒤에 배역 파일을 확인해 고치거나, 책 전체를 목소리 하나로 읽으세요.

Audiobookshelf 같은 오디오북 앱에서 들을 수 있나요?

네. MP3마다 제목, 저자, 앨범, 트랙 태그가 붙어 있어서 Audiobookshelf 같은 서버가 장들을 책 한 권으로 묶습니다.

아무 책이나 변환해도 되나요?

직접 소유했거나 권리를 가진 책만 변환하고, 공개하는 결과물에는 AI 생성 오디오임을 표시하세요. 템플릿에는 테스트용으로 퍼블릭 도메인인 이상한 나라의 앨리스 두 챕터가 들어 있습니다.

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

네. 레시피에서 코드를 단계별로 살펴보고, README에서 설정, 환경 변수, 배포를 다루며, TTS 서버 전송 이벤트(SSE) 레퍼런스에서 Cartesia 쪽 동작을 설명합니다.

오늘 시작하세요

전문가와 상담하세요.

팀원과 연결해 Cartesia가 세계적 수준의 음성 경험을 만드는 데 어떻게 도움이 되는지 알아보세요.

영업팀 문의

개발을 시작하세요.

API로 모델을 사용하고 몇 분 만에 음성 에이전트를 프로덕션에 배포하세요.

Cartesia 사용해 보기