Lyria RealTime으로 실시간 음악 생성

Lyria RealTime으로 실시간 음악 생성

참고: Lyria RealTime은 실험적 모델이에요.

Gemini API는 Lyria RealTime을 사용해 최첨단 실시간 스트리밍 음악 생성 모델에 접근하게 해 줘요. 개발자는 사용자가 악기 음악을 대화형으로 만들고, 지속적으로 조종하고, 연주할 수 있는 애플리케이션을 빌드할 수 있어요.

Lyria RealTime 음악 생성은 WebSocket을 사용하는 지속적·양방향·저지연 스트리밍 연결을 사용해요.

Lyria RealTime으로 무엇을 만들 수 있는지 경험하려면 AI Studio의 Prompt DJ 또는 MIDI DJ 앱을 사용해 보세요.

참고: 비스트리밍 음악 생성을 찾고 있나요? Generate music with Lyria 3.5를 참고하세요.

출처: 원문

본문

음악 생성·제어

Lyria RealTime은 모델과 실시간 통신을 유지하기 위해 Websockets를 사용한다는 점에서 Live API와 비슷하게 동작해요.

다음 코드는 음악을 생성하는 방법을 보여줘요.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(http_options={'api_version': 'v1beta'})

async def main():
    async def receive_audio(session):
      """Example background task to process incoming audio."""
      while True:
        async for message in session.receive():
          audio_data = message.server_content.audio_chunks[0].data
          # Process audio...
          await asyncio.sleep(10**-12)

    async with (
      client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
      asyncio.TaskGroup() as tg,
    ):
      # Set up task to receive server messages.
      tg.create_task(receive_audio(session))

      # Send initial prompts and config
      await session.set_weighted_prompts(
        prompts=[
          types.WeightedPrompt(text='minimal techno', weight=1.0),
        ]
      )
      await session.set_music_generation_config(
        config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
      )

      # Start streaming music
      await session.play()
if __name__ == "__main__":
    asyncio.run(main())

참고: 더 완전한 코드 샘플은 cookbooks 저장소의 Lyria RealTime - Get Started 파일을 참고하세요.

import { GoogleGenAI } from "@google/genai";
import Speaker from "speaker";
import { Buffer } from "buffer";

const client = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
    apiVersion: "v1beta" ,
});

async function main() {
  const speaker = new Speaker({
    channels: 2,       // stereo
    bitDepth: 16,      // 16-bit PCM
    sampleRate: 44100, // 44.1 kHz
  });

  const session = await client.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
      onmessage: (message) => {
        if (message.serverContent?.audioChunks) {
          for (const chunk of message.serverContent.audioChunks) {
            const audioBuffer = Buffer.from(chunk.data, "base64");
            speaker.write(audioBuffer);
          }
        }
      },
      onerror: (error) => console.error("music session error:", error),
      onclose: () => console.log("Lyria RealTime stream closed."),
    },
  });

  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: "Minimal techno with deep bass, sparse percussion, and atmospheric synths", weight: 1.0 },
    ],
  });

  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 90,
      temperature: 1.0,
      audioFormat: "pcm16",  // important so we know format
      sampleRateHz: 44100,
    },
  });

  await session.play();
}

main().catch(console.error);

참고: 더 완전한 코드 샘플은 AI Studio의 Prompt DJ와 MIDI DJ 앱을 시도해 보세요.

그런 다음 session.play(), session.pause(), session.stop(), session.reset_context()로 세션을 시작·일시정지·중지·리셋할 수 있어요.

실시간으로 음악 조종하기

프롬프트를 보내고 생성 파라미터를 실시간으로 업데이트해 음악 생성을 실시간으로 조종할 수 있어요.

Lyria RealTime 프롬프팅

스트림이 활성인 동안 언제든 새 WeightedPrompt 메시지를 보내 생성된 음악을 바꿀 수 있어요. 모델은 새 입력에 따라 부드럽게 전환해요.

프롬프트는 text(실제 프롬프트)와 weight로 올바른 형식을 따라야 해요. weight는 0을 제외한 어떤 값도 가능해요. 보통 1.0이 좋은 시작점이에요.

from google.genai import types

await session.set_weighted_prompts(
  prompts=[
    {"text": "Piano", "weight": 2.0},
    types.WeightedPrompt(text="Meditation", weight=0.5),
    types.WeightedPrompt(text="Live Performance", weight=1.0),
  ]
)

await session.setWeightedPrompts({
  weightedPrompts: [
    { text: 'Harmonica', weight: 0.3 },
    { text: 'Afrobeat', weight: 0.7 }
  ],
});

프롬프트를 크게 바꾸면 모델 전환이 약간 갑작스러울 수 있으므로, 모델에 중간 weight 값을 보내 어떤 종류의 크로스페이드를 구현하는 것이 좋아요.

구성 업데이트

음악 생성 파라미터를 실시간으로 업데이트해 음악 생성을 조종할 수 있어요. 파라미터 하나만 업데이트할 수는 없고, 전체 구성을 설정해야 해요. 그렇지 않으면 다른 필드가 기본값으로 리셋돼요.

bpm이나 scale을 업데이트하는 것은 모델에 큰 변화이므로 reset_context()로 컨텍스트를 리셋하라고 알려야 새 구성이 반영돼요. 스트림을 중지하지는 않지만 하드 전환이 될 거예요. 다른 파라미터에는 이 작업이 필요 없어요.

from google.genai import types

await session.set_music_generation_config(
  config=types.LiveMusicGenerationConfig(
    bpm=128,
    scale=types.Scale.D_MAJOR_B_MINOR,
    music_generation_mode=types.MusicGenerationMode.QUALITY
  )
)
await session.reset_context();

await session.setMusicGenerationConfig({
  musicGenerationConfig: { 
    bpm: 120,
    density: 0.75,
    musicGenerationMode: MusicGenerationMode.QUALITY
  },
});
await session.reset_context();

Lyria RealTime 프롬프팅

Lyria RealTime은 가중 프롬프트(weighted prompts)로 음악 장르·악기·분위기를 동적으로 혼합해요. 프롬프트 조종 전략, 키워드 태그 어휘, 전체 프롬프트 예제를 탐색하려면 Lyria prompt guide를 참고하세요.

모범 사례

  • 클라이언트 애플리케이션은 원활한 재생을 위해 견고한 오디오 버퍼링을 구현해야 해요. 이는 네트워크 지터와 생성 지연의 약간의 변동을 보완하는 데 도움이 돼요.
  • 효과적인 프롬프팅:
    • 서술적으로 표현하세요. 분위기·장르·악기를 나타내는 형용사를 사용하세요.
    • 점진적으로 반복·조종하세요. 프롬프트를 완전히 바꾸기보다 요소를 추가·수정해 음악을 더 부드럽게 변형해 보세요.
    • WeightedPrompt의 weight를 실험해 새 프롬프트가 진행 중인 생성에 얼마나 강하게 영향을 주는지 조절하세요.

기술적 세부 사항

이 섹션은 Lyria RealTime 음악 생성 사용 방법의 구체사항을 설명해요.

사양

  • 출력 형식: Raw 16-bit PCM Audio
  • 샘플 레이트: 48kHz
  • 채널: 2(스테레오)

컨트롤

음악 생성은 다음을 담은 메시지를 보내 실시간으로 영향받을 수 있어요.

  • WeightedPrompt: 음악적 아이디어·장르·악기·분위기·특성을 설명하는 텍스트 문자열. 여러 프롬프트를 제공해 영향력을 혼합할 수 있어요. Lyria RealTime 프롬프팅 방법은 위 음악 조종 섹션 참고.

  • MusicGenerationConfig: 음악 생성 과정의 구성으로, 출력 오디오의 특성에 영향을 줘요. 파라미터는 다음과 같아요.

    • guidance: (float) 범위: [0.0, 6.0]. 기본값: 4.0. 모델이 프롬프트를 얼마나 엄격히 따르는지 제어해요. guidance를 높이면 프롬프트 준수가 좋아지지만 전환이 더 갑작스러워져요.
    • bpm: (int) 범위: [60, 200]. 생성된 음악에 원하는 Beats Per Minute을 설정해요. 새 bpm을 반영하려면 stop/play하거나 컨텍스트를 리셋해야 해요.
    • density: (float) 범위: [0.0, 1.0]. 음악적 음표·소리의 밀도를 제어해요. 낮은 값은 더 드문 음악을, 높은 값은 더 "바쁜" 음악을 만들어요.
    • brightness: (float) 범위: [0.0, 1.0]. 음조 품질을 조정해요. 높은 값은 일반적으로 높은 주파수를 강조해 "더 밝은" 소리의 오디오를 만들어요.
    • scale: (Enum) 생성의 음악적 스케일(Key와 Mode)을 설정해요. SDK가 제공하는 Scale enum 값을 사용하세요. 새 scale을 반영하려면 stop/play하거나 컨텍스트를 리셋해야 해요.
    • mute_bass: (bool) 기본값: False. 모델이 출력의 베이스를 줄이는지 제어해요.
    • mute_drums: (bool) 기본값: False. 모델이 출력의 드럼을 줄이는지 제어해요.
    • only_bass_and_drums: (bool) 기본값: False. 모델이 베이스와 드럼만 출력하도록 조종해요.
    • music_generation_mode: (Enum) 모델이 음악의 QUALITY(기본값)에 집중할지 DIVERSITY에 집중할지 나타내요. VOCALIZATION으로 설정해 모델이 보컬라이즈를 또 다른 악기로 생성하게 할 수도 있어요(새 프롬프트로 추가).

  • PlaybackControl: play, pause, stop 또는 컨텍스트 리셋 같은 재생 측면을 제어하는 명령.

bpm, density, brightness, scale에 값이 제공되지 않으면 모델이 초기 프롬프트에 따라 가장 좋은 것을 결정해요.

temperature(0.03.0, 기본 1.1), top_k(11000, 기본 40), seed(0~2,147,483,647, 기본은 무작위 선택) 같은 더 전통적인 파라미터도 MusicGenerationConfig에서 커스터마이즈할 수 있어요.

Scale Enum 값

모델이 수용할 수 있는 모든 scale 값은 다음과 같아요.

Enum 값 Scale / Key
C_MAJOR_A_MINOR C major / A minor
D_FLAT_MAJOR_B_FLAT_MINOR D♭ major / B♭ minor
D_MAJOR_B_MINOR D major / B minor
E_FLAT_MAJOR_C_MINOR E♭ major / C minor
E_MAJOR_D_FLAT_MINOR E major / C♯/D♭ minor
F_MAJOR_D_MINOR F major / D minor
G_FLAT_MAJOR_E_FLAT_MINOR G♭ major / E♭ minor
G_MAJOR_E_MINOR G major / E minor
A_FLAT_MAJOR_F_MINOR A♭ major / F minor
A_MAJOR_G_FLAT_MINOR A major / F♯/G♭ minor
B_FLAT_MAJOR_G_MINOR B♭ major / G minor
B_MAJOR_A_FLAT_MINOR B major / G♯/A♭ minor
SCALE_UNSPECIFIED 기본 / 모델이 결정

모델은 연주되는 음을 안내할 수 있지만 상대 조성을 구분하지는 못해요. 따라서 각 enum은 상대 장조와 단조 모두에 대응해요. 예를 들어 C_MAJOR_A_MINOR는 피아노의 모든 흰 건반에 해당하고, F_MAJOR_D_MINOR는 B♭을 제외한 모든 흰 건반에 해당해요.

한계

  • 악기 전용: 모델은 악기 음악만 생성해요.
  • 안전: 프롬프트는 안전 필터로 검사돼요. 필터를 트리거하는 프롬프트는 무시되며, 이 경우 출력의 filtered_prompt 필드에 설명이 기록돼요.
  • 워터마킹: 출력 오디오는 Responsible AI 원칙에 따라 식별을 위해 항상 워터마킹돼요.

다음 단계

더 많은 코드 예제와 튜토리얼은 Cookbook을 살펴보세요.

더 알아보기 (Learn more)