tools.play_music module

Play music in Discord voice channels using Lyria RealTime via ctx.adapter.

async tools.play_music.run(guild_id, channel_id=None, prompt=None, bpm=135, temperature=1.0, brightness=0.5, scale=None, music_generation_mode=None, guidance=None, density=None, mute_bass=None, mute_drums=None, only_bass_and_drums=None, top_k=None, seed=None, ctx=None)[source]

Join a Discord voice channel and start AI-generated music via Lyria.

Implements the play_music tool: it connects (or moves) the bot into a voice channel and kicks off a continuous Lyria RealTime generation session driven by the supplied prompt and musical parameters. This is the heavy entry point of the music subsystem; pause_music, resume_music, and steer_music operate on the session it creates.

The work fans out across several collaborators: the live discord.Client is obtained through tools._discord_helpers.get_discord_client, prompts are parsed by services.lyria_session.parse_prompts, and a Gemini API key is resolved per-user via tools.manage_api_keys.get_user_api_key (falling back to a shared default key that is rate-limited through default_key_limit_applies / check_default_key_limit / increment_default_key_usage, all keyed in Redis via ctx.redis). It then touches Discord voice state directly (connect / move_to / disconnect), builds a google.genai.types.LiveMusicGenerationConfig, and hands everything to ctx.adapter.lyria_service (init_client, is_playing, start_session, stop) which streams audio into the channel. On any exception it stops the Lyria session and force-disconnects the voice client to avoid leaving a dangling connection. It is registered and dispatched dynamically by tool_loader.py as the module-level run handler; no in-repo callers invoke it directly outside of tests.

Parameters:

  • guild_id (str) – Discord server (guild) ID as a string; must parse to an int.

  • channel_id (str) – Optional voice channel ID. When omitted, the first voice channel that currently has members is chosen.

  • prompt (str) – Music description in prompt:weight form; defaults to "Violin metal" when None.

  • bpm (int) – Beats per minute for the generation config.

  • temperature (float) – Sampling creativity passed to Lyria.

  • brightness (float) – Tonal brightness passed to Lyria.

  • scale (str) – Optional musical scale name resolved against types.Scale.

  • music_generation_mode (str) – Optional mode name resolved against types.MusicGenerationMode (QUALITY, DIVERSITY, VOCALIZATION).

  • guidance (float) – Optional prompt-adherence strength (validated 0.0-6.0).

  • density (float) – Optional note density (validated 0.0-1.0).

  • mute_bass (bool) – Optional flag to reduce bass output.

  • mute_drums (bool) – Optional flag to reduce drums output.

  • only_bass_and_drums (bool) – Optional flag to restrict output to bass and drums.

  • top_k (int) – Optional sampling parameter (validated 1-1000).

  • seed (int) – Optional random seed (validated 0-2147483647).

  • ctx (ToolContext | None) – The tool execution context. Must expose a non-None adapter; ctx.redis and ctx.user_id are used for key resolution and rate limiting.

Returns:

A human-readable confirmation describing the prompt, channel, bitrate, and guild tier on success, or an Error: prefixed string for any validation, connection, or generation failure.

Return type:

str