텍스트 음성 변환 스트리밍 | ElevenLabs Documentation

이 가이드에서는 파일로 음성을 생성하는 방법, 오디오 응답을 직접 스트리밍하는 방법, 그리고 선택적으로 생성된 오디오를 AWS S3 버킷에 업로드하여 서명된 URL로 공유하는 방법까지 세 가지 방식을 다룹니다.

이 가이드는 API 키와 SDK를 설정했다고 가정합니다. 아직 완료하지 않았다면 먼저 빠른 시작 가이드를 완료하세요. 선택 사항인 S3 업로드 섹션을 사용하려면 S3에 액세스할 수 있는 AWS 계정도 필요합니다.

스트리밍이 왜 이런 방식으로 작동하는지 궁금하신가요? 오디오 스트리밍 이해하기에서 프로토콜, 버퍼링, 지연 시간 간의 트레이드오프를 자세히 설명합니다.

텍스트를 음성으로 변환(파일)

텍스트를 음성으로 변환해 파일로 저장하려면 ElevenLabs SDK의 convert 메서드를 사용한 다음, 이를 로컬에 .mp3 파일로 저장합니다.

import os
import uuid
from dotenv import load_dotenv
from elevenlabs import VoiceSettings
from elevenlabs.client import ElevenLabs
load_dotenv()
ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(
    api_key=ELEVENLABS_API_KEY,
)
def text_to_speech_file(text: str) -> str:
    # Calling the text_to_speech conversion API with detailed parameters
    response = elevenlabs.text_to_speech.convert(
        voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
        output_format="mp3_22050_32",
        text=text,
        model_id="eleven_flash_v2_5", # use the flash model for low latency
        # Optional voice settings that allow you to customize the output
        voice_settings=VoiceSettings(
            stability=0.0,
            similarity_boost=1.0,
            style=0.0,
            use_speaker_boost=True,
            speed=1.0,
        ),
    )
    # uncomment the line below to play the audio back
    # play(response)
    # Generating a unique file name for the output MP3 file
    save_file_path = f"{uuid.uuid4()}.mp3"
    # Writing the audio to a file
    with open(save_file_path, "wb") as f:
        for chunk in response:
            if chunk:
                f.write(chunk)
    print(f"{save_file_path}: A new audio file was saved successfully!")
    # Return the path of the saved audio file
    return save_file_path

다음과 같이 이 함수를 실행할 수 있습니다.

text_to_speech_file("Hello World")

텍스트를 음성으로 변환(스트리밍)

파일로 저장하지 않고 오디오를 직접 스트리밍하려면 스트리밍 기능을 사용할 수 있습니다.

import os
from typing import IO
from io import BytesIO
from dotenv import load_dotenv
from elevenlabs import VoiceSettings
from elevenlabs.client import ElevenLabs
load_dotenv()
ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(
    api_key=ELEVENLABS_API_KEY,
)
def text_to_speech_stream(text: str) -> IO[bytes]:
    # Perform the text-to-speech conversion
    response = elevenlabs.text_to_speech.stream(
        voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
        output_format="mp3_22050_32",
        text=text,
        model_id="eleven_multilingual_v2",
        # Optional voice settings that allow you to customize the output
        voice_settings=VoiceSettings(
            stability=0.0,
            similarity_boost=1.0,
            style=0.0,
            use_speaker_boost=True,
            speed=1.0,
        ),
    )
    # Create a BytesIO object to hold the audio data in memory
    audio_stream = BytesIO()
    # Write each chunk of audio data to the stream
    for chunk in response:
        if chunk:
            audio_stream.write(chunk)
    # Reset stream position to the beginning
    audio_stream.seek(0)
    # Return the stream for further use
    return audio_stream

다음과 같이 이 함수를 실행할 수 있습니다.

text_to_speech_stream("This is James")

추가 - AWS S3에 업로드하고 안전한 공유 링크 받기

오디오 데이터가 파일 또는 스트림으로 생성되면 사용자와 공유하고 싶을 수 있습니다. 이를 위한 한 가지 방법은 AWS S3 버킷에 업로드하고 안전한 공유 링크를 생성하는 것입니다.

AWS 자격 증명 생성

데이터를 S3에 업로드하려면 AWS 액세스 키 ID, 보안 액세스 키 및 AWS 리전 이름을 .env 파일에 추가해야 합니다. 다음 단계에 따라 자격 증명을 찾으세요.

AWS Management Console에 로그인합니다. AWS 홈 페이지로 이동하여 계정으로 로그인하세요.

IAM(Identity and Access Management) 대시보드에 액세스합니다. 서비스 메뉴의 “Security, Identity, & Compliance”에서 IAM을 찾을 수 있습니다. IAM 대시보드에서는 AWS 서비스에 대한 액세스를 안전하게 관리합니다.

새 사용자를 생성합니다(필요한 경우). IAM 대시보드에서 “Users”를 선택한 후 “Add user”를 선택하세요. 사용자 이름을 입력합니다.

권한을 설정합니다. 부여하려는 액세스 수준에 따라 정책을 사용자에게 직접 연결하세요. S3 업로드에는 AmazonS3FullAccess 정책을 사용할 수 있습니다. 하지만 최소 권한 원칙에 따라 작업 수행에 필요한 최소한의 권한만 부여하는 것이 좋습니다. S3 버킷에서 필요한 작업만 특별히 허용하는 사용자 지정 정책을 만들 수 있습니다.

사용자를 검토하고 생성합니다. 설정을 검토한 후 사용자를 생성하세요. 생성 후 액세스 키 ID와 보안 액세스 키가 표시됩니다. 이 자격 증명은 반드시 다운로드하여 안전하게 보관하세요. 이 단계 이후에는 보안 액세스 키를 다시 조회할 수 없습니다.

AWS 리전 이름을 확인합니다. 예: us-east-1

AWS S3 버킷이 없다면 다음 단계에 따라 새 버킷을 만들어야 합니다.

S3 대시보드에 액세스합니다. 서비스 메뉴의 “Storage”에서 S3를 찾을 수 있습니다.

새 버킷을 생성합니다. S3 대시보드에서 “Create bucket” 버튼을 클릭하세요.

버킷 이름을 입력하고 “Create bucket” 버튼을 클릭합니다. 다른 버킷 옵션은 기본값으로 그대로 둘 수 있습니다. 새로 추가한 버킷이 목록에 표시됩니다.

AWS SDK 설치 및 자격 증명 추가

pip 및 npm을 사용하여 AWS 서비스와 상호작용할 수 있도록 boto3를 설치합니다.

pip install boto3

그런 다음 다음과 같이 환경 변수를 .env 파일에 추가합니다.

AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
AWS_REGION_NAME=your_aws_region_name_here
AWS_S3_BUCKET_NAME=your_s3_bucket_name_here

AWS S3 업로드 및 서명된 URL 생성

다음 함수를 추가하여 오디오 스트림을 S3에 업로드하고 서명된 URL을 생성합니다.

import os
import boto3
import uuid
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION_NAME = os.getenv("AWS_REGION_NAME")
AWS_S3_BUCKET_NAME = os.getenv("AWS_S3_BUCKET_NAME")
session = boto3.Session(
    aws_access_key_id=AWS_ACCESS_KEY_ID,
    aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
    region_name=AWS_REGION_NAME,
)
s3 = session.client("s3")
def generate_presigned_url(s3_file_name: str) -> str:
    signed_url = s3.generate_presigned_url(
        "get_object",
        Params={"Bucket": AWS_S3_BUCKET_NAME, "Key": s3_file_name},
        ExpiresIn=3600,
    )  # URL expires in 1 hour
    return signed_url
def upload_audiostream_to_s3(audio_stream) -> str:
    s3_file_name = f"{uuid.uuid4()}.mp3"  # Generates a unique file name using UUID
    s3.upload_fileobj(audio_stream, AWS_S3_BUCKET_NAME, s3_file_name)
    return s3_file_name

그런 다음 텍스트에서 생성한 오디오 스트림으로 업로드 함수를 호출할 수 있습니다.

s3_file_name = upload_audiostream_to_s3(audio_stream)

오디오 파일을 S3에 업로드한 후, 파일 액세스를 공유할 서명된 URL을 생성합니다. 이 URL은 시간 제한이 있어 일정 시간이 지나면 만료되므로 임시 공유에 안전합니다.

이제 다음과 같이 파일에서 URL을 생성할 수 있습니다.

signed_url = generate_presigned_url(s3_file_name)
print(f"Signed URL to access the file: {signed_url}")

파일을 여러 번 사용하려면 만료되는 서명된 URL을 직접 저장하지 말고, S3 파일 경로를 데이터베이스에 저장한 다음 필요할 때마다 서명된 URL을 다시 생성해야 합니다.

모든 단계 통합

모든 단계를 통합하려면 다음 스크립트를 사용할 수 있습니다.

import os
from dotenv import load_dotenv
load_dotenv()
from text_to_speech_stream import text_to_speech_stream
from s3_uploader import upload_audiostream_to_s3, generate_presigned_url
def main():
    text = "This is James"
    audio_stream = text_to_speech_stream(text)
    s3_file_name = upload_audiostream_to_s3(audio_stream)
    signed_url = generate_presigned_url(s3_file_name)
    print(f"Signed URL to access the file: {signed_url}")
if __name__ == "__main__":
    main()

결론

이제 텍스트를 음성으로 변환하고 오디오 파일을 공유할 서명된 URL을 생성하는 방법을 알게 되었습니다. 이 기능으로 동적으로 콘텐츠를 만들고 공유할 수 있는 다양한 기회가 열립니다.

이를 활용해 만들 수 있는 몇 가지 예시는 다음과 같습니다.

교육용 팟캐스트: 학생이 필요할 때 이용할 수 있는 맞춤형 교육 콘텐츠를 만듭니다. 교사는 수업을 오디오 형식으로 변환해 S3에 업로드하고, 학생과 링크를 공유하여 기존 교실 환경 밖에서도 더욱 흥미로운 학습 경험을 제공할 수 있습니다.
웹사이트 접근성 기능: 텍스트 콘텐츠를 오디오 형식으로 제공하여 웹사이트 접근성을 높입니다. 이를 통해 시각 장애가 있거나 청각적 학습을 선호하는 사람이 웹사이트의 정보에 더 쉽게 접근할 수 있습니다.
자동화된 고객 지원 메시지: FAQ 또는 주문 상태 업데이트와 같은 자동화된 맞춤형 고객 지원 오디오 메시지를 제작합니다. 기존의 텍스트 이메일보다 더 몰입도 높은 고객 경험을 제공할 수 있습니다.
오디오북 및 내레이션: 책 전체나 단편 소설을 오디오 형식으로 변환하여 독자가 문학을 즐길 새로운 방식을 제공합니다. 저자와 출판사는 콘텐츠 제공 범위를 넓히고 읽기보다 듣기를 선호하는 독자에게 다가갈 수 있습니다.
언어 학습 도구: 학습자에게 오디오 수업과 연습 문제를 제공하는 언어 학습 도구를 개발합니다. 발음과 듣기 능력을 목표에 맞춰 연습할 수 있습니다.

다음 단계

WebSocket 스트리밍

LLM이 생성하는 대로 WebSocket을 사용해 텍스트 음성을 실시간으로 스트리밍합니다.

지연 시간 이해

지연 시간에 영향을 주는 요소와 첫 오디오까지의 시간을 최소화하는 방법을 알아보세요.