# 사운드 로고 생성기 — 기획서

> **작성일**: 2026-03-08
> **상태**: 기획 확정
> **메뉴명**: 사운드 로고 생성기
> **라우트**: `GET /rd/sound-logo`
> **담당**: R&D실

---

## 1. 개요

### 1.1 목적

1~5초의 **짧고 강렬한 시그니처 사운드(Sound Logo)**를 생성하는 도구. 브라우저 내 Web Audio API 신디사이저와 Google Gemini AI를 결합하여, 누구나 전문적인 사운드 로고를 만들 수 있도록 한다.

### 1.2 벤치마킹

| 브랜드 | 사운드 | 길이 | 특징 |
|--------|--------|------|------|
| Intel | 봉-봉봉봉-봉 | 1.5초 | 5음, 밝고 미래적 |
| Netflix | 타-둠 | 3초 | 2음, 깊은 울림 + 리버브 |
| Samsung | 오버더호라이즌 | 2초 | 5음, 따뜻한 멜로디 |
| McDonald's | 바다바바~ | 2초 | 5음, 경쾌한 리듬 |
| Windows | 시작 사운드 | 3초 | 4음, 화음 진행 |
| 카카오톡 | 카톡~ | 0.5초 | 2음, 귀여운 효과음 |
| T-Mobile | 띠-띠띠-띠-띠 | 1초 | 5음, 단순 반복 |

### 1.3 핵심 차별점 — AI 어드바이저 엔진

단순 신디사이저 도구가 아니라, **Google Gemini AI가 음악 이론 기반으로 조언하고 생성을 도와주는** 지능형 도구.

```
┌─────────────────────────────────────────────────────┐
│                  사운드 로고 생성기                     │
│                                                      │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐      │
│  │ 수동 모드  │    │ AI 어시스트│    │ AI 자동   │      │
│  │ (신디사이저)│ ←→ │ (Gemini)  │ ←→ │ (Lyria)  │      │
│  │          │    │          │    │          │      │
│  │ 음표 직접  │    │ 브랜드 분석│    │ 프롬프트→ │      │
│  │ 배치/편집  │    │ 음악 추천  │    │ AI 음악   │      │
│  │          │    │ 코드 제안  │    │ 직접 생성  │      │
│  └──────────┘    └──────────┘    └──────────┘      │
│       ↕               ↕               ↕             │
│  ┌──────────────────────────────────────────┐      │
│  │          Web Audio API 재생 엔진           │      │
│  │    (실시간 미리듣기 + WAV 내보내기)          │      │
│  └──────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────┘
```

---

## 2. 3가지 모드 설계

### 2.1 모드 A — 수동 모드 (신디사이저)

> 음표를 직접 배치하고 파라미터를 조절하여 사운드를 만드는 전통적 방식

| 기능 | 설명 |
|------|------|
| 음표 시퀀서 | 음표(C4, E4 등) + 길이(0.05~2초) + 쉼표를 시각적 배열로 편집 |
| 신디사이저 4종 | Sine(부드러움), Square(8bit), Triangle(따뜻함), Sawtooth(날카로움) |
| ADSR 엔벨로프 | Attack(0~500ms), Decay(0~1s), Sustain(0~1), Release(0~3s) |
| 화음(Chord) | 동시에 여러 음 재생 (C+E+G = C Major 등) |
| 이펙트 | 리버브, 딜레이, 로우패스/하이패스 필터 |
| 파형 시각화 | Canvas 실시간 파형 + 스펙트럼 표시 |

**기술 기반**: Web Audio API (`OscillatorNode`, `GainNode`, `BiquadFilterNode`, `ConvolverNode`)

### 2.2 모드 B — AI 어시스트 (Gemini 텍스트)

> 브랜드 정보를 입력하면 Gemini가 **음악 이론 기반으로 사운드 로고를 설계**해 주고, 사용자가 미세 조정

**입력 → AI 분석 → 음표 데이터 출력 → Web Audio 재생**

```
사용자 입력                    Gemini 분석·추천                    출력
┌───────────────┐            ┌──────────────────────┐          ┌──────────────┐
│ 브랜드명       │            │                      │          │              │
│ 업종/분위기    │──요청──→   │ 1. 브랜드 성격 분석    │──JSON──→ │ 음표 시퀀스   │
│ 키워드        │            │ 2. 조성/스케일 추천    │          │ BPM, 조성    │
│ 참고 브랜드    │            │ 3. 음표 시퀀스 생성    │          │ 신디 파라미터 │
│ 원하는 느낌    │            │ 4. ADSR 파라미터 제안  │          │ ADSR 값     │
└───────────────┘            │ 5. 이펙트 추천        │          │ 이펙트 설정   │
                             │ 6. 근거 설명          │          │              │
                             └──────────────────────┘          └──────────────┘
                                                                      ↓
                                                               Web Audio 재생
                                                                      ↓
                                                               사용자 미세 조정
```

**Gemini 프롬프트 설계**:

```
당신은 사운드 브랜딩 전문가이자 음악 이론가입니다.
다음 브랜드 정보를 분석하여 1~5초 사운드 로고를 설계해 주세요.

[브랜드 정보]
- 브랜드명: {name}
- 업종: {industry}
- 브랜드 성격: {personality} (예: 혁신적, 신뢰, 친근함)
- 참고 사운드: {reference} (예: 인텔처럼 밝은 느낌)
- 원하는 길이: {duration}초

[응답 형식 - 반드시 JSON으로]
{
  "analysis": "브랜드 분석 설명 (한글)",
  "reasoning": "이 사운드를 추천하는 음악 이론적 근거 (한글)",
  "key": "C",
  "scale": "major",
  "bpm": 120,
  "synth": "sine",
  "adsr": { "attack": 0.01, "decay": 0.1, "sustain": 0.7, "release": 0.5 },
  "effects": { "reverb": 0.3, "delay": 0 },
  "notes": [
    { "note": "C5", "duration": 0.2, "velocity": 0.8 },
    { "note": "E5", "duration": 0.2, "velocity": 0.9 },
    { "note": "G5", "duration": 0.15, "velocity": 0.7 },
    { "rest": 0.05 },
    { "chord": ["C5", "E5", "G5"], "duration": 0.8, "velocity": 1.0 }
  ],
  "variations": [
    { "name": "밝은 버전", "notes": [...] },
    { "name": "차분한 버전", "notes": [...] }
  ]
}
```

**AI 어시스트 기능 상세**:

| 기능 | 설명 |
|------|------|
| 브랜드 분석 | 업종·성격 기반 적합한 조성/템포/음색 추천 |
| 음표 시퀀스 생성 | 음악 이론(화성학, 리듬 패턴) 기반 멜로디 제안 |
| 변형 3종 제공 | 밝은/차분한/임팩트 버전 동시 생성 |
| 근거 설명 | "C Major → 신뢰감, 5도 상행 → 상승 에너지" 등 이론 설명 |
| 반복 개선 | "좀 더 밝게" "더 짧게" 등 자연어로 수정 요청 |

### 2.3 모드 C — AI 자동 생성 (Google Lyria)

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

**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)                   결과
┌───────────────┐            ┌──────────────────────┐       ┌──────────────┐
│ 분위기 선택    │            │ SoundLogoService      │       │              │
│ 길이 (1~5초)  │──POST──→  │ → Lyria 2 API (REST)  │──→   │ WAV/MP3 파일 │
│ 프롬프트 입력  │            │ (Vertex AI)           │       │ (다운로드)    │
└───────────────┘            └──────────────────────┘       └──────────────┘
```

> **우선순위**: Lyria RealTime(브라우저) 먼저 시도 → 실패 시 Lyria 2(서버) 폴백.
> 두 엔진 모두 기존 인증 정보로 사용 가능하며 별도 API 키 발급 불필요.

---

## 3. UI 레이아웃

```
┌─────────────────────────────────────────────────────────────────┐
│  🎵 사운드 로고 생성기                    [내 프로젝트 ▾] [저장]  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  모드: [🎹 수동] [🤖 AI 어시스트] [✨ AI 자동]                    │
│                                                                  │
│  ┌─ 모드 B: AI 어시스트 ──────────────────────────────────────┐ │
│  │                                                             │ │
│  │  브랜드명    [SAM                    ]                      │ │
│  │  업종       [ERP/MES 통합 솔루션      ]                      │ │
│  │  브랜드 성격 [○혁신적 ●신뢰 ○친근 ○고급 ○에너지]              │ │
│  │  참고 사운드 [인텔처럼 짧고 밝은 ▾    ]                      │ │
│  │  길이       [━━━●━━━ 2초            ]                       │ │
│  │                                                             │ │
│  │  [🤖 AI에게 사운드 설계 요청]                                │ │
│  │                                                             │ │
│  │  ┌─ AI 분석 결과 ─────────────────────────────────────┐    │ │
│  │  │ 💡 "SAM은 ERP/MES 통합 솔루션으로, 신뢰와 기술력을    │    │ │
│  │  │  전달해야 합니다. C Major 조성으로 안정감을,           │    │ │
│  │  │  5도 상행 진행으로 성장과 발전을 표현합니다."           │    │ │
│  │  │                                                     │    │ │
│  │  │ 추천: C Major | BPM 130 | Sine + 리버브 30%         │    │ │
│  │  │                                                     │    │ │
│  │  │ 변형 3종:                                            │    │ │
│  │  │ [▶ 밝은 버전] [▶ 차분한 버전] [▶ 임팩트 버전]         │    │ │
│  │  └─────────────────────────────────────────────────────┘    │ │
│  │                                                             │ │
│  │  💬 추가 요청: [좀 더 짧고 강렬하게 해줘            ] [전송]  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌─ 음표 에디터 (AI 결과 또는 수동 편집) ──────────────────────┐ │
│  │  C5(0.2s)  E5(0.2s)  G5(0.15s)  .(0.05s)  [CEG](0.8s)    │ │
│  │  ████      ████      ███        ·          ████████████    │ │
│  │  [+음표] [+쉼표] [+화음] [삭제]                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌─ 파라미터 ────────────────────────────────────────────────┐ │
│  │  음색:   ●Sine  ○Square  ○Triangle  ○Sawtooth             │ │
│  │  BPM:    ━━━━━━●━━━━━ 130                                 │ │
│  │  리버브:  ━━━●━━━━━━━ 30%                                  │ │
│  │  Attack:  ━●━━━━━━━━ 10ms    Release: ━━━━━●━━━ 500ms     │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌─ 파형 시각화 ─────────────────────────────────────────────┐ │
│  │  ∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿ │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  [▶ 재생]  [⏹ 정지]  [💾 WAV 저장]  [📋 JSON 내보내기]          │
│                                                                  │
├─ 내 사운드 라이브러리 ──────────────────────────────────────────┤
│  🎵 SAM 시그널 v1  |  🎵 알림음 v2  |  🎵 전환 효과  | [+ 새로]  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 4. 프리셋 템플릿 (10종)

| 프리셋 | 스타일 | 음표 수 | 길이 | 용도 |
|--------|--------|---------|------|------|
| 기업 시그널 (밝음) | Intel 스타일 | 5 | 1.5초 | 브랜드 인트로 |
| 기업 시그널 (무게감) | Netflix 스타일 | 2 | 3초 | 프리미엄 브랜드 |
| 알림음 (경쾌) | 카카오톡 스타일 | 2~3 | 0.5초 | 푸시 알림 |
| 알림음 (정보) | Slack 스타일 | 3 | 1초 | 시스템 알림 |
| 성공 사운드 | 게임 레벨업 | 4 | 1초 | 작업 완료 |
| 에러 사운드 | 경고음 | 2 | 0.5초 | 오류 알림 |
| 전환 효과 (업) | 상승 스윕 | 연속 | 0.5초 | 화면 전환 |
| 전환 효과 (다운) | 하강 스윕 | 연속 | 0.5초 | 메뉴 닫기 |
| 팡파레 | 축하 | 6 | 2초 | 이벤트/달성 |
| 로딩 루프 | 반복 패턴 | 4 | 2초 | 대기 상태 |

---

## 5. 기술 아키텍처

### 5.1 기술 스택

| 계층 | 기술 | 설명 |
|------|------|------|
| 프론트엔드 | Blade + Alpine.js | 단일 파일 SPA (디자인 인사이트 패턴) |
| 오디오 엔진 | Web Audio API | `OscillatorNode`, `GainNode`, `ConvolverNode` |
| 시각화 | Canvas API | `AnalyserNode` → 파형/스펙트럼 렌더링 |
| AI 어시스트 | Gemini 2.5 Flash | 텍스트 기반 음악 이론 분석·추천 (모드 B) |
| AI 자동 생성 (1차) | Lyria RealTime | WebSocket 실시간 음악 스트리밍 (모드 C, 브라우저 직접) |
| AI 자동 생성 (폴백) | Lyria 2 (Vertex AI) | REST API 파일 생성 (모드 C, 서버 경유) |
| 저장 | localStorage + DB | 프로젝트 데이터(localStorage), 음원 파일(DB+Storage) |

### 5.2 기존 인프라 재활용

| 기존 코드 | 재활용 내용 |
|----------|-----------|
| `BgmService::generateWithLyria()` | Lyria API 호출 패턴, Vertex AI 인증 흐름 |
| `BgmService::getMoodChord()` | 분위기별 화음 주파수 매핑 |
| `BgmService::generateAmbient()` | FFmpeg 기반 오디오 합성 (서버사이드 폴백) |
| `CmSongController::generateLyrics()` | Gemini API 호출 패턴 (프롬프트 → JSON 응답) |
| `CmSongController::pcmToWav()` | PCM → WAV 변환 유틸리티 |
| `AiConfig::getActiveGemini()` | AI 설정 조회 (API 키, 모델, 리전) |
| `GoogleCloudService::getAccessToken()` | Vertex AI 인증 토큰 |

### 5.3 파일 구조

```
app/Http/Controllers/Rd/
└── SoundLogoController.php        # 컨트롤러 (AI API 프록시)

app/Services/Rd/
└── SoundLogoService.php           # Gemini 프롬프트 + Lyria 호출

resources/views/rd/sound-logo/
└── index.blade.php                # 단일 파일 SPA

routes/web.php                     # 라우트 추가
```

### 5.4 라우트 설계

| Method | Path | 컨트롤러 | 설명 |
|--------|------|---------|------|
| `GET` | `/rd/sound-logo` | `soundLogo.index` | 메인 페이지 |
| `POST` | `/rd/sound-logo/ai-assist` | `soundLogo.aiAssist` | Gemini 음악 설계 요청 (모드 B) |
| `POST` | `/rd/sound-logo/ai-refine` | `soundLogo.aiRefine` | Gemini 추가 수정 요청 |
| `POST` | `/rd/sound-logo/ai-generate` | `soundLogo.aiGenerate` | Lyria 음악 생성 (모드 C) |
| `POST` | `/rd/sound-logo/save` | `soundLogo.save` | 사운드 저장 (DB + Storage) |
| `GET` | `/rd/sound-logo/{id}/download` | `soundLogo.download` | WAV 다운로드 |

### 5.5 Web Audio API 핵심 구조

```javascript
// 노드 그래프
const ctx = new AudioContext();

// Oscillator → Gain(ADSR) → Filter → Reverb → Analyser → Destination
function createSynthChain(type, freq, adsr, effects) {
    const osc  = ctx.createOscillator();       // 음원
    const gain = ctx.createGain();              // ADSR 엔벨로프
    const filter = ctx.createBiquadFilter();    // LP/HP 필터
    const analyser = ctx.createAnalyser();      // 시각화

    osc.type = type;           // sine | square | triangle | sawtooth
    osc.frequency.value = freq; // Hz

    // ADSR
    const now = ctx.currentTime;
    gain.gain.setValueAtTime(0, now);
    gain.gain.linearRampToValueAtTime(1, now + adsr.attack);
    gain.gain.linearRampToValueAtTime(adsr.sustain, now + adsr.attack + adsr.decay);

    osc.connect(gain).connect(filter).connect(analyser).connect(ctx.destination);
    return { osc, gain, filter, analyser };
}

// WAV 내보내기 (OfflineAudioContext)
async function exportWav(notes, params) {
    const offline = new OfflineAudioContext(2, 44100 * duration, 44100);
    // ... 노트 렌더링
    const buffer = await offline.startRendering();
    const wav = audioBufferToWav(buffer);
    // Blob → 다운로드
}
```

### 5.6 음표 ↔ 주파수 매핑

```javascript
const NOTE_FREQ = {
    'C3': 130.81, 'D3': 146.83, 'E3': 164.81, 'F3': 174.61,
    'G3': 196.00, 'A3': 220.00, 'B3': 246.94,
    'C4': 261.63, 'D4': 293.66, 'E4': 329.63, 'F4': 349.23,
    'G4': 392.00, 'A4': 440.00, 'B4': 493.88,
    'C5': 523.25, 'D5': 587.33, 'E5': 659.25, 'F5': 698.46,
    'G5': 783.99, 'A5': 880.00, 'B5': 987.77,
    'C6': 1046.50
    // 반음(#/b)도 포함
};
```

---

## 6. Phase별 개발 계획

### Phase 1 — MVP (수동 모드 + 프리셋)

| 항목 | 내용 |
|------|------|
| 음표 시퀀서 UI | 음표 추가/삭제/편집, 드래그 순서 변경 |
| 신디사이저 4종 | Sine, Square, Triangle, Sawtooth |
| ADSR 슬라이더 | Attack, Decay, Sustain, Release |
| 실시간 재생 | Web Audio API 즉시 재생 |
| WAV 내보내기 | OfflineAudioContext → WAV 다운로드 |
| 프리셋 10종 | 즉시 로드 가능한 사운드 패턴 |
| 프로젝트 저장 | localStorage (디자인 인사이트 패턴) |

### Phase 2 — AI 어시스트 (Gemini)

| 항목 | 내용 |
|------|------|
| 브랜드 입력 폼 | 브랜드명, 업종, 성격, 참고 사운드, 길이 |
| Gemini 분석 API | 브랜드 → 음악 이론 기반 사운드 설계 JSON |
| 변형 3종 생성 | 밝은/차분한/임팩트 버전 동시 제공 |
| 대화형 개선 | "좀 더 밝게" 등 자연어 추가 수정 |
| 근거 표시 | AI가 이 사운드를 추천하는 이유 설명 |
| 라우트 | `POST /rd/sound-logo/ai-assist`, `ai-refine` |

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

| 항목 | 내용 |
|------|------|
| Lyria RealTime 연동 | WebSocket으로 브라우저에서 직접 실시간 음악 생성 (기존 Gemini API 키) |
| Lyria 2 폴백 | Vertex AI REST API로 서버 경유 파일 생성 (기존 서비스 계정) |
| 실시간 BPM/스케일 조절 | Lyria RealTime의 파라미터 실시간 변경 |
| 화음(Chord) 편집 | 동시에 여러 음 배치 |
| 이펙트 체인 | 리버브, 딜레이, 필터 |
| 파형 시각화 | Canvas 실시간 파형 + 스펙트럼 |
| DB 저장 | 사운드 로고를 DB + Storage에 영구 저장 |
| 공유/내보내기 | JSON 설정 공유, MP3 변환 |

### Phase 4 — 프로급 확장 (선택)

| 항목 | 내용 |
|------|------|
| 타임라인 UI | 드래그로 음표 배치하는 DAW 스타일 |
| 샘플 기반 음색 | 피아노, 벨, 마림바 등 실제 악기 |
| 드럼/퍼커션 | 노이즈 기반 킥/스네어/하이햇 |
| MIDI 내보내기 | 전문 DAW에서 추가 편집 가능 |
| A/B 비교 | 두 사운드를 나란히 비교 재생 |

---

## 7. Gemini AI 연동 상세

### 7.1 API 호출 흐름

```
Frontend (Alpine.js)
    │
    │ POST /rd/sound-logo/ai-assist
    │ { brand_name, industry, personality, reference, duration }
    │
    ▼
SoundLogoController::aiAssist()
    │
    │ 프롬프트 구성
    │
    ▼
Gemini 2.5 Flash API
    │
    │ JSON 응답 (notes, adsr, effects, analysis)
    │
    ▼
SoundLogoController → JsonResponse
    │
    │ { success: true, data: { notes, params, analysis, variations } }
    │
    ▼
Frontend: 음표 에디터에 자동 로드 → 즉시 재생
```

### 7.2 대화형 개선 흐름

```
사용자: "좀 더 짧고 강렬하게"
    │
    ▼
POST /rd/sound-logo/ai-refine
{ previous_notes: [...], feedback: "좀 더 짧고 강렬하게" }
    │
    ▼
Gemini: 기존 노트를 분석하고 피드백 반영하여 수정된 JSON 반환
    │
    ▼
수정된 음표가 에디터에 반영
```

### 7.3 Lyria 음악 생성 흐름

#### 7.3.1 Lyria RealTime (브라우저 직접, 권장)

```
사용자: "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
{ mood: "bright_futuristic", duration: 3, prompt: "..." }
    │
    ▼
SoundLogoService::generateWithLyria()
    ├── AiConfig::getActiveGemini() → Vertex AI 설정 확인
    ├── GoogleCloudService::getAccessToken() → OAuth 토큰
    └── Lyria API 호출 → audioContent (base64)
    │
    ▼
WAV 파일 저장 → 다운로드 URL 반환
```

---

## 8. 데이터 모델

### 8.1 localStorage 구조 (Phase 1~2)

```json
{
  "sl_projects": [
    {
      "id": "sl_1709000000_abc",
      "title": "SAM 사운드 로고",
      "sounds": [
        {
          "id": "snd_001",
          "name": "SAM 시그널 v1",
          "notes": [
            { "note": "C5", "duration": 0.2, "velocity": 0.8 },
            { "note": "E5", "duration": 0.2, "velocity": 0.9 },
            { "chord": ["C5", "E5", "G5"], "duration": 0.8, "velocity": 1.0 }
          ],
          "params": {
            "synth": "sine",
            "bpm": 130,
            "adsr": { "attack": 0.01, "decay": 0.1, "sustain": 0.7, "release": 0.5 },
            "effects": { "reverb": 0.3, "delay": 0, "filterFreq": 2000 }
          },
          "aiAnalysis": "C Major 조성, 5도 상행으로 신뢰감과 성장 표현",
          "createdAt": "2026-03-08T00:00:00.000Z"
        }
      ],
      "createdAt": "2026-03-08T00:00:00.000Z"
    }
  ],
  "sl_current": "sl_1709000000_abc"
}
```

### 8.2 DB 테이블 (Phase 3, API 프로젝트에서 마이그레이션)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | bigint | PK |
| `tenant_id` | bigint | FK → tenants |
| `user_id` | bigint | FK → users |
| `name` | varchar(200) | 사운드 이름 |
| `audio_path` | varchar(500) | WAV/MP3 파일 경로 |
| `options` | json | notes, params, aiAnalysis 등 |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

## 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) — 구현 튜토리얼

---

**최종 업데이트**: 2026-03-08
