ElevenLabs 텍스트-음성

ElevenLabs 텍스트-음성 (TTS)

ElevenLabs는 딥러닝 기반의 자연스러운 음성 합성 소프트웨어를 제공해요. ElevenLabs의 AI 오디오 모델은 32개 언어에 걸쳐 현실적이고 다재다능하며 상황에 맞는 음성, 목소리, 음향 효과를 생성해요. 이 글에서는 ElevenLabs TTS를 Spring AI에서 사용하기 위한 의존성 추가, 자동 설정, 음성 옵션, 실시간 스트리밍까지 차근차근 다뤄볼게요.

출처: 문서

본문

Introduction

ElevenLabs는 딥러닝을 사용하는 자연스러운 음성 합성 소프트웨어를 제공해요. 이 AI 오디오 모델은 32개 언어에 걸쳐 현실적이고, 다재다능하며, 상황을 인지하는 음성(speech), 목소리(voices), 그리고 음향 효과(sound effects)를 생성해요. ElevenLabs Text-to-Speech API를 사용하면 어떤 책, 기사, PDF, 뉴스레터 또는 텍스트라도 초현실적인 AI 내레이션으로 생생하게 만들 수 있어요.

Prerequisites

ElevenLabs 계정을 만들고 API 키를 받으세요. ElevenLabs signup page에서 가입할 수 있어요. 로그인 후 프로필 페이지에서 API 키를 찾을 수 있어요.
프로젝트의 빌드 파일에 spring-ai-elevenlabs 의존성을 추가하세요. 자세한 내용은 Dependency Management 섹션을 참고해주세요.

Auto-configuration

Spring AI는 ElevenLabs Text-to-Speech 클라이언트에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 프로젝트의 Maven pom.xml 파일에 다음 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-elevenlabs</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-elevenlabs'
}

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

Speech Properties

Connection Properties

프리픽스 spring.ai.elevenlabs는 모든 ElevenLabs 관련 설정(연결 및 TTS 특정 설정 모두)의 프로퍼티 프리픽스로 사용돼요. 이는 ElevenLabsConnectionProperties에 정의돼 있어요.

Property	Description	Default
spring.ai.elevenlabs.base-url	ElevenLabs API의 베이스 URL.	api.elevenlabs.io
spring.ai.elevenlabs.api-key	ElevenLabs API 키.	-

Configuration Properties

__ 오디오 음성 자동 설정의 활성화/비활성화는 이제 프리픽스 spring.ai.model.audio.speech가 붙은 최상위 프로퍼티로 설정해요. 활성화하려면 spring.ai.model.audio.speech=elevenlabs (기본값으로 활성화됨). 비활성화하려면 spring.ai.model.audio.speech=none (또는 elevenlabs와 일치하지 않는 어떤 값). 이 변경은 여러 모델의 설정을 허용하기 위한 것이에요.

프리픽스 spring.ai.elevenlabs.tts는 ElevenLabs Text-to-Speech 클라이언트를 특히 구성하기 위한 프로퍼티 프리픽스로 사용돼요. 이는 ElevenLabsSpeechProperties에 정의돼 있어요.

Property	Description	Default
spring.ai.model.audio.speech	Audio Speech Model 활성화	elevenlabs
spring.ai.elevenlabs.tts.model-id	사용할 모델의 ID.	eleven_turbo_v2_5
spring.ai.elevenlabs.tts.voice-id	사용할 음성의 ID. voice ID이지 음성 이름이 아니에요.	9BWtsMINqrJLrRacOk9x
spring.ai.elevenlabs.tts.output-format	생성된 오디오의 출력 형식. 아래 Output Formats 참고.	mp3_22050_32

__ 베이스 URL과 API 키는 spring.ai.elevenlabs.tts.base-url과 spring.ai.elevenlabs.tts.api-key를 사용해 TTS에 특별히 구성할 수도 있어요. 하지만 서로 다른 ElevenLabs 서비스에 서로 다른 자격 증명을 쓸 특별한 이유가 없다면, 단순함을 위해 전역 spring.ai.elevenlabs 프리픽스를 사용하는 것을 일반적으로 권장해요. 더 구체적인 tts 프로퍼티가 전역 프로퍼티를 덮어씁니다.

__	`spring.ai.elevenlabs.tts` 프리픽스가 붙은 모든 프로퍼티는 런타임에 재정의할 수 있어요.

Table 1. 사용 가능한 Output Formats Enum 값	Description
MP3_22050_32	MP3, 22.05 kHz, 32 kbps
MP3_44100_32	MP3, 44.1 kHz, 32 kbps
MP3_44100_64	MP3, 44.1 kHz, 64 kbps
MP3_44100_96	MP3, 44.1 kHz, 96 kbps
MP3_44100_128	MP3, 44.1 kHz, 128 kbps
MP3_44100_192	MP3, 44.1 kHz, 192 kbps
PCM_8000	PCM, 8 kHz
PCM_16000	PCM, 16 kHz
PCM_22050	PCM, 22.05 kHz
PCM_24000	PCM, 24 kHz
PCM_44100	PCM, 44.1 kHz
PCM_48000	PCM, 48 kHz
ULAW_8000	µ-law, 8 kHz
ALAW_8000	A-law, 8 kHz
OPUS_48000_32	Opus, 48 kHz, 32 kbps
OPUS_48000_64	Opus, 48 kHz, 64 kbps
OPUS_48000_96	Opus, 48 kHz, 96 kbps
OPUS_48000_128	Opus, 48 kHz, 128 kbps
OPUS_48000_192	Opus, 48 kHz, 192 kbps

Runtime Options

ElevenLabsTextToSpeechOptions 클래스는 텍스트-음성 요청을 할 때 사용할 옵션을 제공해요. 시작 시 spring.ai.elevenlabs.tts로 지정한 옵션이 사용되지만, 런타임에 이를 재정의할 수 있어요. 다음 옵션을 사용할 수 있어요:

modelId: 사용할 모델의 ID.
voiceId: 사용할 음성의 ID.
outputFormat: 생성된 오디오의 출력 형식.
voiceSettings: stability, similarityBoost, style, useSpeakerBoost, speed 같은 음성 설정을 담은 객체.
enableLogging: 로깅 활성화/비활성화를 위한 부울 값.
languageCode: 입력 텍스트의 언어 코드 (예: 영어는 "en").
pronunciationDictionaryLocators: 발음 사전 위치 지정자(locator) 목록.
seed: 재현 가능성을 위한 난수 생성 시드.
previousText: 멀티 턴 대화에서 맥락을 위한 본문 이전 텍스트.
nextText: 멀티 턴 대화에서 맥락을 위한 본문 이후 텍스트.
previousRequestIds: 대화에서 이전 턴의 요청 ID.
nextRequestIds: 대화에서 이후 턴의 요청 ID.
applyTextNormalization: 텍스트 정규화 적용 ("auto", "on", "off").
applyLanguageTextNormalization: 언어 텍스트 정규화 적용.

예:

ElevenLabsTextToSpeechOptions speechOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_multilingual_v2")
    .voiceId("your_voice_id")
    .outputFormat(ElevenLabsApi.OutputFormat.MP3_44100_128.getValue())
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

Using Voice Settings

옵션에 VoiceSettings를 제공해 음성 출력을 커스터마이즈할 수 있어요. 이를 통해 stability나 similarity 같은 속성을 제어할 수 있어요.

var voiceSettings = new ElevenLabsApi.SpeechRequest.VoiceSettings(0.75f, 0.75f, 0.0f, true);

ElevenLabsTextToSpeechOptions speechOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_multilingual_v2")
    .voiceId("your_voice_id")
    .voiceSettings(voiceSettings)
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("This is a test with custom voice settings!", speechOptions);
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

Manual Configuration

프로젝트의 Maven pom.xml 파일에 spring-ai-elevenlabs 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-elevenlabs</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-elevenlabs'
}

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

다음으로 ElevenLabsTextToSpeechModel을 만들어볼게요:

ElevenLabsApi elevenLabsApi = ElevenLabsApi.builder()
		.apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
		.build();

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.options(ElevenLabsTextToSpeechOptions.builder()
		.model("eleven_turbo_v2_5")
		.voiceId("your_voice_id") // e.g. "9BWtsMINqrJLrRacOk9x"
		.outputFormat("mp3_44100_128")
		.build())
	.build();

// The call will use the default options configured above.
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.");
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

byte[] responseAsBytes = response.getResult().getOutput();

Streaming Real-time Audio

ElevenLabs Speech API는 chunk transfer encoding을 사용한 실시간 오디오 스트리밍을 지원해요. 덕분에 전체 오디오 파일이 생성되기 전에 오디오 재생을 시작할 수 있어요.

ElevenLabsApi elevenLabsApi = ElevenLabsApi.builder()
		.apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
		.build();

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.build();

ElevenLabsTextToSpeechOptions streamingOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_turbo_v2_5")
    .voiceId("your_voice_id")
    .outputFormat("mp3_44100_128")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Today is a wonderful day to build something people love!", streamingOptions);

Flux<TextToSpeechResponse> responseStream = elevenLabsTextToSpeechModel.stream(speechPrompt);

// Process the stream, e.g., play the audio chunks
responseStream.subscribe(speechResponse -> {
    byte[] audioChunk = speechResponse.getResult().getOutput();
    // Play the audioChunk
});

Voices API

ElevenLabs Voices API를 사용하면 사용 가능한 음성, 그 설정, 그리고 기본 음성 설정에 대한 정보를 검색할 수 있어요. 이 API로 음성 요청에서 사용할 voiceId를 찾을 수 있어요.

Voices API를 사용하려면 ElevenLabsVoicesApi 인스턴스를 만들어야 해요:

ElevenLabsVoicesApi voicesApi = ElevenLabsVoicesApi.builder()
        .apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
        .build();

그런 다음 다음 메서드를 사용할 수 있어요:

getVoices(): 사용 가능한 모든 음성 목록을 검색해요.
getDefaultVoiceSettings(): 음성의 기본 설정을 가져와요.
getVoiceSettings(String voiceId): 특정 음성의 설정을 반환해요.
getVoice(String voiceId): 특정 음성의 메타데이터를 반환해요.

예:

// Get all voices
ResponseEntity<ElevenLabsVoicesApi.Voices> voicesResponse = voicesApi.getVoices();
List<ElevenLabsVoicesApi.Voice> voices = voicesResponse.getBody().voices();

// Get default voice settings
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> defaultSettingsResponse = voicesApi.getDefaultVoiceSettings();
ElevenLabsVoicesApi.VoiceSettings defaultSettings = defaultSettingsResponse.getBody();

// Get settings for a specific voice
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> voiceSettingsResponse = voicesApi.getVoiceSettings(voiceId);
ElevenLabsVoicesApi.VoiceSettings voiceSettings = voiceSettingsResponse.getBody();

// Get details for a specific voice
ResponseEntity<ElevenLabsVoicesApi.Voice> voiceDetailsResponse = voicesApi.getVoice(voiceId);
ElevenLabsVoicesApi.Voice voiceDetails = voiceDetailsResponse.getBody();

Example Code

ElevenLabsTextToSpeechModelIT.java 테스트는 라이브러리 사용법에 대한 일반적인 예제를 제공해요.
ElevenLabsApiIT.java 테스트는 저수준 ElevenLabsApi 사용 예제를 제공해요.

ElevenLabs 텍스트-음성