docs: [plans] 사운드 로고 생성기 기획서 고도화

- 모드 C를 Lyria RealTime(WebSocket, 브라우저 직접) + Lyria 2(REST, 폴백) 듀얼 구조로 개편 - 별도 API 키 발급 불필요 확인 (기존 Gemini API 키 + Vertex AI 서비스 계정 재활용) - API 인증 현황, Lyria RealTime/Lyria 2 사양, 공식 문서 참조 추가
2026-03-08 12:09:51 +09:00
parent 7c9f7afb52
commit 4d13301ce0
1 changed files with 135 additions and 24 deletions
--- a/sam/docs/plans/sound-logo-generator-plan.md
+++ b/sam/docs/plans/sound-logo-generator-plan.md
@@ -143,30 +143,56 @@

 > Google Lyria AI가 프롬프트 기반으로 **실제 음악을 직접 생성**

-**기존 인프라 활용**: `BgmService::generateWithLyria()` 패턴을 그대로 사용
+**2가지 Lyria 엔진 지원** (기존 API 키로 사용 가능, 별도 발급 불필요):
+
+| 엔진 | 인증 | 방식 | 특징 |
+|------|------|------|------|
+| **Lyria RealTime** (권장) | 기존 Gemini API 키 | WebSocket (브라우저 직접) | 실시간 스트리밍, BPM/스케일 실시간 조절 |
+| Lyria 2 (폴백) | Vertex AI 서비스 계정 | REST API (서버 경유) | 30초 단위 파일 생성, $0.06/30초 |
+
+#### Lyria RealTime — 브라우저에서 직접 음악 생성
+
+```
+브라우저 (Alpine.js)                         Google API
+┌───────────────────┐                      ┌──────────────────┐
+│ BPM: 130          │                      │                  │
+│ Scale: C Major    │──WebSocket 연결──→   │ Lyria RealTime   │
+│ 프롬프트 입력      │                      │ (lyria-realtime- │
+│                   │←─2초 단위 오디오──   │  exp)             │
+│ 🔊 실시간 재생    │                      │                  │
+│ BPM 슬라이더 조절 │──실시간 파라미터──→  │ 즉시 반영         │
+└───────────────────┘                      └──────────────────┘
+```
+
+- **모델**: `lyria-realtime-exp` (experimental, Gemini API v1alpha)
+- **인증**: 기존 `.env`의 `GEMINI_API_KEY` 그대로 사용
+- **출력**: 48kHz 스테레오, 2초 청크 단위 스트리밍
+- **제어 파라미터**: BPM(60~200), Scale(Key + Mode), 텍스트 프롬프트
+- **지연**: 파라미터 변경 후 최대 2초 이내 반영
+
+**Lyria RealTime 프롬프트 예시**:
+
+```
+Short sonic logo. Bright, futuristic, memorable melody.
+Clean synthesizer with light reverb.
+Ascending progression, major chord resolution.
+```
+
+#### Lyria 2 — 서버 경유 파일 생성 (폴백)
+
+기존 `BgmService::generateWithLyria()` 패턴 재활용. Vertex AI 서비스 계정(`google_service_account.json`) 이미 보유.

 ```
 사용자 입력                    서버 (Laravel)                   결과
 ┌───────────────┐            ┌──────────────────────┐       ┌──────────────┐
-│ 분위기 선택    │            │ Lyria API 호출        │       │              │
-│ 길이 (1~5초)  │──POST──→  │ (Vertex AI)           │──→   │ WAV/MP3 파일 │
-│ 프롬프트 입력  │            │                      │       │ (다운로드)    │
-└───────────────┘            │ BgmService 패턴 재활용 │       └──────────────┘
-                             └──────────────────────┘
+│ 분위기 선택    │            │ SoundLogoService      │       │              │
+│ 길이 (1~5초)  │──POST──→  │ → Lyria 2 API (REST)  │──→   │ WAV/MP3 파일 │
+│ 프롬프트 입력  │            │ (Vertex AI)           │       │ (다운로드)    │
+└───────────────┘            └──────────────────────┘       └──────────────┘
 ```

-**Lyria 프롬프트 예시**:
-
-```
-Short 3-second sonic logo for a technology company.
-Bright, futuristic, memorable 5-note melody.
-Clean synthesizer sound with light reverb.
-Ascending progression ending on a major chord.
-Instrumental only, no vocals.
-```
-
-> **주의**: Lyria는 Vertex AI 전용. `AiConfig::isVertexAi()` 체크 필수.
-> Vertex AI 미설정 시 모드 C 비활성화 (모드 A, B만 사용 가능).
+> **우선순위**: Lyria RealTime(브라우저) 먼저 시도 → 실패 시 Lyria 2(서버) 폴백.
+> 두 엔진 모두 기존 인증 정보로 사용 가능하며 별도 API 키 발급 불필요.

 ---

@@ -256,7 +282,8 @@ Instrumental only, no vocals.
 | 오디오 엔진 | Web Audio API | `OscillatorNode`, `GainNode`, `ConvolverNode` |
 | 시각화 | Canvas API | `AnalyserNode` → 파형/스펙트럼 렌더링 |
 | AI 어시스트 | Gemini 2.5 Flash | 텍스트 기반 음악 이론 분석·추천 (모드 B) |
-| AI 자동 생성 | Google Lyria | Vertex AI 기반 실제 음악 생성 (모드 C) |
+| AI 자동 생성 (1차) | Lyria RealTime | WebSocket 실시간 음악 스트리밍 (모드 C, 브라우저 직접) |
+| AI 자동 생성 (폴백) | Lyria 2 (Vertex AI) | REST API 파일 생성 (모드 C, 서버 경유) |
 | 저장 | localStorage + DB | 프로젝트 데이터(localStorage), 음원 파일(DB+Storage) |

 ### 5.2 기존 인프라 재활용
@@ -375,11 +402,13 @@ const NOTE_FREQ = {
 | 근거 표시 | AI가 이 사운드를 추천하는 이유 설명 |
 | 라우트 | `POST /rd/sound-logo/ai-assist`, `ai-refine` |

-### Phase 3 — AI 자동 생성 (Lyria) + 고도화
+### Phase 3 — AI 자동 생성 (Lyria RealTime + Lyria 2) + 고도화

 | 항목 | 내용 |
 |------|------|
-| Lyria API 연동 | 프롬프트 → 실제 음악 파일 생성 |
+| Lyria RealTime 연동 | WebSocket으로 브라우저에서 직접 실시간 음악 생성 (기존 Gemini API 키) |
+| Lyria 2 폴백 | Vertex AI REST API로 서버 경유 파일 생성 (기존 서비스 계정) |
+| 실시간 BPM/스케일 조절 | Lyria RealTime의 파라미터 실시간 변경 |
 | 화음(Chord) 편집 | 동시에 여러 음 배치 |
 | 이펙트 체인 | 리버브, 딜레이, 필터 |
 | 파형 시각화 | Canvas 실시간 파형 + 스펙트럼 |
@@ -443,10 +472,39 @@ Gemini: 기존 노트를 분석하고 피드백 반영하여 수정된 JSON 반
 수정된 음표가 에디터에 반영
 ```

-### 7.3 Vertex AI (Lyria) 호출 흐름
+### 7.3 Lyria 음악 생성 흐름
+
+#### 7.3.1 Lyria RealTime (브라우저 직접, 권장)

 ```
-사용자: "AI 자동 생성" 탭 선택
+사용자: "AI 자동 생성" 탭 → Lyria RealTime 선택
+    │
+    ▼
+브라우저 JavaScript (Alpine.js)
+    │
+    │ WebSocket 연결 (Gemini API v1alpha)
+    │ wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContent
+    │ API Key: .env GEMINI_API_KEY (서버 경유 프록시)
+    │ Model: lyria-realtime-exp
+    │
+    ▼
+Lyria RealTime 스트리밍
+    │
+    │ 2초 청크 단위 48kHz 스테레오 오디오
+    │ ← BPM/Scale 실시간 조절 가능
+    │
+    ▼
+Web Audio API로 실시간 재생 + 녹음(MediaRecorder) → WAV 저장
+```
+
+> **API 키 보안**: 브라우저에서 직접 Gemini API 키를 노출하지 않기 위해,
+> 서버를 WebSocket 프록시로 사용하거나 `/rd/sound-logo/ws-token` 엔드포인트에서
+> 임시 토큰을 발급하는 방식을 검토한다.
+
+#### 7.3.2 Lyria 2 (서버 경유, 폴백)
+
+```
+사용자: Lyria RealTime 실패 시 자동 전환
    │
    ▼
 POST /rd/sound-logo/ai-generate
@@ -515,11 +573,64 @@ WAV 파일 저장 → 다운로드 URL 반환

 ---

-## 9. 관련 문서
+## 9. API 인증 및 키 현황
+
+> **별도 API 키 발급 불필요** — 기존 인증 정보로 모든 엔진 사용 가능
+
+### 9.1 사용 가능한 인증 정보
+
+| 엔진 | 인증 방식 | 설정 위치 | 상태 |
+|------|----------|----------|------|
+| Gemini 2.5 Flash (모드 B) | API 키 | `.env` `GEMINI_API_KEY` | ✅ 운영 중 |
+| Lyria RealTime (모드 C) | 동일 API 키 | `.env` `GEMINI_API_KEY` | ✅ 사용 가능 (experimental) |
+| Lyria 2 (모드 C 폴백) | 서비스 계정 | `GOOGLE_APPLICATION_CREDENTIALS` | ✅ 파일 존재 |
+| Vertex AI | 프로젝트 ID | `.env` `VERTEX_AI_PROJECT_ID=codebridge-chatbot` | ✅ 설정됨 |
+
+### 9.2 현재 .env 설정 (관련 항목)
+
+```env
+GEMINI_API_KEY=AIzaSy...               # Gemini + Lyria RealTime 공용
+GEMINI_MODEL=gemini-2.5-flash          # 텍스트 AI (모드 B)
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+VERTEX_AI_PROJECT_ID=codebridge-chatbot # Lyria 2 (폴백)
+VERTEX_AI_LOCATION=us-central1
+GOOGLE_APPLICATION_CREDENTIALS=/var/www/sales/apikey/google_service_account.json
+```
+
+### 9.3 Lyria RealTime API 사양
+
+| 항목 | 값 |
+|------|------|
+| 모델 | `lyria-realtime-exp` |
+| API 버전 | `v1alpha` (experimental) |
+| 프로토콜 | WebSocket (양방향 스트리밍) |
+| 출력 포맷 | 48kHz 스테레오 PCM |
+| 청크 크기 | 2초 단위 |
+| 제어 파라미터 | BPM (60~200), Scale (Key + Mode) |
+| 비용 | 무료 (experimental 기간) |
+| 참고 | [공식 문서](https://ai.google.dev/gemini-api/docs/music-generation) |
+
+### 9.4 Lyria 2 API 사양 (폴백)
+
+| 항목 | 값 |
+|------|------|
+| 모델 | `lyria` |
+| API | Vertex AI REST (`/publishers/google/models/lyria:predict`) |
+| 인증 | 서비스 계정 OAuth 토큰 |
+| 출력 포맷 | WAV (base64) |
+| 비용 | $0.06 / 30초 |
+| 기존 코드 | `BgmService::generateWithLyria()` |
+
+---
+
+## 10. 관련 문서

 - [AI 관리 종합 가이드](../guides/ai-management.md) — Gemini API 설정, 호출 흐름
 - [R&D 메뉴 개요](../features/rd/README.md) — R&D 메뉴 구조
 - [디자인 인사이트](../features/rd/design-insight.md) — 유사 SPA 패턴 참고
+- [Lyria RealTime 공식 문서](https://ai.google.dev/gemini-api/docs/music-generation) — Gemini API 음악 생성
+- [Lyria 2 Vertex AI 문서](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/lyria-music-generation) — REST API 레퍼런스
+- [Lyria RealTime 개발자 가이드](https://dev.to/googleai/lyria-realtime-the-developers-guide-to-infinite-music-streaming-4m1h) — 구현 튜토리얼

 ---