koios/docs/tools/orpheus.md

# Orpheus

> Robert's Kawai piano — play music, manage the song library, review practice sessions.

- **MCP server name:** `orpheus`
- **Prompt snippet:** [prompts/tools/orpheus.md](../../prompts/tools/orpheus.md)

## What It Is

Orpheus is the MCP for Robert's Kawai piano. It turns the piano into something an assistant can actually *play* — converting ABC notation to MIDI, queuing pieces for playback, managing a song library, and capturing practice sessions for review. Named for the Greek musician whose lyre could move stones; the Kawai is the modern equivalent.

Music isn't something David just talks about — it's something he can bring to life. Orpheus is the difference between recommending a piece and demonstrating it.

## MCP Tools

### Playback

| Tool | Purpose |
|---|---|
| `play_abc` | Play music from ABC notation. Converts to MIDI and queues for playback. **The easiest way to play a piece.** Args: `title`, `abc`, optional `tempo_bpm`. |
| `play_midi` | Queue raw MIDI events. Each event is a dict with `type`, `time`, `note`, `velocity`, `channel`, `control`, `value`. Args: `title`, `midi_data`, `tempo_bpm` (default 72). |
| `play_song` | Queue a library song by ID. Args: `song_id`. |
| `stop_playback` | Stop whatever's currently playing. |
| `playback_status` | Returns `{is_playing, is_paused, title, playback_id, progress}`. |

### Library

| Tool | Purpose |
|---|---|
| `export_midi` | Convert ABC to MIDI and save to the song library for future replay via `play_song`. Args: `title`, `abc`, optional `tempo_bpm`, `save_to_library=True`. |
| `list_songs` | List all songs in the library — id, title, composer, genre, duration. |

### Sessions (review practice history)

| Tool | Purpose |
|---|---|
| `list_sessions` | List recent practice sessions — id, date, duration, note count. Args: `limit` (default 20). |
| `get_session` | Full session details including all raw MIDI events. Args: `session_id`. |

### System

| Tool | Purpose |
|---|---|
| `get_system_info` | Returns hostname, IP, instrument, uptime, DB path, version. |

## Canonical Workflows

### Play a piece from ABC notation

```
play_abc(
    title="Gymnopédie No. 1",
    abc="X:1\nT:Gymnopédie No. 1\nC:Erik Satie\nM:3/4\nL:1/4\nK:Dmaj\n...",
    tempo_bpm=60
)
```

The simplest path — composer + piece + ABC notation → live piano playback.

### Save a piece to the library for later

```
export_midi(
    title="Gymnopédie No. 1",
    abc="...",
    tempo_bpm=60,
    save_to_library=True
)
# returns a song_id

# Later:
play_song(song_id="...")
```

Useful when David has converged on the right interpretation of a piece and wants it persistent rather than re-composed each time.

### Review a practice session

```
list_sessions(limit=5)
# returns recent sessions with date and note counts

get_session(session_id="...")
# returns full MIDI event detail — every note played, when, how hard
```

This is the diagnostic side — when Robert practiced something and wants to see what he actually played vs. what he intended.

## Who Uses Orpheus

- **David** — primary user. Music is David's domain, so the piano is most often his to play. Orpheus is how David can demonstrate rather than just describe.

Other agents may use Orpheus too — it just happens that David is the first one with it. If another agent's work has a legitimate reason to play something (a piece tied to a memory, a song for a mood), Orpheus is available.

## What It's Good For

- Demonstrating a piece David is recommending ("here, let me play it for you")
- Building a library of pieces Robert is working on or wants to revisit
- Reviewing practice sessions for analysis — what was played, tempo discipline, note accuracy
- Setting a mood — a piece in the background while doing something else
- Exploring music interactively — try a piece, adjust tempo, try variations

## What It's Not Good For

- Music *recommendations* alone — those don't need Orpheus; conversation is enough. Orpheus is for when David wants to *play* the recommendation, not just describe it.
- Recording — Orpheus plays back; the piano captures sessions separately
- Genre or artist analysis — that's interpretation work belonging in David's Neo4j `Music`, `Artist`, `Playlist` nodes
- Songs not in ABC notation or MIDI form. To play something obscure, you need the notation first.

## Known Gotchas

- **ABC notation is the path of least resistance.** Most pieces in the public domain (classical, traditional folk) have ABC available. For other pieces, you may need to transcribe or find a MIDI source first.
- **Tempo matters for piece identity.** Satie at 60 bpm and Satie at 90 bpm are different musical experiences. Pick deliberately and document the choice in the song-library entry if saving.
- **Playback is queued, not instant.** `playback_status` tells you what's actually playing. Don't assume a successful queue call means the piece is currently audible.
- **`stop_playback` is the kill switch.** Use it when something is wrong (wrong piece, wrong tempo, distraction) rather than waiting for it to finish.
- **`get_session` returns all raw MIDI events.** For long sessions this is a lot of data. If you just want overview metrics (date, duration, count), `list_sessions` is enough.
- **The piano is a physical object in Robert's space.** Playing something loud at 11pm has real consequences. Confirm before queueing a piece if context suggests it might be disruptive.