## 핵심 콕집! - React 앱에서 **ElevenLabs의 TTS(텍스트 음성 변환)** API를 활용해 텍스트를 음성으로 자동 변환하고 재생할 수 있어요. - `useElevenLabs` 훅으로 API 호출 및 비동기 상태 관리를 간편하게 처리해요. - ElevenLabs의 **음성 클로닝** 기능으로 개인화된 음성을 앱에 바로 적용할 수 있어요. ## 핵심 개념 - ElevenLabs의 API를 React 앱에 연동해 텍스트를 자연스러운 음성으로 변환하고 재생하는 음성 UI를 만드는 방법이에요. ## 이럴 때 유용해요! - 사용자 알림, 기사 낭독, 챗봇 등에서 **음성 피드백이 필요할 때** - 텍스트를 직접 읽어주거나 음성 안내를 자동화할 수 있어요. - React 기반 웹 앱에 **간단히 음성 기능을 추가하고 싶을 때** - Vite 프로젝트에서 `useElevenLabs` 훅으로 빠르게 API를 호출해 적용 가능해요. - 서비스에 **사용자 맞춤 음성(클로닝) 기능을 도입할 때** - 사용자가 녹음한 음성 샘플로 커스텀 보이스를 만들어 개성 있는 UI를 구현할 수 있어요. ## 따라하기 1. Node.js와 Vite로 React 프로젝트 생성 - Node.js v16 이상 설치 - 아래 명령어로 Vite React 템플릿 생성 및 의존성 설치 ```bash npm create vite@latest elevenlabs-react-demo --template react cd elevenlabs-react-demo npm install ``` 2. 음성 재생용 라이브러리 설치 - 아래 명령어로 `howler`와 `eslint-plugin-react` 개발 의존 설치 ```bash npm install --save-dev eslint-plugin-react npm install howler ``` 3. API 키 환경 변수 설정 - 프로젝트 루트에 `.env` 파일 생성 후 ElevenLabs API 키 저장 ``` VITE_ELEVENLABS_API_KEY=your_api_key_here ``` - `.env` 파일은 깃에 커밋하지 마세요 4. ElevenLabs API 호출 유틸리티 작성 (`src/services/elevenlabs.js`) - 음성 생성 요청을 함수로 감싸 재사용 가능하게 만듭니다 ```js const API_KEY = import.meta.env.VITE_ELEVENLABS_API_KEY; const BASE_URL = "https://api.elevenlabs.io/v1"; export async function generateSpeech({ text, voiceId = "EXAVITQu4vr4xnSDxMaL", stability = 0.75, similarityBoost = 0.75, }) { const response = await fetch(`${BASE_URL}/text-to-speech/${voiceId}`, { method: "POST", headers: { "xi-api-key": API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ text, voice_settings: { stability, similarity_boost: similarityBoost }, }), }); if (!response.ok) { const err = await response.json(); throw new Error(err.error?.message ?? "ElevenLabs request failed"); } const { audio_url } = await response.json(); return audio_url; } ``` 5. React 훅으로 API 통신 및 상태 관리 (`src/hooks/useElevenLabs.js`) - 음성 생성 요청 및 로딩, 에러 상태를 관리합니다 ```js import { useState } from "react"; import { generateSpeech } from "../services/elevenlabs"; export function useElevenLabs() { const [loading, setLoading] = useState(false); const [audioUrl, setAudioUrl] = useState(null); const [error, setError] = useState(null); const speak = async ({ text, voiceId }) => { setLoading(true); setError(null); try { const url = await generateSpeech({ text, voiceId }); setAudioUrl(url); } catch (e) { setError(e.message); } finally { setLoading(false); } }; return { speak, loading, audioUrl, error }; } ``` 6. 음성 입력 및 재생 컴포넌트 구현 (`src/components/VoiceButton.jsx`) - 텍스트 입력 후 버튼 클릭하면 음성 재생 - `Howl`로 MP3 오디오 스트림 재생 ```jsx import { useState, useEffect } from "react"; import { useElevenLabs } from "../hooks/useElevenLabs"; import { Howl } from "howler"; export default function VoiceButton({ voiceId }) { const [text, setText] = useState(""); const { speak, loading, audioUrl, error } = useElevenLabs(); useEffect(() => { if (!audioUrl) return; const sound = new Howl({ src: [audioUrl], format: ["mp3"], html5: true }); sound.play(); return () => sound.unload(); }, [audioUrl]); const handleSubmit = (e) => { e.preventDefault(); if (!text.trim()) return; speak({ text, voiceId }); }; return (

setText(e.target.value)}
             style={{ width: "100%", padding: "0.5rem" }}
           />
           <button
             type="submit"
             disabled={loading}
             style={{
               marginTop: "0.5rem",
               padding: "0.5rem 1rem",
               background: "#0066ff",
               color: "#fff",
               border: "none",
               cursor: loading ? "wait" : "pointer",
             }}
           >
             {loading ? "Speaking…" : "Speak"}
           </button>
         </form>
         {error && <p style={{ color: "red" }}>{error}</p>}
       </div>
     );
   }
   ```
7. 앱에 컴포넌트 적용  
   - `<VoiceButton />`를 원하는 위치에 추가  
   - 커스텀 음성클론이 있을 경우 `voiceId` 속성에 복사한 음성 ID 전달  
   ```jsx
   <VoiceButton voiceId="my_custom_voice_id" />
   ```
8. 개발 서버 실행 및 확인  
   - 다음 명령어 실행  
     ```bash
     npm run dev
     ```
   - `http://localhost:5173` 접속 후, 텍스트 입력 -> `Speak` 버튼 클릭 시 음성 출력 확인

## 주의할 점
- API 키 노출 위험  
  - 개발 중 API 키가 클라이언트에 노출될 수 있으므로 `.env` 파일을 꼭 `.gitignore`에 추가해야 해요.  
  - 운영 환경에서는 API 호출을 서버(예: Vercel, Cloudflare Workers)에서 프록시 처리하는 것을 권장해요.  
- 모바일에서 자동재생 제한  
  - iOS Safari 등 자동 재생 제한이 있으니 재생은 반드시 버튼 클릭(사용자 인터랙션) 후 실행해야 해요.  
- 무료 플랜 요청 제한  
  - 분당 요청 수 제한에 걸릴 수 있으니 빠른 연속 요청은 `debounce` 처리하거나 생성된 음성 URL을 캐싱하세요.  
- 음성 클론 처리 시간  
  - 클론 생성 시 처리 시간이 걸리며, ElevenLabs 음성 상태가 `is_ready`가 되어야 사용 가능해요. 상태는 `/v1/voices` 엔드포인트에서 확인하세요.

## 참고 링크  
- ElevenLabs API 무료 키 신청: [https://try.elevenlabs.io/kr07zfuqn1bp](https://try.elevenlabs.io/kr07zfuqn1bp)</article></body></html>

React과 ElevenLabs로 음성 UI 만들기

요약

상세 내용