Music Player

When to useCopy Anchor Link

• The user asks what's playing, or to control playback on their music app. Use mode now-playing with the state the provider reports.
• The agent built a playlist or found tracks to add to one. Use mode playlist, so the user can preview, reorder, remove and save.

When not to useCopy Anchor Link

• The agent doesn't have the tracks from the user's music provider. Never invent tracks, artwork or preview URLs.
• It's a recording, a podcast clip or a voice note. Use the Audio Player.
• The user only wants a name or two. Say them in text.

How the agent should use itCopy Anchor Link

• Pass tracks, artwork, previewUrl, url and nowPlaying exactly as the provider returns them. The provider is data: its name appears as text ("Open in Music app"), with no logos or brand colors.
• Now-playing: put the current track first in tracks, then what's up next. Each control sends a request back. Carry it out with the provider, then show the new state.
• Playlist: save nothing until save-playlist arrives, then save exactly trackIds, in that order, under title.
• On open-in-provider, hand off to the user's music app. On dismiss, save nothing.

Playback and previewsCopy Anchor Link

Two kinds of playback, kept apart:

Full tracks always hand off to the provider: the now-playing card links to the current track's url, and the playlist's "Open in provider.name" item (in the footer's "More actions" menu, next to Dismiss) returns open-in-provider.

LayoutCopy Anchor Link

• Now playing: the device ("Playing on Kitchen speaker"), then the artwork with the track title large and the artists, the seek bar with its times, and the transport row (shuffle, previous, play/pause, next, repeat as an icon toggle). Up next follows. The album is read to screen readers only.
• Playlist: the title and one quiet line with the totals, then the tracks. The footer holds Undo (after a removal), a "More actions" menu (Open in the provider, Dismiss) and Save playlist. The playlist description is read to screen readers only.

Editing a playlistCopy Anchor Link

With editable (the default), the user reorders and removes tracks before saving. Nothing reaches the agent until they save.

The header totals ("8 tracks · 32 min") follow the edits. Past 6 tracks the list scrolls inside the card.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/music-player.json

UsageCopy Anchor Link

import { tool } from "ai"
import { musicPlayerTool } from "@/components/genui/music-player.schema"

const tools = {
  // No execute(): the call is completed by the user's action in the UI.
  [musicPlayerTool.name]: tool({
    description: musicPlayerTool.description,
    inputSchema: musicPlayerTool.inputSchema,
  }),
}

<MusicPlayer
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) => sendToAgent(part.toolCallId, result)}
/>

In now-playing mode onResult fires on every control, so route results to the agent (or straight to the provider) rather than completing the tool call with the first one. The agent receives one of:

// Now-playing. trackId is the track on screen when the control was used.
{ action: "play" | "pause" | "next" | "previous", trackId: "tidewater" }
{ action: "like" | "unlike" | "shuffle-on" | "shuffle-off", trackId: "tidewater" }
{ action: "repeat", value: "off" | "all" | "one", trackId: "tidewater" }
{ action: "seek", positionSeconds: 95, trackId: "tidewater" } // sent once, on release

// Playlist
{ action: "save-playlist", title: "Deep focus", trackIds: ["graphite", "slow-current"], removed: ["field-notes"] }
{ action: "open-in-provider" }
{ action: "dismiss" }

Keyboard seeks (arrow keys on the progress slider) are sent 0.6 s after the last key press.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_music", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored playlist result back as result. A saved playlist shows exactly the saved tracks, in order, read-only, with "Saved to your library" in the footer, and never calls onResult again. A dismissed playlist reads "Dismissed. Nothing was saved."

<MusicPlayer {...part.input} result={part.state === "output-available" ? part.output : undefined} />

Now-playing never locks, so result is ignored there. Pass a fresh nowPlaying to show the provider's latest state.

SchemaCopy Anchor Link

MusicTrack

Host props: status (streaming, ready, submitting, saved, dismissed), onResult, result and className.

SourceCopy Anchor Link