/listen

name: listen
description: Opens a track's Suno takes in the browser or in iTerm2 panes beside the session, or plays takes and local audio in the terminal. Use when the user wants to hear a take, compare takes, audition a generation, or says "play it" or "let me hear it". Opening the song page is the default and is free; playing a new Suno take in the terminal uses one download credit.
argument-hint: <album-name> <track> [take N | all] [--browser [<app>] | --iterm2 | --terminal] [--from m:ss] [--stage original|polished|mastered]
model: sonnet
effort: medium
allowed-tools:
  - Read
  - Edit
  - Bash
  - bitwize-music-mcp
  - mcp__suno__*

Your Task

**Input**: $ARGUMENTS

Let the user hear a track: open its Suno takes in the browser or in iTerm2 panes beside this session, or play takes and local audio through the computer's speakers. Then ask which take they want to keep.

You never choose a take. Audio never passes through you — you start a player and report what is playing.

---

Listen Skill

For Suno takes the browser is the default, because listening on the song page is free. Two other ways are there for the asking, for one run or as the user's standing choice in `generation.listen_mode`:

• **iTerm2 panes** (`--iterm2`, or `listen_mode: iterm2_browser`) — Suno's compact player for each take, in panes beside this session, with the track's lyrics in a pane under them, so the user never leaves the terminal window. Free, like the browser. Needs macOS, iTerm2 3.6 or later and iTerm2's Browser Plugin.
• **Terminal** (`--terminal`, or `listen_mode: terminal`) — the take plays through the speakers from here, for one download credit.

Both fall back to the browser whenever they cannot be used. Local files always play in the terminal.

What Listening Costs

Suno has no free audio feed for a terminal player, so playing a take here means downloading it.

| Way to listen | Cost | |---------------|------| | Song page in the browser | Free, unlimited | | Compact player in an iTerm2 pane | Free, unlimited | | A take in the terminal, first time | 1 Suno download credit | | The same take again | Free (it is cached) | | A file already on disk (imported, polished, mastered) | Free | | Comparing files already on disk, passage by passage | Free |

The take that is kept needs that download credit anyway — its WAV import is then free. Only rejected takes played in the terminal cost extra. Details: `${CLAUDE_PLUGIN_ROOT}/reference/suno/mcp-api-mapping.md`.

Step 1: Work Out What to Play

Expected format: `<album-name> <track> [take N | all] [--browser [<app>] | --iterm2 | --terminal] [--from m:ss] [--stage original|polished|mastered]`

Call `get_listen_plan(album_slug, track_slug)`.

**Target**

• `take N` or `all` → those rows of `takes`.
• `--stage X` → `local[X]`. If it is null, say there is no such file yet and stop.
• Neither → `default`:
• `kind: "takes"` → those rows (the takes awaiting a decision).
• `kind: "local"` → that file.
• `kind: "none"` → "Nothing to play yet — generate the track first with `/bitwize-music:generate`." Stop.

**How**

• `--browser`, `--iterm2` or `--terminal` wins; otherwise use `mode` from the plan (`browser` unless the user's config says `iterm2_browser` or `terminal`).
• `--browser <app>` also names the web browser for this run: an app name (`Safari`, `"Google Chrome"`) or a path to one. Without it the takes open in `generation.listen_browser`, else the system's default.
• Local files always play in the terminal.
• A take whose `clip_id` is null is a share link from before MCP generation: it can be opened in the browser or in an iTerm2 pane, never played in the terminal.
• Terminal mode with `player: null` → say no audio player is installed (`brew install mpv`, or see the reference doc), then use the browser for takes.
• iTerm2 mode needs no check of your own: when the panes cannot be used, `open_song_page` opens the browser instead and says why.

Step 2: Browser Mode and iTerm2 Mode

Call `open_song_page(urls)` with the chosen takes' `url`s (at most four), in take order. For `--browser <app>`, add `browser: "<app>"`. For iTerm2 mode add `where="iterm2_browser"`, `album_slug` and `track_slug`: the track's Lyrics Box then opens in one more pane under the takes. Leave the track out when the takes are instrumental versions.

The answer's `where` says where the takes went:

• `browser` → say which takes are open in the browser. If the answer has a `note`, the browser named couldn't be opened and the default was used: pass the note on.
• `iterm2_browser` → each take is open as a compact player in a pane to the right of this session, the first take on top. Say which take is where, and that each needs one click on its play button — a browser never starts sound by itself:

  Both takes are open beside this session: take 1 on top, take 2 under it,
  and the lyrics below them. Click play on each one.

`lyrics_pane: true` → the lyrics pane is open. It is plain text from the track file, not timed to the music, so never say it follows the song. The user scrolls it with the mouse wheel or the arrow keys, and `q` closes that pane alone. `lyrics_pane: false` → say why in a few words, from `lyrics_note` (for example, the Lyrics Box has no lyrics yet). An instrumental track needs no mention.

• `note` → the panes could not be used, so the takes went to the browser. Pass the reason on; it names the fix when there is one (for example, installing iTerm2's Browser Plugin).
• `failed` → no browser could be launched here; print those links for the user to open.

Opening panes again replaces the ones already open. All of this costs nothing and needs no Suno server. Go to Step 7.

Step 3: Terminal Mode — Local File or Cached Take

A local file, or a take with `cached: true`, plays at once: `play_audio(path, start_s)` with the file path or the take's `cache_path`. Go to Step 5.

Step 4: Terminal Mode — Take Not Cached Yet

1. Run § Preflight in `${CLAUDE