From 4d0268aa0b68f79ad4ea213b51616cb3980bb18f Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Wed, 25 Mar 2026 16:56:52 +0000
Subject: [PATCH 01/29] delete docs avoid interupt

---
 docs/OPENCLAW_INSTALL.md           | 144 -------------------------
 docs/tinydew-for-openclaw.SKILL.md | 162 -----------------------------
 2 files changed, 306 deletions(-)
 delete mode 100644 docs/OPENCLAW_INSTALL.md
 delete mode 100644 docs/tinydew-for-openclaw.SKILL.md

diff --git a/docs/OPENCLAW_INSTALL.md b/docs/OPENCLAW_INSTALL.md
deleted file mode 100644
index 116c0e6..0000000
--- a/docs/OPENCLAW_INSTALL.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# Tinydew Installation (OpenClaw one-doc guide)
-
-This document is a single, copy-paste setup guide for getting **Tinydew** running in an OpenClaw environment.
-
----
-
-## 1) Prerequisites
-
-Install required tools:
-
-- `git`
-- `rustup` (Rust toolchain)
-- `cargo`
-
-Check:
-
-```bash
-git --version
-rustc --version
-cargo --version
-```
-
-If Rust is missing:
-
-```bash
-curl https://sh.rustup.rs -sSf | sh
-source "$HOME/.cargo/env"
-```
-
----
-
-## 2) Clone Tinydew
-
-```bash
-git clone https://github.com/rustq/tinydew.git
-cd tinydew
-```
-
-(If already cloned, just `cd tinydew`.)
-
----
-
-## 3) Build
-
-Standard build:
-
-```bash
-cargo build --release
-```
-
-Interactive build (TUI):
-
-```bash
-cargo build --release --features interactive
-```
-
----
-
-## 4) Run Modes
-
-### A) MCP mode (for OpenClaw automation)
-
-Run without interactive feature:
-
-```bash
-cargo run --quiet
-```
-
-- In non-TTY context, Tinydew falls back to MCP stdio server.
-- OpenClaw can send JSON requests to stdin (`startSession`, `getState`, `command`, etc.).
-- Recommended chat behavior: for every user message during game sessions, call `print` and include the latest Tinydew UI snapshot in the assistant reply.
-
-### B) Interactive mode (guest/player keyboard control)
-
-```bash
-cargo run --quiet --features interactive
-```
-
-Controls (interactive):
-
-- Guest mode hint line: `move: ↑↓←→ | greet: [SPACE]`
-- Player mode hint line: `move: ↑↓←→ | clear: [C] | plant: [P] | water: [W] | harvest: [H] | trade: [T]`
-- Esc: quit
-
----
-
-## 5) Save File Location
-
-Tinydew save path:
-
-```text
-~/.local/share/tinydew/savegame.json
-```
-
-Reset save (fresh Day 1):
-
-```bash
-rm -f ~/.local/share/tinydew/savegame.json
-```
-
----
-
-## 6) OpenClaw usage note
-
-For OpenClaw automation, prefer MCP mode and send tool-style commands:
-
-- `startSession`
-- `getState`
-- `command` / `commandBatch`
-- `print` for text UI snapshots
-
-Common MCP command strings:
-- `move:up|down|left|right`
-- `clear`, `plant:seed`, `water`, `harvest`
-  - Mature crop tiles are non-walkable (blocked until harvested)
-  - `plant:seed` consumes one generic seed and rolls a random crop type
-- `fish` or `fish:up|down|left|right`
-- `buy:<item>[:<qty>]`, `sell:<item>[:<qty>]`, `print`, `save`, `load`
-- Sell examples: `sell:mushroom:1`, `sell:carrot:2`, `sell:fish:1`
-  - Mushroom (🍄) sell value: $25 each
-- Spec inventory convention for seeds: show as `🫙 xN`
-
-This gives deterministic, scriptable game control.
-
-### Suggested response format for chat
-
-When replying in game flow:
-1. One short status line (what happened).
-2. A fenced code block with the latest `print` snapshot UI.
-3. Optional one-line next prompt (e.g., "move where?").
-
-Example:
-
-```text
-Done — moved to Square.
-
-tinydew day 3 ☀️ 09:10
-
-<map rows>
-
-Money: 💰 $500
-
-> Entered Square.
-```
diff --git a/docs/tinydew-for-openclaw.SKILL.md b/docs/tinydew-for-openclaw.SKILL.md
deleted file mode 100644
index a332261..0000000
--- a/docs/tinydew-for-openclaw.SKILL.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# OpenClaw Skill Draft: Play Tinydew in Chat
-
-## Installation Reference
-
-Use this installation guide:
-- https://raw.githubusercontent.com/rustq/tinydew/refs/heads/dev/docs/OPENCLAW_INSTALL.md
-
-## Goal
-
-Make Tinydew feel **live and interactive** in chat.
-
-When user talks about Tinydew, OpenClaw should:
-1. Execute game commands through Tinydew MCP.
-2. Show a fresh game UI snapshot in the reply.
-3. Narrate key moments in a fun, human style.
-
----
-
-## Core Interaction Model
-
-### 1) Always-show UI loop
-For every Tinydew-related user message:
-1. Ensure session is active (`startSession` if needed).
-2. Interpret intent (move, farm, fish, inspect, etc.).
-3. Execute one or more commands (`command` / `commandBatch`).
-4. Run `command: print`.
-5. Reply with:
-   - brief action summary,
-   - current UI snapshot (`snapshot_text`),
-   - bottom status/message from game UI,
-   - next suggested actions.
-
-**Rule:** If user says anything about Tinydew, include the game UI in the message whenever possible.
-
----
-
-### 2) Planting & seed model (required)
-Seed/shop model for this spec:
-- Shop sells a single generic seed item: `seed`
-- Inventory should show seed count as `🫙 xN` (no per-crop seed split)
-- Planting consumes one `seed`
-- After planting, crop type is randomized to one of the crop types (Carrot / Strawberry / Cauliflower / Flower)
-
-When planting succeeds, include growth timing:
-- Rolled crop name (the randomized result)
-- Days to mature
-- Expected ready day (current day + growth days)
-- Note: mature crop tiles are non-walkable (blocked until harvested)
-
-Example style:
-- "🌱 Seed planted! It rolled into Carrot. Needs 4 watered days to mature (ready around Day 5)."
-
-If planting fails (no seed / invalid tile), explain clearly.
-
----
-
-### 3) Surprise narration moments (required)
-Use short celebratory lines when notable events happen.
-
-#### Flowers / mushrooms found
-Add a surprise tone, e.g.:
-- "✨ Surprise find! A wild mushroom 🍄 popped up nearby."
-- "🌸 Ooh—flowers in bloom. Nice little bonus spot."
-
-#### Fish caught in river region
-Add surprise + reward tone, e.g.:
-- "🎣 Splash! You hooked a fish from the river!"
-- "🐟 Nice catch—river luck is on your side."
-
-#### Wonder view discovered
-When map/location/message implies scenic moment, react with delight:
-- "🌄 Whoa, that view is gorgeous—tiny vacation energy."
-- "✨ Found a wonder view. Worth pausing for a second."
-
-Keep surprise lines to 1 sentence so chat stays fast.
-
----
-
-### 4) Bottom text forwarding (required)
-Always pass along the game’s bottom message/status text from the latest `print` snapshot.
-
-Format recommendation:
-- `Game says: <bottom_text>`
-
-If multiple important system messages occur, summarize them in bullets.
-
----
-
-## Reply Format (recommended)
-
-1. **Action result** (1-2 lines)
-2. **Surprise/celebration line** (only if event triggered)
-3. **Game UI snapshot** (code block)
-   - keep MCP snapshot style (no location/player/guest position lines)
-   - top line should be `tinydew day <day> <weather_icon> <time>`
-   - money line should appear as `Money: 💰 $<amount>`
-   - omit inventory section header; show item lines only when non-empty
-4. **Bottom text** (`Game says: ...`)
-5. **What next?** (2-4 concise options)
-
-Example skeleton:
-
-```text
-Moved east into SouthRiver.
-🎣 Splash! You hooked a fish from the river!
-
-<snapshot_text>
-
-Game says: You caught a Sardine!
-Next: fish | move:left | sell:mushroom:1 | print
-```
-
----
-
-## MCP Methods to Use
-
-- `startSession`
-- `getState`
-- `getMap`
-- `command`
-- `commandBatch`
-
-Use `command: print` after actions to ensure user sees updated UI each turn.
-
----
-
-## Command Mapping Hints
-
-Natural language → Tinydew command examples:
-- "go right" → `move:right`
-- "plant" / "plant seed" → `plant:seed` (random crop outcome)
-- "water" → `water`
-- "harvest" → `harvest`
-- "fish" → `fish` (or directional `fish:up|down|left|right`)
-- "sell mushroom" → `sell:mushroom` (each 🍄 sells for $25)
-- "show map" / "where am I" → `print`
-
-If ambiguous, take safest single step and show UI immediately.
-
----
-
-## UX Rules
-
-- Keep narration concise, not verbose.
-- Prefer action + visible UI over long explanation.
-- Do not hide failures: show exact reason from game.
-- Preserve momentum: always offer next 2-4 commands.
-
----
-
-## Suggested Skill Trigger Description (for SKILL.md frontmatter)
-
-"Play Tinydew through MCP in chat with live UI snapshots. Use when user asks to play Tinydew, move, farm, fish, harvest, inspect map/state, or continue a Tinydew session. Always execute commands, show updated game UI (`print` snapshot), surface bottom status text, announce planting maturity timing, and add short surprise narration for flowers/mushrooms, fish catches, and scenic wonder views."
-
----
-
-## Notes
-
-This is a draft spec. Final skill can later split into:
-- `SKILL.md` (core workflow)
-- `references/reply-templates.md` (message templates)
-- `references/event-triggers.md` (surprise trigger rules)

From 447d7401e8dd12be0e4405b8a51c2c3336f4096c Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Wed, 25 Mar 2026 17:18:44 +0000
Subject: [PATCH 02/29] Add north square piano spec and update related specs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 agents/entities-and-movement.spec.md |  2 +-
 agents/north-square-piano.spec.md    | 34 ++++++++++++++++++++++++++++
 agents/spawns.spec.md                |  1 +
 agents/square-region.spec.md         |  3 ++-
 4 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 agents/north-square-piano.spec.md

diff --git a/agents/entities-and-movement.spec.md b/agents/entities-and-movement.spec.md
index d42eb00..9abf1ac 100644
--- a/agents/entities-and-movement.spec.md
+++ b/agents/entities-and-movement.spec.md
@@ -17,7 +17,7 @@ Implemented.
 ## Guest Control
 - Interactive mode enables guest control path.
 - Space triggers guest greeting text.
-- Guest obeys non-walkable tiles (including Fountain and Wonder).
+- Guest obeys non-walkable tiles (including Fountain, Piano, and Wonder).
 
 ## Transitions
 - Farm <-> EastPath (return from EastPath to Farm spawns at `(6,5)`)
diff --git a/agents/north-square-piano.spec.md b/agents/north-square-piano.spec.md
new file mode 100644
index 0000000..00a8c31
--- /dev/null
+++ b/agents/north-square-piano.spec.md
@@ -0,0 +1,34 @@
+# North Square Piano Spec
+
+## Status
+Not implemented.
+
+## Context
+The Square region (the northernmost plaza) receives a permanent decorative piano object. The piano is a non-walkable fixture placed at a specific tile.
+
+## Placement
+- Piano tile (`🎹`) placed at Square `(6,2)`.
+- Replaces the default Grass tile at that position.
+- Piano is always present on the map (not seasonal or spawned).
+- The tile sits on row 2 (the fountain row), two tiles right of the fountain (`⛲` at `(4,2)`).
+
+## Map Reference (Square, row 2 after placement)
+```
+🌳 🌿 🌿 🌿 ⛲ 🌿 🎹 🌿 🌳
+```
+
+## Walkability
+- Piano is non-walkable for both player and guest.
+- Movement, pathfinding, and collision must respect the piano as a blocking tile.
+- Random spawn logic must treat `(6,2)` as a protected tile (no flower/mushroom spawn on it).
+
+## Interaction
+- Attempting to walk onto the piano tile shows:
+  `A beautiful old piano. It hums quietly in the square.`
+
+## Implementation Notes
+- Requires new `TileType::Piano` variant in the tile enum.
+- `is_walkable()` must return `false` for `TileType::Piano`.
+- `emoji()` must return `"🎹"` for `TileType::Piano`.
+- `create_square_map()` sets `TileType::Piano` at `square_map[2][6]`.
+- Protected tile list in spawn logic must include Piano (or the `(6,2)` coordinate in Square).
diff --git a/agents/spawns.spec.md b/agents/spawns.spec.md
index 29b6deb..b12b624 100644
--- a/agents/spawns.spec.md
+++ b/agents/spawns.spec.md
@@ -13,4 +13,5 @@ Consolidates random crop/flower/mushroom-style world spawning rules.
 - Per region, nightly random spawn executes only when that region currently has no flower/mushroom present (max one active flower-or-mushroom blocker per region).
 - Mushroom visual/emoji in specs is 🍄.
 - Protected tiles (house/wakeup-sensitive and similar guard tiles) are excluded from random placement.
+- Piano tile at Square `(6,2)` is a protected tile excluded from random spawn (see `north-square-piano.spec.md`).
 - Square supports decorative spawn participation while preserving movement/collision constraints.
diff --git a/agents/square-region.spec.md b/agents/square-region.spec.md
index 4d9aace..a681f77 100644
--- a/agents/square-region.spec.md
+++ b/agents/square-region.spec.md
@@ -6,7 +6,8 @@ Implemented.
 ## Map
 - Dimensions: 9 x 5.
 - Boundary trees block edges.
-- Center fountain (`⛲`) is non-walkable.
+- Center fountain (`⛲`) at `(4,2)` is non-walkable.
+- Piano (`🎹`) at `(6,2)` is a permanent non-walkable fixture (see `north-square-piano.spec.md`).
 - Bottom center gate connects to EastPath top-center gate.
 
 ## Behavior

From 443cde31edb5c2a970a81d0dc11244a567ec91df Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Wed, 25 Mar 2026 17:29:25 +0000
Subject: [PATCH 03/29] Add Piano tile to north square at (6,2)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 agents/north-square-piano.spec.md | 2 +-
 src/mcp/session.rs                | 2 ++
 src/mcp/state_manager.rs          | 2 ++
 src/state.rs                      | 7 ++++++-
 src/world.rs                      | 5 ++++-
 5 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/agents/north-square-piano.spec.md b/agents/north-square-piano.spec.md
index 00a8c31..a7b783b 100644
--- a/agents/north-square-piano.spec.md
+++ b/agents/north-square-piano.spec.md
@@ -1,7 +1,7 @@
 # North Square Piano Spec
 
 ## Status
-Not implemented.
+Implemented.
 
 ## Context
 The Square region (the northernmost plaza) receives a permanent decorative piano object. The piano is a non-walkable fixture placed at a specific tile.
diff --git a/src/mcp/session.rs b/src/mcp/session.rs
index 0b229a7..0ed9d63 100644
--- a/src/mcp/session.rs
+++ b/src/mcp/session.rs
@@ -142,6 +142,7 @@ impl Session {
             TileType::River => "R".to_string(),
             TileType::RiverBubble => "B".to_string(),
             TileType::Wonder => "W".to_string(),
+            TileType::Piano => "N".to_string(),
         }
     }
 
@@ -172,6 +173,7 @@ impl Session {
             TileType::River => "River".to_string(),
             TileType::RiverBubble => "RiverBubble".to_string(),
             TileType::Wonder => "Wonder".to_string(),
+            TileType::Piano => "Piano".to_string(),
         }
     }
 
diff --git a/src/mcp/state_manager.rs b/src/mcp/state_manager.rs
index b7736bf..e083830 100644
--- a/src/mcp/state_manager.rs
+++ b/src/mcp/state_manager.rs
@@ -145,6 +145,7 @@ impl GameStateManager {
             TileType::River => "R".to_string(),
             TileType::RiverBubble => "B".to_string(),
             TileType::Wonder => "W".to_string(),
+            TileType::Piano => "N".to_string(),
         }
     }
 
@@ -176,6 +177,7 @@ impl GameStateManager {
             TileType::River => "River".to_string(),
             TileType::RiverBubble => "RiverBubble".to_string(),
             TileType::Wonder => "Wonder".to_string(),
+            TileType::Piano => "Piano".to_string(),
         }
     }
 
diff --git a/src/state.rs b/src/state.rs
index f7d7461..629f998 100644
--- a/src/state.rs
+++ b/src/state.rs
@@ -651,6 +651,9 @@ impl GameState {
                     self.message =
                         String::from("Cannot move there. Try walking around to find a path.");
                 }
+            } else if matches!(target_tile, Some(TileType::Piano)) {
+                self.message =
+                    String::from("A beautiful old piano. It hums quietly in the square.");
             } else if matches!(target_tile, Some(TileType::Mushroom)) {
                 self.message =
                     String::from("Cannot move there. Mature crop ahead — try harvest.");
@@ -2670,12 +2673,14 @@ mod tests {
         let can_up = state.can_move_to(4, 1);
         let can_down = state.can_move_to(4, 3);
         let can_left = state.can_move_to(3, 2);
-        let can_right = state.can_move_to(6, 2);
+        let can_right = state.can_move_to(5, 2);
+        let can_piano = state.can_move_to(6, 2);
 
         assert!(can_up, "Should be able to move up (grass)");
         assert!(can_down, "Should be able to move down (grass)");
         assert!(can_left, "Should be able to move left (grass)");
         assert!(can_right, "Should be able to move right (grass)");
+        assert!(!can_piano, "Piano at (6,2) should block movement");
     }
 
     #[test]
diff --git a/src/world.rs b/src/world.rs
index b924b93..b9fcf1d 100644
--- a/src/world.rs
+++ b/src/world.rs
@@ -40,6 +40,7 @@ pub enum TileType {
     River,
     RiverBubble,
     Wonder,
+    Piano,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -211,6 +212,7 @@ impl TileType {
             TileType::River => false,
             TileType::RiverBubble => false,
             TileType::Wonder => false,
+            TileType::Piano => false,
             TileType::Grass
             | TileType::Soil
             | TileType::PathEast
@@ -259,6 +261,7 @@ impl TileType {
             TileType::River => "🌊",
             TileType::RiverBubble => "🫧",
             TileType::Wonder => "🦋",
+            TileType::Piano => "🎹",
         }
     }
 }
@@ -456,7 +459,7 @@ pub fn create_square_map() -> Map {
             TileType::Grass,
             TileType::Fountain,
             TileType::Grass,
-            TileType::Grass,
+            TileType::Piano,
             TileType::Grass,
             TileType::Boundary,
         ],

From 7f379f27bd23eb1c7ec12ff054921302d6285442 Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Wed, 25 Mar 2026 17:54:04 +0000
Subject: [PATCH 04/29] Add guest piano play spec and update related specs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 agents/entities-and-movement.spec.md |  1 +
 agents/guest-piano-play.spec.md      | 95 ++++++++++++++++++++++++++++
 agents/north-square-piano.spec.md    |  1 +
 agents/square-region.spec.md         |  1 +
 4 files changed, 98 insertions(+)
 create mode 100644 agents/guest-piano-play.spec.md

diff --git a/agents/entities-and-movement.spec.md b/agents/entities-and-movement.spec.md
index 9abf1ac..8b960d0 100644
--- a/agents/entities-and-movement.spec.md
+++ b/agents/entities-and-movement.spec.md
@@ -18,6 +18,7 @@ Implemented.
 - Interactive mode enables guest control path.
 - Space triggers guest greeting text.
 - Guest obeys non-walkable tiles (including Fountain, Piano, and Wonder).
+- Guest can play the piano when standing at Square `(6,3)` via A/S/D/F/G/H/J/K keys (see `guest-piano-play.spec.md`).
 
 ## Transitions
 - Farm <-> EastPath (return from EastPath to Farm spawns at `(6,5)`)
diff --git a/agents/guest-piano-play.spec.md b/agents/guest-piano-play.spec.md
new file mode 100644
index 0000000..2a5cb11
--- /dev/null
+++ b/agents/guest-piano-play.spec.md
@@ -0,0 +1,95 @@
+# Guest Piano Play Spec
+
+## Status
+Not implemented.
+
+## Context
+The guest girl can play the piano placed at Square `(6,2)`. When the guest stands directly below the piano at `(6,3)`, keyboard keys activate piano notes with audible sound output. Only the guest has this ability — the player character cannot play the piano.
+
+## Activation
+- Guest must be enabled (`guest_enabled == true`).
+- Guest must be in Square region (`guest_location == Location::Square`).
+- Guest must be at tile `(6,3)` — directly south of the piano at `(6,2)`.
+- When all conditions are met, the piano key bindings become active in the interactive input loop.
+- Piano mode is passive — no explicit enter/exit action. Keys are simply available while standing at `(6,3)`.
+
+## Key Mapping
+| Key | Note Name | Display |
+|-----|-----------|---------|
+| A   | Do        | Do      |
+| S   | Re        | Re      |
+| D   | Mi        | Mi      |
+| F   | Fa        | Fa      |
+| G   | So        | So      |
+| H   | La        | La      |
+| J   | Si        | Si      |
+| K   | DO#       | DO#     |
+
+- Keys are case-insensitive (`a`/`A` both trigger Do).
+- Each key press plays the corresponding note sound and updates the bottom message.
+
+## Message Display
+- On key press, the bottom message line shows the note name:
+  - Example: pressing `D` shows `🎹 Mi`
+- The message updates on each key press, replacing the previous note display.
+- If the guest moves away from `(6,3)`, the keys revert to their normal behavior (farm action rejection messages).
+
+## Sound Playback
+
+### Sample Source
+- Piano samples come from the **Salamander Grand Piano v3** by Alexander Holm (CC-BY license).
+- Sample format: FLAC files, naming convention `[Note][Octave]v[Velocity].flac` (e.g., `C4v8.flac`, `A4v8.flac`).
+- Only 5 source samples are needed (the direct-hit notes); the remaining notes are derived via pitch-shifting:
+  - **C4v8.flac** — used for Do (C4), Re (D4, +2 semitones), Mi (E4, +4 semitones)
+  - **F#4v8.flac** — used for Fa (F4, −1 semitone), So (G4, +1 semitone)
+  - **A4v8.flac** — used for La (A4, direct)
+  - **C5v8.flac** — used for Si (B4, −1 semitone), DO# (C5, direct)
+- Velocity layer v8 (medium) is used for all notes — a single dynamic level is sufficient.
+- Samples are stored in a `Samples/` directory at the project root.
+
+### Note-to-Pitch Mapping
+| Note | Display | Source Sample | Semitone Offset | Speed Ratio (`2^(offset/12)`) |
+|------|---------|---------------|-----------------|-------------------------------|
+| Do   | Do      | C4v8.flac     | 0               | 1.0                           |
+| Re   | Re      | C4v8.flac     | +2              | 1.1225                        |
+| Mi   | Mi      | C4v8.flac     | +4              | 1.2599                        |
+| Fa   | Fa      | F#4v8.flac    | −1              | 0.9439                        |
+| So   | So      | F#4v8.flac    | +1              | 1.0595                        |
+| La   | La      | A4v8.flac     | 0               | 1.0                           |
+| Si   | Si      | C5v8.flac     | −1              | 0.9439                        |
+| DO#  | DO#     | C5v8.flac     | 0               | 1.0                           |
+
+### Playback Engine
+- Use the `rodio` crate for audio decoding and playback (already cross-platform: ALSA/PulseAudio on Linux, CoreAudio on macOS, WASAPI on Windows).
+- Playback pipeline per note:
+  1. Read source sample bytes from disk (or from a pre-loaded in-memory cache).
+  2. Wrap bytes in a `std::io::Cursor`, decode with `rodio::Decoder::new()`.
+  3. Apply pitch shift via `.speed(speed_ratio)` using the semitone formula `2.0_f32.powf(offset / 12.0)`.
+  4. Apply a short fade-in (`.fade_in(Duration::from_millis(8))`) to prevent click artifacts.
+  5. Append to a `rodio::Sink` for non-blocking playback.
+- **Polyphony**: Maintain up to 4 concurrent voice sinks in a `VecDeque<Sink>`. When a 5th note triggers, stop the oldest sink. Prune empty sinks on each key press.
+- Each key press triggers a single note playback (non-blocking, fire-and-forget).
+- If audio initialization fails (e.g., no audio device), the game continues silently — sound is best-effort, never a hard failure.
+
+## Player Restriction
+- When the player (non-guest) stands at `(6,3)`, the A/S/D/F/G/H/J/K keys do **not** trigger piano notes.
+- The piano interaction message from `north-square-piano.spec.md` still applies when walking into `(6,2)`.
+
+## Implementation Notes
+- **Input handling** (`src/main.rs`): Inside the guest-enabled branch of the interactive key loop, check if `guest_location == Square && guest_x == 6 && guest_y == 3`. If true, intercept `KeyCode::Char('a'..'k')` for the 8 mapped keys before falling through to the default "Guest can only walk around." handler.
+- **State** (`src/state.rs`): Add a method `guest_play_piano(&mut self, note: &str)` that sets `self.message` to the note display string (e.g., `"🎹 Do"`). No persistent piano state is needed — each press is stateless.
+- **Audio module**: Create `src/audio.rs` that loads Salamander FLAC samples from `Samples/` and plays them via `rodio`. Expose a function like `play_note(note: PianoNote)` that decodes, pitch-shifts, and appends to a sink on a background thread. Guard the entire module behind the `interactive` feature flag so MCP/headless mode is unaffected.
+- **Cargo.toml**: Add `rodio` under `[dependencies]` gated by the `interactive` feature:
+  ```toml
+  rodio = { version = "0.21", optional = true }
+  ```
+  Update the `interactive` feature to include it:
+  ```toml
+  interactive = ["rodio"]
+  ```
+- **No MCP impact**: Piano playback is interactive-only. The MCP command interface has no piano command and requires no changes.
+
+## Related Specs
+- `north-square-piano.spec.md` — Piano tile placement and walkability.
+- `entities-and-movement.spec.md` — Guest movement and non-walkable tile rules.
+- `square-region.spec.md` — Square map layout.
diff --git a/agents/north-square-piano.spec.md b/agents/north-square-piano.spec.md
index a7b783b..6477da7 100644
--- a/agents/north-square-piano.spec.md
+++ b/agents/north-square-piano.spec.md
@@ -25,6 +25,7 @@ The Square region (the northernmost plaza) receives a permanent decorative piano
 ## Interaction
 - Attempting to walk onto the piano tile shows:
   `A beautiful old piano. It hums quietly in the square.`
+- Guest can play the piano by standing at `(6,3)` directly below the piano tile (see `guest-piano-play.spec.md`).
 
 ## Implementation Notes
 - Requires new `TileType::Piano` variant in the tile enum.
diff --git a/agents/square-region.spec.md b/agents/square-region.spec.md
index a681f77..bb10b90 100644
--- a/agents/square-region.spec.md
+++ b/agents/square-region.spec.md
@@ -13,6 +13,7 @@ Implemented.
 ## Behavior
 - Supports player/guest movement with region-aware collision.
 - Square forbids farm actions like clear/plant.
+- Tile `(6,3)` acts as the piano play zone for the guest (see `guest-piano-play.spec.md`).
 - Transition rules connect EastPath <-> Square for both player and guest.
 - Entering Square from EastPath spawns at `(4,3)`.
 - Returning from Square to EastPath spawns at `(5,1)`.

From cc5350adc6c600c57e74c554fe82d54fa38ee709 Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Wed, 25 Mar 2026 18:32:08 +0000
Subject: [PATCH 05/29] chore: make AudioManager thread-safe with Arc<Mutex<_>>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Wrap Mixer in Mutex for proper synchronization
- Wrap AudioManager in Arc<Mutex<_>> for safe multi-threaded access
- This fixes potential race conditions when play_note is called

Co-authored-by: 🦞 <🦞@ubuntu>
---
 Cargo.lock                      | 756 +++++++++++++++++++++++++++++++-
 Cargo.toml                      |   6 +-
 agents/guest-piano-play.spec.md |   4 +-
 src/main.rs                     |  26 +-
 src/mcp/command.rs              |  60 +--
 src/mcp/handler.rs              |   3 -
 src/mcp/state_manager.rs        |   3 +-
 src/piano.rs                    | 168 +++++++
 src/state.rs                    |  43 +-
 9 files changed, 1009 insertions(+), 60 deletions(-)
 create mode 100644 src/piano.rs

diff --git a/Cargo.lock b/Cargo.lock
index b1147a4..4992402 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -11,6 +11,28 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "alsa"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed7572b7ba83a31e20d1b48970ee402d2e3e0537dcfe0a3ff4d6eb7508617d43"
+dependencies = [
+ "alsa-sys",
+ "bitflags 2.11.0",
+ "cfg-if",
+ "libc",
+]
+
+[[package]]
+name = "alsa-sys"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db8fee663d06c4e303404ef5f40488a53e062f89ba8bfed81f42325aafad1527"
+dependencies = [
+ "libc",
+ "pkg-config",
+]
+
 [[package]]
 name = "android_system_properties"
 version = "0.1.5"
@@ -76,12 +98,24 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
 [[package]]
 name = "autocfg"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
 [[package]]
 name = "bitflags"
 version = "2.11.0"
@@ -94,6 +128,18 @@ version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
+[[package]]
+name = "bytemuck"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+
+[[package]]
+name = "bytes"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
+
 [[package]]
 name = "cc"
 version = "1.2.57"
@@ -104,6 +150,12 @@ dependencies = [
  "shlex",
 ]
 
+[[package]]
+name = "cesu8"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c"
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -170,19 +222,69 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "combine"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "coreaudio-rs"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aae284fbaf7d27aa0e292f7677dfbe26503b0d555026f702940805a630eac17"
+dependencies = [
+ "bitflags 1.3.2",
+ "libc",
+ "objc2-audio-toolbox",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "cpal"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cbd307f43cc2a697e2d1f8bc7a1d824b5269e052209e28883e5bc04d095aaa3f"
+dependencies = [
+ "alsa",
+ "coreaudio-rs",
+ "dasp_sample",
+ "jni",
+ "js-sys",
+ "libc",
+ "mach2",
+ "ndk",
+ "ndk-context",
+ "num-derive",
+ "num-traits",
+ "objc2-audio-toolbox",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "windows",
+]
+
 [[package]]
 name = "crossterm"
 version = "0.28.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.0",
  "crossterm_winapi",
  "mio",
  "parking_lot",
@@ -201,6 +303,12 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "dasp_sample"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c87e182de0887fd5361989c677c4e8f5000cd9491d6d563161a8f3a5519fc7f"
+
 [[package]]
 name = "dirs"
 version = "5.0.1"
@@ -222,6 +330,25 @@ dependencies = [
  "windows-sys 0.48.0",
 ]
 
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+]
+
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -238,6 +365,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "extended"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af9673d8203fcb076b19dfd17e38b3d4ae9f44959416ea532ce72415a6020365"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -250,6 +383,30 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
 
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -307,7 +464,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
@@ -349,6 +506,50 @@ version = "1.0.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
 
+[[package]]
+name = "jni"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a87aa2bb7d2af34197c04845522473242e1aa17c12f4935d5856491a7fb8c97"
+dependencies = [
+ "cesu8",
+ "cfg-if",
+ "combine",
+ "jni-sys 0.3.1",
+ "log",
+ "thiserror",
+ "walkdir",
+ "windows-sys 0.45.0",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258"
+dependencies = [
+ "jni-sys 0.4.1",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.91"
@@ -407,6 +608,15 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "mach2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d640282b302c0bb0a2a8e0233ead9035e3bed871f0b7e81fe4a1ec829765db44"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -434,6 +644,35 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "ndk"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
+dependencies = [
+ "bitflags 2.11.0",
+ "jni-sys 0.3.1",
+ "log",
+ "ndk-sys",
+ "num_enum",
+ "thiserror",
+]
+
+[[package]]
+name = "ndk-context"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b"
+
+[[package]]
+name = "ndk-sys"
+version = "0.6.0+11769913"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873"
+dependencies = [
+ "jni-sys 0.3.1",
+]
+
 [[package]]
 name = "nu-ansi-term"
 version = "0.50.3"
@@ -443,6 +682,47 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "num-bigint"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -452,6 +732,100 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "num_enum"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-audio-toolbox"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6948501a91121d6399b79abaa33a8aa4ea7857fe019f341b8c23ad6e81b79b08"
+dependencies = [
+ "bitflags 2.11.0",
+ "libc",
+ "objc2",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-audio"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1eebcea8b0dbff5f7c8504f3107c68fc061a3eb44932051c8cf8a68d969c3b2"
+dependencies = [
+ "dispatch2",
+ "objc2",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-core-audio-types"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a89f2ec274a0cf4a32642b2991e8b351a404d290da87bb6a9a9d8632490bd1c"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags 2.11.0",
+ "dispatch2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "objc2",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -499,6 +873,12 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "pkg-config"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"
+
 [[package]]
 name = "prettyplease"
 version = "0.2.37"
@@ -509,6 +889,15 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "proc-macro-crate"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
+dependencies = [
+ "toml_edit",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -539,7 +928,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.0",
 ]
 
 [[package]]
@@ -570,13 +959,25 @@ version = "0.8.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
+[[package]]
+name = "rodio"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e40ecf59e742e03336be6a3d53755e789fd05a059fa22dfa0ed624722319e183"
+dependencies = [
+ "cpal",
+ "dasp_sample",
+ "num-rational",
+ "symphonia",
+]
+
 [[package]]
 name = "rustix"
 version = "0.38.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.0",
  "errno",
  "libc",
  "linux-raw-sys",
@@ -589,6 +990,15 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
@@ -690,6 +1100,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"
@@ -702,6 +1118,153 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
+[[package]]
+name = "symphonia"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5773a4c030a19d9bfaa090f49746ff35c75dfddfa700df7a5939d5e076a57039"
+dependencies = [
+ "lazy_static",
+ "symphonia-bundle-flac",
+ "symphonia-bundle-mp3",
+ "symphonia-codec-aac",
+ "symphonia-codec-pcm",
+ "symphonia-codec-vorbis",
+ "symphonia-core",
+ "symphonia-format-isomp4",
+ "symphonia-format-ogg",
+ "symphonia-format-riff",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-bundle-flac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c91565e180aea25d9b80a910c546802526ffd0072d0b8974e3ebe59b686c9976"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-bundle-mp3"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4872dd6bb56bf5eac799e3e957aa1981086c3e613b27e0ac23b176054f7c57ed"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-codec-aac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c263845aa86881416849c1729a54c7f55164f8b96111dba59de46849e73a790"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-pcm"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e89d716c01541ad3ebe7c91ce4c8d38a7cf266a3f7b2f090b108fb0cb031d95"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-vorbis"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f025837c309cd69ffef572750b4a2257b59552c5399a5e49707cc5b1b85d1c73"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-core"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea00cc4f79b7f6bb7ff87eddc065a1066f3a43fe1875979056672c9ef948c2af"
+dependencies = [
+ "arrayvec",
+ "bitflags 1.3.2",
+ "bytemuck",
+ "lazy_static",
+ "log",
+]
+
+[[package]]
+name = "symphonia-format-isomp4"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "243739585d11f81daf8dac8d9f3d18cc7898f6c09a259675fc364b382c30e0a5"
+dependencies = [
+ "encoding_rs",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-ogg"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b4955c67c1ed3aa8ae8428d04ca8397fbef6a19b2b051e73b5da8b1435639cb"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-riff"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2d7c3df0e7d94efb68401d81906eae73c02b40d5ec1a141962c592d0f11a96f"
+dependencies = [
+ "extended",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-metadata"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36306ff42b9ffe6e5afc99d49e121e0bd62fe79b9db7b9681d48e29fa19e6b16"
+dependencies = [
+ "encoding_rs",
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-utils-xiph"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee27c85ab799a338446b68eec77abf42e1a6f1bb490656e121c6e27bfbab9f16"
+dependencies = [
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
 [[package]]
 name = "syn"
 version = "2.0.117"
@@ -751,6 +1314,8 @@ dependencies = [
  "clap",
  "crossterm",
  "dirs",
+ "once_cell",
+ "rodio",
  "serde",
  "serde_json",
  "tracing",
@@ -758,6 +1323,36 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "toml_datetime"
+version = "1.1.0+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97251a7c317e03ad83774a8752a7e81fb6067740609f75ea2b585b569a59198f"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.25.8+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16bff38f1d86c47f9ff0647e6838d7bb362522bdf44006c7068c2b1e606f1f3c"
+dependencies = [
+ "indexmap",
+ "toml_datetime",
+ "toml_parser",
+ "winnow",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.0+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2334f11ee363607eb04df9b8fc8a13ca1715a72ba8662a26ac285c98aabb4011"
+dependencies = [
+ "winnow",
+]
+
 [[package]]
 name = "tracing"
 version = "0.1.44"
@@ -855,6 +1450,16 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
@@ -892,6 +1497,20 @@ dependencies = [
  "wasm-bindgen-shared",
 ]
 
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.64"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9c5522b3a28661442748e09d40924dfb9ca614b21c00d3fd135720e48b67db8"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "js-sys",
+ "once_cell",
+ "wasm-bindgen",
+ "web-sys",
+]
+
 [[package]]
 name = "wasm-bindgen-macro"
 version = "0.2.114"
@@ -952,12 +1571,22 @@ version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.0",
  "hashbrown 0.15.5",
  "indexmap",
  "semver",
 ]
 
+[[package]]
+name = "web-sys"
+version = "0.3.91"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "854ba17bb104abfb26ba36da9729addc7ce7f06f5c0f90f3c391f8461cca21f9"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "winapi"
 version = "0.3.9"
@@ -974,12 +1603,41 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
 
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "winapi-x86_64-pc-windows-gnu"
 version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
+[[package]]
+name = "windows"
+version = "0.54.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9252e5725dbed82865af151df558e754e4a3c2c30818359eb17465f1346a1b49"
+dependencies = [
+ "windows-core 0.54.0",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.54.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12661b9c89351d684a50a8a643ce5f608e20243b9fb84687800163429f161d65"
+dependencies = [
+ "windows-result 0.1.2",
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -989,7 +1647,7 @@ dependencies = [
  "windows-implement",
  "windows-interface",
  "windows-link",
- "windows-result",
+ "windows-result 0.4.1",
  "windows-strings",
 ]
 
@@ -1021,6 +1679,15 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-result"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e383302e8ec8515204254685643de10811af0ed97ea37210dc26fb0032647f8"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-result"
 version = "0.4.1"
@@ -1039,6 +1706,15 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+dependencies = [
+ "windows-targets 0.42.2",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.48.0"
@@ -1066,6 +1742,21 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-targets"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071"
+dependencies = [
+ "windows_aarch64_gnullvm 0.42.2",
+ "windows_aarch64_msvc 0.42.2",
+ "windows_i686_gnu 0.42.2",
+ "windows_i686_msvc 0.42.2",
+ "windows_x86_64_gnu 0.42.2",
+ "windows_x86_64_gnullvm 0.42.2",
+ "windows_x86_64_msvc 0.42.2",
+]
+
 [[package]]
 name = "windows-targets"
 version = "0.48.5"
@@ -1097,6 +1788,12 @@ dependencies = [
  "windows_x86_64_msvc 0.52.6",
 ]
 
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8"
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.48.5"
@@ -1109,6 +1806,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43"
+
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.48.5"
@@ -1121,6 +1824,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 
+[[package]]
+name = "windows_i686_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f"
+
 [[package]]
 name = "windows_i686_gnu"
 version = "0.48.5"
@@ -1139,6 +1848,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 
+[[package]]
+name = "windows_i686_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060"
+
 [[package]]
 name = "windows_i686_msvc"
 version = "0.48.5"
@@ -1151,6 +1866,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36"
+
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.48.5"
@@ -1163,6 +1884,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3"
+
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.48.5"
@@ -1175,6 +1902,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0"
+
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.48.5"
@@ -1187,6 +1920,15 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
+[[package]]
+name = "winnow"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a90e88e4667264a994d34e6d1ab2d26d398dcdca8b7f52bec8668957517fc7d8"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"
@@ -1245,7 +1987,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
- "bitflags",
+ "bitflags 2.11.0",
  "indexmap",
  "log",
  "serde",
diff --git a/Cargo.toml b/Cargo.toml
index 46be70c..8e7d2d2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2024"
 
 [features]
-interactive = []
+interactive = ["rodio", "once_cell"]
 default = []
 
 [dependencies]
@@ -18,5 +18,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 anyhow = "1.0"
 clap = { version = "4.5", features = ["derive"] }
 dirs = "5.0"
+rodio = { version = "0.21", optional = true }
+once_cell = { version = "1.18", optional = true }
 
-[dev-dependencies]
\ No newline at end of file
+[dev-dependencies]
diff --git a/agents/guest-piano-play.spec.md b/agents/guest-piano-play.spec.md
index 2a5cb11..91762e9 100644
--- a/agents/guest-piano-play.spec.md
+++ b/agents/guest-piano-play.spec.md
@@ -30,7 +30,7 @@ The guest girl can play the piano placed at Square `(6,2)`. When the guest stand
 
 ## Message Display
 - On key press, the bottom message line shows the note name:
-  - Example: pressing `D` shows `🎹 Mi`
+  - Example: pressing `D` shows `🎵 Mi`
 - The message updates on each key press, replacing the previous note display.
 - If the guest moves away from `(6,3)`, the keys revert to their normal behavior (farm action rejection messages).
 
@@ -77,7 +77,7 @@ The guest girl can play the piano placed at Square `(6,2)`. When the guest stand
 
 ## Implementation Notes
 - **Input handling** (`src/main.rs`): Inside the guest-enabled branch of the interactive key loop, check if `guest_location == Square && guest_x == 6 && guest_y == 3`. If true, intercept `KeyCode::Char('a'..'k')` for the 8 mapped keys before falling through to the default "Guest can only walk around." handler.
-- **State** (`src/state.rs`): Add a method `guest_play_piano(&mut self, note: &str)` that sets `self.message` to the note display string (e.g., `"🎹 Do"`). No persistent piano state is needed — each press is stateless.
+- **State** (`src/state.rs`): Add a method `guest_play_piano(&mut self, note: &str)` that sets `self.message` to the note display string (e.g., `"🎵 Do"`). No persistent piano state is needed — each press is stateless.
 - **Audio module**: Create `src/audio.rs` that loads Salamander FLAC samples from `Samples/` and plays them via `rodio`. Expose a function like `play_note(note: PianoNote)` that decodes, pitch-shifts, and appends to a sink on a background thread. Guard the entire module behind the `interactive` feature flag so MCP/headless mode is unaffected.
 - **Cargo.toml**: Add `rodio` under `[dependencies]` gated by the `interactive` feature:
   ```toml
diff --git a/src/main.rs b/src/main.rs
index 97a0724..852a3f2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -2,11 +2,13 @@
 #![allow(dead_code, unused_imports)]
 
 mod mcp;
+mod piano;
 mod savegame;
 mod state;
 mod world;
 
 use crate::mcp::handler::ToolResponse;
+use crate::piano::{PianoNote, play_note};
 use crate::state::GameState;
 use crate::world::Direction;
 use clap::Parser;
@@ -252,7 +254,12 @@ fn print_message<W: Write>(w: &mut W, game: &GameState) {
         if game.is_guest_active() {
             write!(w, "move: ↑↓←→ | greet: [SPACE]{}", EOL).unwrap();
         } else {
-            write!(w, "move: ↑↓←→ | clear: [C] | plant: [P] | water: [W] | harvest: [H] | trade: [T]{}", EOL).unwrap();
+            write!(
+                w,
+                "move: ↑↓←→ | clear: [C] | plant: [P] | water: [W] | harvest: [H] | trade: [T]{}",
+                EOL
+            )
+            .unwrap();
         }
     }
 }
@@ -482,6 +489,19 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                         continue;
                     }
 
+                    let guest_at_square_piano = game.guest_enabled
+                        && game.guest_location == state::Location::Square
+                        && game.guest_x == 6
+                        && game.guest_y == 3;
+
+                    if guest_at_square_piano {
+                        if let Some(note) = PianoNote::from_key_code(key.code) {
+                            game.guest_play_piano(note.display_name());
+                            play_note(note);
+                            continue;
+                        }
+                    }
+
                     match key.code {
                         KeyCode::Up => {
                             if game.guest_enabled {
@@ -603,7 +623,9 @@ mod tests {
         output.push('\n');
         output.push_str(&format!("> {}\n", game.message));
         output.push('\n');
-        output.push_str("move: ↑↓←→ | clear: [C] | plant: [P] | water: [W] | harvest: [H] | trade: [T]\n");
+        output.push_str(
+            "move: ↑↓←→ | clear: [C] | plant: [P] | water: [W] | harvest: [H] | trade: [T]\n",
+        );
 
         println!("{}", output);
         assert!(output.contains("tinydew day 1"));
diff --git a/src/mcp/command.rs b/src/mcp/command.rs
index 4b5e1ee..102dbd2 100644
--- a/src/mcp/command.rs
+++ b/src/mcp/command.rs
@@ -413,14 +413,12 @@ fn generate_text_snapshot(state: &GameState) -> String {
         return lines.join("\n");
     }
 
-    let mut lines = vec![
-        format!(
-            "tinydew day {} {} {}",
-            state.day,
-            state.get_weather_icon(),
-            state.format_time()
-        ),
-    ];
+    let mut lines = vec![format!(
+        "tinydew day {} {} {}",
+        state.day,
+        state.get_weather_icon(),
+        state.format_time()
+    )];
 
     let guest_visible = state.guest_enabled
         && state.guest_location == state.location
@@ -475,7 +473,12 @@ fn generate_text_snapshot(state: &GameState) -> String {
         }
         for (forage, count) in &state.inventory.forage {
             if *count > 0 {
-                lines.push(format!("forage: {} {} x{}", forage.emoji(), forage.name().to_lowercase(), count));
+                lines.push(format!(
+                    "forage: {} {} x{}",
+                    forage.emoji(),
+                    forage.name().to_lowercase(),
+                    count
+                ));
             }
         }
         for (fish, count) in &state.inventory.fish {
@@ -566,11 +569,12 @@ pub fn execute_command(state: &mut GameState, cmd: ParsedCommand) -> CommandResu
                 None => state.plant_action(),
             };
 
-            let events = if state.message.contains("Plant Done") || original_message != state.message {
-                vec!["Planted seed".to_string()]
-            } else {
-                vec![]
-            };
+            let events =
+                if state.message.contains("Plant Done") || original_message != state.message {
+                    vec!["Planted seed".to_string()]
+                } else {
+                    vec![]
+                };
 
             CommandResult::new(state.message.clone())
                 .with_events(events)
@@ -683,7 +687,8 @@ pub fn execute_command(state: &mut GameState, cmd: ParsedCommand) -> CommandResu
                 state.money += revenue;
                 state.record_income(revenue);
                 state.record_forage_sold(forage, sold_count);
-                state.message = format!("Sold {} x{} for ${}!", forage.emoji(), sold_count, revenue);
+                state.message =
+                    format!("Sold {} x{} for ${}!", forage.emoji(), sold_count, revenue);
             } else {
                 state.message = format!("No {} to sell!", forage.emoji());
             }
@@ -822,19 +827,28 @@ mod tests {
         let result = parse_command("plant:seed:down");
         assert!(matches!(
             result,
-            Ok(ParsedCommand::Plant(CropType::Carrot, Some(Direction::Down)))
+            Ok(ParsedCommand::Plant(
+                CropType::Carrot,
+                Some(Direction::Down)
+            ))
         ));
 
         let result = parse_command("plant:seed:left");
         assert!(matches!(
             result,
-            Ok(ParsedCommand::Plant(CropType::Carrot, Some(Direction::Left)))
+            Ok(ParsedCommand::Plant(
+                CropType::Carrot,
+                Some(Direction::Left)
+            ))
         ));
 
         let result = parse_command("plant:seed:right");
         assert!(matches!(
             result,
-            Ok(ParsedCommand::Plant(CropType::Carrot, Some(Direction::Right)))
+            Ok(ParsedCommand::Plant(
+                CropType::Carrot,
+                Some(Direction::Right)
+            ))
         ));
     }
 
@@ -946,19 +960,13 @@ mod tests {
     #[test]
     fn test_parse_buy() {
         let result = parse_command("buy:seed");
-        assert!(matches!(
-            result,
-            Ok(ParsedCommand::BuySeed(1))
-        ));
+        assert!(matches!(result, Ok(ParsedCommand::BuySeed(1))));
     }
 
     #[test]
     fn test_parse_buy_with_qty() {
         let result = parse_command("buy:seed:5");
-        assert!(matches!(
-            result,
-            Ok(ParsedCommand::BuySeed(5))
-        ));
+        assert!(matches!(result, Ok(ParsedCommand::BuySeed(5))));
     }
 
     #[test]
diff --git a/src/mcp/handler.rs b/src/mcp/handler.rs
index 6583d26..a92ec3c 100644
--- a/src/mcp/handler.rs
+++ b/src/mcp/handler.rs
@@ -127,7 +127,6 @@ fn should_autosave_after_command(cmd: &super::command::ParsedCommand) -> bool {
     )
 }
 
-
 pub fn handle_start_session(_input: StartSessionInput) -> ToolResponse {
     let state = match GAME_STATE.lock() {
         Ok(s) => s,
@@ -307,7 +306,6 @@ pub fn handle_command_batch(input: CommandBatchInput) -> ToolResponse {
             }
         };
 
-
         let result = execute_command(&mut state.state, parsed);
 
         results.push(serde_json::json!({
@@ -322,7 +320,6 @@ pub fn handle_command_batch(input: CommandBatchInput) -> ToolResponse {
         }));
 
         executed_count += 1;
-
     }
 
     state.mark_dirty();
diff --git a/src/mcp/state_manager.rs b/src/mcp/state_manager.rs
index e083830..a89e42c 100644
--- a/src/mcp/state_manager.rs
+++ b/src/mcp/state_manager.rs
@@ -283,8 +283,7 @@ mod tests {
 
     #[test]
     fn test_autosave_persists_state() {
-        let test_path: std::path::PathBuf =
-            std::env::temp_dir().join("tinydew_autosave_test.json");
+        let test_path: std::path::PathBuf = std::env::temp_dir().join("tinydew_autosave_test.json");
 
         let mut state = GameState::new();
         state.day = 5;
diff --git a/src/piano.rs b/src/piano.rs
new file mode 100644
index 0000000..0487782
--- /dev/null
+++ b/src/piano.rs
@@ -0,0 +1,168 @@
+use crossterm::event::KeyCode;
+
+/// Represents a piano note that the guest can play at the North Square piano.
+#[derive(Debug, Clone, Copy)]
+pub enum PianoNote {
+    Do,
+    Re,
+    Mi,
+    Fa,
+    So,
+    La,
+    Si,
+    DoSharp,
+}
+
+impl PianoNote {
+    /// Human-readable name displayed in the bottom message.
+    pub fn display_name(self) -> &'static str {
+        match self {
+            PianoNote::Do => "Do",
+            PianoNote::Re => "Re",
+            PianoNote::Mi => "Mi",
+            PianoNote::Fa => "Fa",
+            PianoNote::So => "So",
+            PianoNote::La => "La",
+            PianoNote::Si => "Si",
+            PianoNote::DoSharp => "DO#",
+        }
+    }
+
+    /// File name for the Salamander Grand Piano sample used as the source.
+    pub fn sample_file(self) -> &'static str {
+        match self {
+            PianoNote::Do | PianoNote::Re | PianoNote::Mi => "C4v8.flac",
+            PianoNote::Fa | PianoNote::So => "F#4v8.flac",
+            PianoNote::La => "A4v8.flac",
+            PianoNote::Si | PianoNote::DoSharp => "C5v8.flac",
+        }
+    }
+
+    /// Speed ratio applied to the source sample to reach the target pitch.
+    pub fn playback_speed(self) -> f32 {
+        match self {
+            PianoNote::Do => 1.0,
+            PianoNote::Re => 1.1225,
+            PianoNote::Mi => 1.2599,
+            PianoNote::Fa => 0.9439,
+            PianoNote::So => 1.0595,
+            PianoNote::La => 1.0,
+            PianoNote::Si => 0.9439,
+            PianoNote::DoSharp => 1.0,
+        }
+    }
+
+    /// Converts an interactive key press into a `PianoNote`.
+    pub fn from_key_code(key: KeyCode) -> Option<Self> {
+        if let KeyCode::Char(ch) = key {
+            match ch.to_ascii_lowercase() {
+                'a' => Some(PianoNote::Do),
+                's' => Some(PianoNote::Re),
+                'd' => Some(PianoNote::Mi),
+                'f' => Some(PianoNote::Fa),
+                'g' => Some(PianoNote::So),
+                'h' => Some(PianoNote::La),
+                'j' => Some(PianoNote::Si),
+                'k' => Some(PianoNote::DoSharp),
+                _ => None,
+            }
+        } else {
+            None
+        }
+    }
+}
+
+#[cfg(feature = "interactive")]
+mod audio {
+    use super::PianoNote;
+    use once_cell::sync::Lazy;
+use std::sync::Arc;
+    use rodio::source::Source;
+    use rodio::mixer::Mixer;
+    use rodio::{Decoder, OutputStream, OutputStreamBuilder, Sink};
+    use std::collections::VecDeque;
+    use std::fs::File;
+    use std::io::BufReader;
+    use std::path::PathBuf;
+    use std::sync::Mutex;
+    use std::time::Duration;
+
+    pub fn play_note(note: PianoNote) {
+        if let Some(manager) = &*MANAGER {
+            manager.lock().unwrap().play(note);
+        }
+    }
+
+    struct AudioManager {
+        _stream: OutputStream,
+        mixer: Mutex<Mixer>,
+        sinks: Mutex<VecDeque<Sink>>,
+    }
+
+    impl AudioManager {
+        fn new() -> anyhow::Result<Self> {
+            let stream = OutputStreamBuilder::open_default_stream()?;
+            let mixer = Mutex::new(stream.mixer().clone());
+            Ok(Self {
+                _stream: stream,
+                mixer,
+                sinks: Mutex::new(VecDeque::new()),
+            })
+        }
+
+        fn play(&self, note: PianoNote) {
+            let path = Self::sample_path(note.sample_file());
+            let file = match File::open(&path) {
+                Ok(f) => f,
+                Err(err) => {
+                    eprintln!("Failed to open piano sample {:?}: {}", path, err);
+                    return;
+                }
+            };
+
+            let decoder = match Decoder::new(BufReader::new(file)) {
+                Ok(d) => d,
+                Err(err) => {
+                    eprintln!("Failed to decode piano sample {:?}: {}", path, err);
+                    return;
+                }
+            };
+
+            let speed = note.playback_speed();
+            let source = decoder.speed(speed).fade_in(Duration::from_millis(8));
+
+            let sink = Sink::connect_new(&self.mixer.lock().unwrap());
+
+            sink.append(source);
+
+            let mut sinks = self.sinks.lock().unwrap();
+            sinks.retain(|s| !s.empty());
+            if sinks.len() >= 4 {
+                if let Some(old) = sinks.pop_front() {
+                    old.stop();
+                }
+            }
+            sinks.push_back(sink);
+        }
+
+        fn sample_path(file_name: &str) -> PathBuf {
+            static SAMPLE_DIR: Lazy<PathBuf> = Lazy::new(|| {
+                PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+                    .join("..")
+                    .join("salamander-grand-piano-in-rust")
+                    .join("Samples")
+            });
+            SAMPLE_DIR.join(file_name)
+        }
+    }
+
+    static MANAGER: Lazy<Option<Arc<Mutex<AudioManager>>>> = Lazy::new(|| {
+        AudioManager::new().ok().map(|m| Arc::new(Mutex::new(m)))
+    });
+}
+
+#[cfg(feature = "interactive")]
+pub use audio::play_note;
+
+#[cfg(not(feature = "interactive"))]
+pub fn play_note(_: PianoNote) {}
diff --git a/src/state.rs b/src/state.rs
index 629f998..783e53e 100644
--- a/src/state.rs
+++ b/src/state.rs
@@ -263,6 +263,10 @@ impl GameState {
         self.guest_enabled && self.guest_location == self.location
     }
 
+    pub fn guest_play_piano(&mut self, note: &str) {
+        self.message = format!("🎵 {}", note);
+    }
+
     fn find_guest_spawn_location(&self) -> Option<(usize, usize)> {
         self.find_guest_spawn_location_in(self.guest_location)
     }
@@ -383,7 +387,11 @@ impl GameState {
             false
         } else {
             let target_tile = match self.guest_location {
-                Location::Farm => self.farm_map.get(new_y).and_then(|row| row.get(new_x)).copied(),
+                Location::Farm => self
+                    .farm_map
+                    .get(new_y)
+                    .and_then(|row| row.get(new_x))
+                    .copied(),
                 Location::EastPath => self
                     .east_path_map
                     .get(new_y)
@@ -406,7 +414,8 @@ impl GameState {
                     "That is so beautiful. Let human enjoy it together in interactive mode.",
                 );
             } else {
-                self.message = String::from("Cannot move there. Try walking around to find a path.");
+                self.message =
+                    String::from("Cannot move there. Try walking around to find a path.");
             }
             false
         }
@@ -655,10 +664,10 @@ impl GameState {
                 self.message =
                     String::from("A beautiful old piano. It hums quietly in the square.");
             } else if matches!(target_tile, Some(TileType::Mushroom)) {
-                self.message =
-                    String::from("Cannot move there. Mature crop ahead — try harvest.");
+                self.message = String::from("Cannot move there. Mature crop ahead — try harvest.");
             } else {
-                self.message = String::from("Cannot move there. Try walking around to find a path.");
+                self.message =
+                    String::from("Cannot move there. Try walking around to find a path.");
             }
             false
         }
@@ -922,9 +931,7 @@ impl GameState {
             }
 
             let mut map_candidates: Vec<FlowerSpawnMap> = Vec::new();
-            if !farm_positions.is_empty()
-                && !Self::region_has_flower_or_mushroom(&self.farm_map)
-            {
+            if !farm_positions.is_empty() && !Self::region_has_flower_or_mushroom(&self.farm_map) {
                 map_candidates.push(FlowerSpawnMap::Farm);
             }
             if !east_path_positions.is_empty()
@@ -1006,8 +1013,8 @@ impl GameState {
             let mut farm_positions = self.get_empty_grass_positions(&self.farm_map);
             let mut east_path_positions = self.get_empty_grass_positions(&self.east_path_map);
 
-            let farm_allowed = !farm_positions.is_empty()
-                && !Self::region_has_flower_or_mushroom(&self.farm_map);
+            let farm_allowed =
+                !farm_positions.is_empty() && !Self::region_has_flower_or_mushroom(&self.farm_map);
             let east_allowed = !east_path_positions.is_empty()
                 && !Self::region_has_flower_or_mushroom(&self.east_path_map);
 
@@ -1193,8 +1200,7 @@ impl GameState {
                     self.message = String::from("Cannot clear the slide!");
                 }
                 _ => {
-                    self.message =
-                        String::from("Nothing clearable nearby.");
+                    self.message = String::from("Nothing clearable nearby.");
                 }
             }
         } else {
@@ -1233,8 +1239,7 @@ impl GameState {
                     self.message = String::from("Cannot clear the slide!");
                 }
                 _ => {
-                    self.message =
-                        String::from("Nothing clearable nearby.");
+                    self.message = String::from("Nothing clearable nearby.");
                 }
             }
         } else {
@@ -2025,14 +2030,20 @@ mod tests {
         state.spring_forced_flower_6_2_done = true;
         for y in 0..FARM_HEIGHT {
             for x in 0..FARM_WIDTH {
-                if matches!(state.farm_map[y][x], TileType::Mushroom | TileType::Crop(CropType::Flower, _)) {
+                if matches!(
+                    state.farm_map[y][x],
+                    TileType::Mushroom | TileType::Crop(CropType::Flower, _)
+                ) {
                     state.farm_map[y][x] = TileType::Grass;
                 }
             }
         }
         for y in 0..EAST_PATH_HEIGHT {
             for x in 0..EAST_PATH_WIDTH {
-                if matches!(state.east_path_map[y][x], TileType::Mushroom | TileType::Crop(CropType::Flower, _)) {
+                if matches!(
+                    state.east_path_map[y][x],
+                    TileType::Mushroom | TileType::Crop(CropType::Flower, _)
+                ) {
                     state.east_path_map[y][x] = TileType::Grass;
                 }
             }

From eef9adb3fd95fee4cc41e740073a2803139a3b4a Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 02:17:17 +0000
Subject: [PATCH 06/29] feat: implement block key sound system

- Add BlockKeyNote enum with C4-E5 notes mapped to QWERTYUIOP keys
- Generate 500ms sine wave WAV for each note via rodio
- Add BlockKeyState for key debounce
- Integrate into main.rs for guest piano mode
- Update spec documentation

Co-authored-by: Claude <claude@ubuntu>
Co-authored-by: OpenClaw <openclaw@ubuntu>
---
 agents/block-key-sound.spec.md |  73 ++++++++++++++
 src/block_key.rs               | 173 +++++++++++++++++++++++++++++++++
 src/main.rs                    |  25 ++++-
 3 files changed, 269 insertions(+), 2 deletions(-)
 create mode 100644 agents/block-key-sound.spec.md
 create mode 100644 src/block_key.rs

diff --git a/agents/block-key-sound.spec.md b/agents/block-key-sound.spec.md
new file mode 100644
index 0000000..3187060
--- /dev/null
+++ b/agents/block-key-sound.spec.md
@@ -0,0 +1,73 @@
+# Block Key Sound System — Spec
+
+## Status
+Implemented in `src/block_key.rs`.
+
+## Overview
+
+A keyboard-driven sound instrument where each of the 10 keys `Q W E R T Y U I O P` triggers a distinct musical note sound on keydown. This is a one-row piano/sampler for the Rust CLI app.
+
+## Key-to-Sound Mapping (Option A - C Major Scale)
+
+| Key | Note | Frequency (Hz) |
+|-----|------|----------------|
+| Q   | C4   | 261.63         |
+| W   | D4   | 293.66         |
+| E   | E4   | 329.63         |
+| R   | F4   | 349.23         |
+| T   | G4   | 392.00         |
+| Y   | A4   | 440.00         |
+| U   | B4   | 493.88         |
+| I   | C5   | 523.25         |
+| O   | D5   | 587.33         |
+| P   | E5   | 659.25         |
+
+## Audio Playback Mechanism
+
+**Rust rodio crate** — cross-platform audio playback.
+
+- On keydown → generate a sine wave at the mapped frequency
+- Create a 500ms duration tone with simple envelope
+- Apply gain (0.3 volume) to prevent clipping
+- Each key press is fire-and-forget (no keyup handling needed)
+- Audio initialization failures are silently ignored
+
+### Event Flow
+
+```
+key_code = KeyCode::Char('q')
+  → BlockKeyNote::Q(C4) generated from key code
+  → play_note(note) spawns new audio thread
+  → Generate 500ms sine wave at 261.63Hz
+  → Play via rodio::Sink
+```
+
+## State Management
+
+```rust
+// No persistent state needed - each press is stateless.
+// Active notes are managed internally by rodio's Sink.
+
+// Key tracking is done via Set in the input handler
+// to prevent re-triggering on key repeat.
+```
+
+### Key Concerns
+
+1. **Debounce key repeat** — track pressed keys in a `Set` to ignore key held events
+2. **Audio initialization** — silently fail if no audio device available
+3. **Polyphony** — multiple keys create separate sinks (handled by rodio)
+4. **No cleanup** — rodio handles sink cleanup automatically
+5. **Case insensitivity** — normalize `key.to_ascii_lowercase()` to handle Caps Lock
+
+## Implementation Notes
+
+- **Input handling** (`src/main.rs`): In the interactive key loop, intercept `KeyCode::Char('q'..='p')` for the 10 mapped keys
+- **Note mapping** (`src/block_key.rs`): `BlockKeyNote::from_key_code(key)` converts `KeyCode` to `BlockKeyNote`
+- **Audio module**: `src/block_key.rs` exposes `play_note(note)` which generates and plays a sine wave via rodio
+- **Cargo.toml**: `rodio` is already added as a dependency (from piano.rs)
+
+## Related Specs
+
+- `guest-piano-play.spec.md` — Existing piano implementation for reference
+- `north-square-piano.spec.md` — Piano tile placement and walkability
diff --git a/src/block_key.rs b/src/block_key.rs
new file mode 100644
index 0000000..9580ff8
--- /dev/null
+++ b/src/block_key.rs
@@ -0,0 +1,173 @@
+use std::collections::HashSet;
+use std::f32::consts::PI;
+use std::io::Cursor;
+use std::thread;
+
+use crossterm::event::KeyCode;
+use rodio::{Decoder, OutputStreamBuilder, Sink};
+
+/// Musical notes mapped to keyboard keys (C Major scale, C4–E5).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum BlockKeyNote {
+    C4,
+    D4,
+    E4,
+    F4,
+    G4,
+    A4,
+    B4,
+    C5,
+    D5,
+    E5,
+}
+
+impl BlockKeyNote {
+    /// Human-readable name displayed in the bottom message.
+    pub fn display_name(self) -> &'static str {
+        match self {
+            BlockKeyNote::C4 => "C4",
+            BlockKeyNote::D4 => "D4",
+            BlockKeyNote::E4 => "E4",
+            BlockKeyNote::F4 => "F4",
+            BlockKeyNote::G4 => "G4",
+            BlockKeyNote::A4 => "A4",
+            BlockKeyNote::B4 => "B4",
+            BlockKeyNote::C5 => "C5",
+            BlockKeyNote::D5 => "D5",
+            BlockKeyNote::E5 => "E5",
+        }
+    }
+
+    /// Frequency in Hz for this note.
+    pub fn frequency(self) -> f32 {
+        match self {
+            BlockKeyNote::C4 => 261.63,
+            BlockKeyNote::D4 => 293.66,
+            BlockKeyNote::E4 => 329.63,
+            BlockKeyNote::F4 => 349.23,
+            BlockKeyNote::G4 => 392.00,
+            BlockKeyNote::A4 => 440.00,
+            BlockKeyNote::B4 => 493.88,
+            BlockKeyNote::C5 => 523.25,
+            BlockKeyNote::D5 => 587.33,
+            BlockKeyNote::E5 => 659.25,
+        }
+    }
+
+    /// Convert a lowercase character to its corresponding note.
+    pub fn from_char(c: char) -> Option<Self> {
+        match c.to_ascii_lowercase() {
+            'q' => Some(Self::C4),
+            'w' => Some(Self::D4),
+            'e' => Some(Self::E4),
+            'r' => Some(Self::F4),
+            't' => Some(Self::G4),
+            'y' => Some(Self::A4),
+            'u' => Some(Self::B4),
+            'i' => Some(Self::C5),
+            'o' => Some(Self::D5),
+            'p' => Some(Self::E5),
+            _ => None,
+        }
+    }
+
+    /// Converts an interactive key press into a `BlockKeyNote`.
+    pub fn from_key_code(key: KeyCode) -> Option<Self> {
+        if let KeyCode::Char(ch) = key {
+            Self::from_char(ch)
+        } else {
+            None
+        }
+    }
+}
+
+/// Generate a 500ms sine-wave WAV at the given frequency, with 0.3 gain.
+fn generate_sine_wav(freq: f32) -> Vec<u8> {
+    let sample_rate: u32 = 44100;
+    let duration_secs: f32 = 0.5;
+    let gain: f32 = 0.3;
+    let num_samples = (sample_rate as f32 * duration_secs) as usize;
+
+    let attack_samples = (sample_rate as f32 * 0.01) as usize;
+    let release_samples = (sample_rate as f32 * 0.01) as usize;
+
+    let mut samples: Vec<i16> = Vec::with_capacity(num_samples);
+    for i in 0..num_samples {
+        let t = i as f32 / sample_rate as f32;
+        let raw = (2.0 * PI * freq * t).sin();
+
+        let envelope = if i < attack_samples {
+            i as f32 / attack_samples as f32
+        } else if i > num_samples - release_samples {
+            (num_samples - i) as f32 / release_samples as f32
+        } else {
+            1.0
+        };
+
+        let sample = (raw * gain * envelope * i16::MAX as f32) as i16;
+        samples.push(sample);
+    }
+
+    let data_size = (num_samples * 2) as u32;
+    let file_size = 36 + data_size;
+    let mut buf: Vec<u8> = Vec::with_capacity(44 + data_size as usize);
+
+    buf.extend_from_slice(b"RIFF");
+    buf.extend_from_slice(&file_size.to_le_bytes());
+    buf.extend_from_slice(b"WAVE");
+    buf.extend_from_slice(b"fmt ");
+    buf.extend_from_slice(&16u32.to_le_bytes());
+    buf.extend_from_slice(&1u16.to_le_bytes());
+    buf.extend_from_slice(&1u16.to_le_bytes());
+    buf.extend_from_slice(&sample_rate.to_le_bytes());
+    buf.extend_from_slice(&(sample_rate * 2).to_le_bytes());
+    buf.extend_from_slice(&2u16.to_le_bytes());
+    buf.extend_from_slice(&16u16.to_le_bytes());
+    buf.extend_from_slice(b"data");
+    buf.extend_from_slice(&data_size.to_le_bytes());
+    for s in &samples {
+        buf.extend_from_slice(&s.to_le_bytes());
+    }
+
+    buf
+}
+
+/// Fire-and-forget: spawn a thread that plays the note.
+/// Audio initialization failures are silently ignored.
+pub fn play_note(note: BlockKeyNote) {
+    thread::spawn(move || {
+        let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
+            return;
+        };
+        let sink = Sink::connect_new(&stream.mixer().clone());
+
+        let wav_data = generate_sine_wav(note.frequency());
+        let cursor = Cursor::new(wav_data);
+        if let Ok(source) = rodio::Decoder::new(cursor) {
+            sink.append(source);
+        }
+    });
+}
+
+/// Tracks currently held keys to debounce key-repeat events.
+pub struct BlockKeyState {
+    pressed: HashSet<char>,
+}
+
+impl BlockKeyState {
+    pub fn new() -> Self {
+        Self {
+            pressed: HashSet::new(),
+        }
+    }
+
+    /// Returns true if this is a fresh press (not a repeat).
+    pub fn key_down(&mut self, c: char) -> bool {
+        self.pressed.insert(c.to_ascii_lowercase())
+    }
+
+    /// Call on key release to allow re-triggering.
+    pub fn key_up(&mut self, c: char) {
+        self.pressed.remove(&c.to_ascii_lowercase());
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index 852a3f2..0d0fe27 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,14 +1,16 @@
 #![allow(clippy::needless_range_loop)]
 #![allow(dead_code, unused_imports)]
 
+mod block_key;
 mod mcp;
 mod piano;
 mod savegame;
 mod state;
 mod world;
 
+use crate::block_key::{BlockKeyNote, BlockKeyState, play_note};
 use crate::mcp::handler::ToolResponse;
-use crate::piano::{PianoNote, play_note};
+use crate::piano::{PianoNote, play_note as piano_play_note};
 use crate::state::GameState;
 use crate::world::Direction;
 use clap::Parser;
@@ -461,6 +463,8 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
 
         let _ = crossterm::execute!(std::io::stdout(), EnterAlternateScreen);
 
+        let mut block_key_state = BlockKeyState::new();
+
         loop {
             render(&game);
 
@@ -497,11 +501,24 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                     if guest_at_square_piano {
                         if let Some(note) = PianoNote::from_key_code(key.code) {
                             game.guest_play_piano(note.display_name());
-                            play_note(note);
+                            piano_play_note(note);
                             continue;
                         }
                     }
 
+                    // Block key sound system (QWERTYUIOP) - same piano location
+                    if guest_at_square_piano {
+                        if let KeyCode::Char(c) = key.code {
+                            if let Some(note) = BlockKeyNote::from_char(c) {
+                                if block_key_state.key_down(c) {
+                                    game.message = format!("🎵 {}", note.display_name());
+                                    play_note(note);
+                                }
+                                continue;
+                            }
+                        }
+                    }
+
                     match key.code {
                         KeyCode::Up => {
                             if game.guest_enabled {
@@ -576,6 +593,10 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                                 game.message = game.guest_greeting_message();
                             }
                         }
+                        // Block key key release to allow re-triggering
+                        KeyCode::Char(c) => {
+                            block_key_state.key_up(c);
+                        }
                         _ => {}
                     }
                 }

From 8af99217147144d8758f6e2309a44f60d507add5 Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 02:57:48 +0000
Subject: [PATCH 07/29] fix: use OutputStream::try_default to avoid Send trait
 issue on macOS

- Changed from OutputStreamBuilder::open_default_stream to OutputStream::try_default
- Removed thread spawned for audio stream since we can use try_default directly
- Simplified AudioManager to hold OutputStream directly
- Changed MANAGER from Lazy<Option<Arc<Mutex<...>>>> to Lazy<Arc<Mutex<_>>>
---
 src/piano.rs | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/piano.rs b/src/piano.rs
index 0487782..7afbe38 100644
--- a/src/piano.rs
+++ b/src/piano.rs
@@ -76,21 +76,21 @@ impl PianoNote {
 mod audio {
     use super::PianoNote;
     use once_cell::sync::Lazy;
-use std::sync::Arc;
-    use rodio::source::Source;
     use rodio::mixer::Mixer;
-    use rodio::{Decoder, OutputStream, OutputStreamBuilder, Sink};
+    use rodio::source::Source;
+    use rodio::{Decoder, OutputStream, Sink};
     use std::collections::VecDeque;
     use std::fs::File;
     use std::io::BufReader;
     use std::path::PathBuf;
-    use std::sync::Mutex;
+    use std::sync::{Arc, Mutex};
     use std::time::Duration;
 
     pub fn play_note(note: PianoNote) {
-        if let Some(manager) = &*MANAGER {
-            manager.lock().unwrap().play(note);
-        }
+        let manager = MANAGER.get_or_init(|| {
+            Arc::new(Mutex::new(AudioManager::new().expect("Failed to initialize audio manager")))
+        });
+        manager.lock().unwrap().play(note);
     }
 
     struct AudioManager {
@@ -101,7 +101,7 @@ use std::sync::Arc;
 
     impl AudioManager {
         fn new() -> anyhow::Result<Self> {
-            let stream = OutputStreamBuilder::open_default_stream()?;
+            let stream = OutputStream::try_default()?;
             let mixer = Mutex::new(stream.mixer().clone());
             Ok(Self {
                 _stream: stream,
@@ -156,8 +156,8 @@ use std::sync::Arc;
         }
     }
 
-    static MANAGER: Lazy<Option<Arc<Mutex<AudioManager>>>> = Lazy::new(|| {
-        AudioManager::new().ok().map(|m| Arc::new(Mutex::new(m)))
+    static MANAGER: Lazy<Arc<Mutex<AudioManager>>> = Lazy::new(|| {
+        Arc::new(Mutex::new(AudioManager::new().expect("Failed to initialize audio manager")))
     });
 }
 

From cff04fc8823f36b6019916ce8df995429e3c89fb Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 03:03:45 +0000
Subject: [PATCH 08/29] fix: use dedicated audio thread for macOS compatibility

- Spawn a dedicated thread that owns the OutputStream (which is not Send/Sync on macOS)
- Communicate with audio commands via mpsc channel
- Reads sample files and sends to audio thread instead of storing file paths
- Removed static AudioManager that caused Send trait issues with CoreAudio

This approach is similar to how block_key.rs already works and avoids
the macOS-specific issue where OutputStream contains non-Send types.
---
 src/piano.rs | 137 ++++++++++++++++++++++++++-------------------------
 1 file changed, 69 insertions(+), 68 deletions(-)

diff --git a/src/piano.rs b/src/piano.rs
index 7afbe38..71be692 100644
--- a/src/piano.rs
+++ b/src/piano.rs
@@ -75,89 +75,90 @@ impl PianoNote {
 #[cfg(feature = "interactive")]
 mod audio {
     use super::PianoNote;
-    use once_cell::sync::Lazy;
-    use rodio::mixer::Mixer;
     use rodio::source::Source;
-    use rodio::{Decoder, OutputStream, Sink};
+    use rodio::{Decoder, OutputStreamBuilder, Sink};
     use std::collections::VecDeque;
     use std::fs::File;
     use std::io::BufReader;
     use std::path::PathBuf;
-    use std::sync::{Arc, Mutex};
-    use std::time::Duration;
+    use std::sync::mpsc;
+    use std::thread;
 
     pub fn play_note(note: PianoNote) {
-        let manager = MANAGER.get_or_init(|| {
-            Arc::new(Mutex::new(AudioManager::new().expect("Failed to initialize audio manager")))
-        });
-        manager.lock().unwrap().play(note);
+        let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("..")
+            .join("salamander-grand-piano-in-rust")
+            .join("Samples")
+            .join(note.sample_file());
+        let speed = note.playback_speed();
+        let source_data = std::fs::read(&path).ok();
+        
+        if let Some(source_data) = source_data {
+            // Send the note info to the audio thread via channel
+            let _ = AUDIO_SENDER.send(AudioCommand::Play {
+                source_data,
+                speed,
+            });
+        }
     }
 
-    struct AudioManager {
-        _stream: OutputStream,
-        mixer: Mutex<Mixer>,
-        sinks: Mutex<VecDeque<Sink>>,
+    #[derive(Debug)]
+    enum AudioCommand {
+        Play {
+            source_data: Vec<u8>,
+            speed: f32,
+        },
+        Stop,
     }
 
-    impl AudioManager {
-        fn new() -> anyhow::Result<Self> {
-            let stream = OutputStream::try_default()?;
-            let mixer = Mutex::new(stream.mixer().clone());
-            Ok(Self {
-                _stream: stream,
-                mixer,
-                sinks: Mutex::new(VecDeque::new()),
-            })
-        }
-
-        fn play(&self, note: PianoNote) {
-            let path = Self::sample_path(note.sample_file());
-            let file = match File::open(&path) {
-                Ok(f) => f,
-                Err(err) => {
-                    eprintln!("Failed to open piano sample {:?}: {}", path, err);
-                    return;
-                }
+    // Channel sender for audio commands
+    static AUDIO_SENDER: once_cell::sync::Lazy<mpsc::Sender<AudioCommand>> = once_cell::sync::Lazy::new(|| {
+        let (tx, rx) = mpsc::channel::<AudioCommand>();
+        
+        // Spawn audio thread that owns the OutputStream
+        thread::spawn(move || {
+            let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
+                eprintln!("Failed to open audio stream");
+                return;
             };
-
-            let decoder = match Decoder::new(BufReader::new(file)) {
-                Ok(d) => d,
-                Err(err) => {
-                    eprintln!("Failed to decode piano sample {:?}: {}", path, err);
-                    return;
+            let mixer = stream.mixer().clone();
+            
+            let mut sinks: VecDeque<Sink> = VecDeque::new();
+            
+            for cmd in rx {
+                match cmd {
+                    AudioCommand::Play { source_data, speed } => {
+                        let cursor = std::io::Cursor::new(source_data);
+                        if let Ok(source) = Decoder::new(cursor) {
+                            let source = source
+                                .speed(speed)
+                                .fade_in(std::time::Duration::from_millis(8));
+                            
+                            let sink = Sink::connect_new(&mixer);
+                            sink.append(source);
+                            sinks.push_back(sink);
+                        }
+                    }
+                    AudioCommand::Stop => {
+                        for sink in sinks.drain(..) {
+                            sink.stop();
+                        }
+                    }
                 }
-            };
-
-            let speed = note.playback_speed();
-            let source = decoder.speed(speed).fade_in(Duration::from_millis(8));
-
-            let sink = Sink::connect_new(&self.mixer.lock().unwrap());
-
-            sink.append(source);
-
-            let mut sinks = self.sinks.lock().unwrap();
-            sinks.retain(|s| !s.empty());
-            if sinks.len() >= 4 {
-                if let Some(old) = sinks.pop_front() {
-                    old.stop();
+                
+                // Clean up empty sinks
+                sinks.retain(|s| !s.empty());
+                
+                // Limit concurrent sinks
+                if sinks.len() > 4 {
+                    if let Some(old) = sinks.pop_front() {
+                        old.stop();
+                    }
                 }
             }
-            sinks.push_back(sink);
-        }
-
-        fn sample_path(file_name: &str) -> PathBuf {
-            static SAMPLE_DIR: Lazy<PathBuf> = Lazy::new(|| {
-                PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-                    .join("..")
-                    .join("salamander-grand-piano-in-rust")
-                    .join("Samples")
-            });
-            SAMPLE_DIR.join(file_name)
-        }
-    }
-
-    static MANAGER: Lazy<Arc<Mutex<AudioManager>>> = Lazy::new(|| {
-        Arc::new(Mutex::new(AudioManager::new().expect("Failed to initialize audio manager")))
+        });
+        
+        tx
     });
 }
 

From a647f805efa59a7b6e774bce9132f7dd9dfb10fd Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 04:09:35 +0000
Subject: [PATCH 09/29] docs: update guest-piano-play.spec.md after
 implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Changed status from 'Not implemented' to 'Implemented in src/piano.rs'
- Added macOS compatibility fix notes

Co-authored-by: 🦞 <🦞@ubuntu>
---
 agents/guest-piano-play.spec.md | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/agents/guest-piano-play.spec.md b/agents/guest-piano-play.spec.md
index 91762e9..1078616 100644
--- a/agents/guest-piano-play.spec.md
+++ b/agents/guest-piano-play.spec.md
@@ -1,7 +1,10 @@
 # Guest Piano Play Spec
 
 ## Status
-Not implemented.
+Implemented in `src/piano.rs` and integrated in `src/main.rs`.
+
+## Recent Updates
+- **2026-03-26**: Updated to reflect macOS compatibility fix. Audio thread owns `OutputStream` to avoid `Send` trait issues with CoreAudio's non-Send `PropertyListenerCallbackWrapper`. Uses `mpsc` channel for communication between main thread and audio thread.
 
 ## Context
 The guest girl can play the piano placed at Square `(6,2)`. When the guest stands directly below the piano at `(6,3)`, keyboard keys activate piano notes with audible sound output. Only the guest has this ability — the player character cannot play the piano.
@@ -60,13 +63,14 @@ The guest girl can play the piano placed at Square `(6,2)`. When the guest stand
 | DO#  | DO#     | C5v8.flac     | 0               | 1.0                           |
 
 ### Playback Engine
-- Use the `rodio` crate for audio decoding and playback (already cross-platform: ALSA/PulseAudio on Linux, CoreAudio on macOS, WASAPI on Windows).
+- Uses `rodio` crate for audio decoding and playback (cross-platform: ALSA/PulseAudio on Linux, CoreAudio on macOS, WASAPI on Windows).
+- **Audio thread pattern**: A dedicated thread owns the `OutputStream` to avoid macOS `Send` trait issues (CoreAudio's `PropertyListenerCallbackWrapper` is not `Send`). The main thread communicates via `mpsc` channel.
 - Playback pipeline per note:
-  1. Read source sample bytes from disk (or from a pre-loaded in-memory cache).
-  2. Wrap bytes in a `std::io::Cursor`, decode with `rodio::Decoder::new()`.
-  3. Apply pitch shift via `.speed(speed_ratio)` using the semitone formula `2.0_f32.powf(offset / 12.0)`.
-  4. Apply a short fade-in (`.fade_in(Duration::from_millis(8))`) to prevent click artifacts.
-  5. Append to a `rodio::Sink` for non-blocking playback.
+  1. Main thread reads sample bytes from disk and sends via channel.
+  2. Audio thread receives, wraps in `std::io::Cursor`, decodes with `rodio::Decoder::new()`.
+  3. Applies pitch shift via `.speed(speed_ratio)` using the semitone formula `2.0_f32.powf(offset / 12.0)`.
+  4. Applies a short fade-in (`.fade_in(Duration::from_millis(8))`) to prevent click artifacts.
+  5. Appends to a `rodio::Sink` for non-blocking playback.
 - **Polyphony**: Maintain up to 4 concurrent voice sinks in a `VecDeque<Sink>`. When a 5th note triggers, stop the oldest sink. Prune empty sinks on each key press.
 - Each key press triggers a single note playback (non-blocking, fire-and-forget).
 - If audio initialization fails (e.g., no audio device), the game continues silently — sound is best-effort, never a hard failure.
@@ -78,15 +82,8 @@ The guest girl can play the piano placed at Square `(6,2)`. When the guest stand
 ## Implementation Notes
 - **Input handling** (`src/main.rs`): Inside the guest-enabled branch of the interactive key loop, check if `guest_location == Square && guest_x == 6 && guest_y == 3`. If true, intercept `KeyCode::Char('a'..'k')` for the 8 mapped keys before falling through to the default "Guest can only walk around." handler.
 - **State** (`src/state.rs`): Add a method `guest_play_piano(&mut self, note: &str)` that sets `self.message` to the note display string (e.g., `"🎵 Do"`). No persistent piano state is needed — each press is stateless.
-- **Audio module**: Create `src/audio.rs` that loads Salamander FLAC samples from `Samples/` and plays them via `rodio`. Expose a function like `play_note(note: PianoNote)` that decodes, pitch-shifts, and appends to a sink on a background thread. Guard the entire module behind the `interactive` feature flag so MCP/headless mode is unaffected.
-- **Cargo.toml**: Add `rodio` under `[dependencies]` gated by the `interactive` feature:
-  ```toml
-  rodio = { version = "0.21", optional = true }
-  ```
-  Update the `interactive` feature to include it:
-  ```toml
-  interactive = ["rodio"]
-  ```
+- **Audio module**: `src/piano.rs` exposes `play_note(note: PianoNote)` that uses a dedicated audio thread pattern to avoid macOS Send/Sync issues. Audio initialization failures are silently ignored (sound is best-effort).
+- **Cargo.toml**: `rodio` is added as a dependency with `rodio = { version = "0.21", optional = true }`. The `interactive` feature includes it.
 - **No MCP impact**: Piano playback is interactive-only. The MCP command interface has no piano command and requires no changes.
 
 ## Related Specs

From 772c7b1233e7e2899b805f111f1f39769ae8da0c Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 04:15:59 +0000
Subject: [PATCH 10/29] fix: make rodio a non-optional dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rodio is used by block_key.rs which is not feature-gated
- CI build fails without rodio because it's not linked
- Make rodio always available, remove from interactive feature

Co-authored-by: 🦞 <🦞@ubuntu>
---
 Cargo.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 8e7d2d2..c8d90e9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2024"
 
 [features]
-interactive = ["rodio", "once_cell"]
+interactive = ["once_cell"]
 default = []
 
 [dependencies]
@@ -18,7 +18,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 anyhow = "1.0"
 clap = { version = "4.5", features = ["derive"] }
 dirs = "5.0"
-rodio = { version = "0.21", optional = true }
+rodio = "0.21"
 once_cell = { version = "1.18", optional = true }
 
 [dev-dependencies]

From 482616bfe8c0ccc2b7655dab356808d76731712b Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 04:19:08 +0000
Subject: [PATCH 11/29] fix(ci): install ALSA dependencies for rodio
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- rodio requires alsa-sys which needs libasound2-dev
- Install ALSA dev libs before building

Co-authored-by: 🦞 <🦞@ubuntu>
---
 .github/workflows/ci.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4e31ea6..20a0177 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -60,6 +60,9 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Install ALSA dependencies
+        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+
       - name: Build
         run: cargo build --release
 

From c0574f746d12a6397f41f09abe1682584a8768c9 Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 04:24:48 +0000
Subject: [PATCH 12/29] fix(ci): add ALSA deps to all jobs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- All jobs that use rodio need libasound2-dev
- Added ALSA install to clippy, test, and nightly jobs

Co-authored-by: 🦞 <🦞@ubuntu>
---
 .github/workflows/ci.yml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 20a0177..7dae123 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -36,6 +36,9 @@ jobs:
         with:
           components: clippy
 
+      - name: Install ALSA dependencies
+        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+
       - name: Run Clippy
         run: cargo clippy --all-targets --all-features -- -D warnings
 
@@ -48,6 +51,9 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Install ALSA dependencies
+        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+
       - name: Run tests
         run: cargo test --all-features -- --test-threads=1
 
@@ -76,6 +82,9 @@ jobs:
       - name: Install Rust Nightly
         uses: dtolnay/rust-toolchain@nightly
 
+      - name: Install ALSA dependencies
+        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+
       - name: Run tests
         run: cargo test --all-features -- --test-threads=1
 

From 129337e2e9eaaec66e3ddff15501a114affaa2fd Mon Sep 17 00:00:00 2001
From: meloalright <meloalright@gmail.com>
Date: Thu, 26 Mar 2026 04:46:40 +0000
Subject: [PATCH 13/29] fix: make rodio and audio code fully optional
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Made rodio an optional dependency with minimp3 feature
- Wrapped all audio code in block_key.rs behind #[cfg(feature = interactive)]
- CI builds now use --no-default-features for headless builds
- Tests still pass with --all-features

Co-authored-by: 🦞 <🦞@ubuntu>
---
 .github/workflows/ci.yml |  7 ++----
 Cargo.lock               | 32 ++++++++++++++++++++++++
 Cargo.toml               |  4 +--
 src/block_key.rs         | 53 ++++++++++++++++++++++++----------------
 4 files changed, 68 insertions(+), 28 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7dae123..0ed03be 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -66,11 +66,8 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
-      - name: Install ALSA dependencies
-        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
-
-      - name: Build
-        run: cargo build --release
+      - name: Build (headless - no audio)
+        run: cargo build --release --no-default-features
 
   nightly:
     name: Nightly Build
diff --git a/Cargo.lock b/Cargo.lock
index 4992402..f1674f7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -632,6 +632,26 @@ version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "minimp3-sys"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e21c73734c69dc95696c9ed8926a2b393171d98b3f5f5935686a26a487ab9b90"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "minimp3_fixed"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42b0f14e7e75da97ae396c2656b10262a3d4afa2ec98f35795630eff0c8b951b"
+dependencies = [
+ "minimp3-sys",
+ "slice-ring-buffer",
+ "thiserror",
+]
+
 [[package]]
 name = "mio"
 version = "1.1.1"
@@ -967,6 +987,7 @@ checksum = "e40ecf59e742e03336be6a3d53755e789fd05a059fa22dfa0ed624722319e183"
 dependencies = [
  "cpal",
  "dasp_sample",
+ "minimp3_fixed",
  "num-rational",
  "symphonia",
 ]
@@ -1106,6 +1127,17 @@ version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
+[[package]]
+name = "slice-ring-buffer"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84ae312bda09b2368f79f985fdb4df4a0b5cbc75546b511303972d195f8c27d6"
+dependencies = [
+ "libc",
+ "mach2",
+ "winapi",
+]
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"
diff --git a/Cargo.toml b/Cargo.toml
index c8d90e9..c49b96b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2024"
 
 [features]
-interactive = ["once_cell"]
+interactive = ["rodio", "once_cell"]
 default = []
 
 [dependencies]
@@ -18,7 +18,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 anyhow = "1.0"
 clap = { version = "4.5", features = ["derive"] }
 dirs = "5.0"
-rodio = "0.21"
+rodio = { version = "0.21", optional = true, features = ["minimp3"] }
 once_cell = { version = "1.18", optional = true }
 
 [dev-dependencies]
diff --git a/src/block_key.rs b/src/block_key.rs
index 9580ff8..6c7e8ea 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -1,10 +1,6 @@
 use std::collections::HashSet;
-use std::f32::consts::PI;
-use std::io::Cursor;
-use std::thread;
 
 use crossterm::event::KeyCode;
-use rodio::{Decoder, OutputStreamBuilder, Sink};
 
 /// Musical notes mapped to keyboard keys (C Major scale, C4–E5).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -81,8 +77,40 @@ impl BlockKeyNote {
     }
 }
 
+/// Fire-and-forget: spawn a thread that plays the note.
+/// Audio initialization failures are silently ignored.
+#[cfg(feature = "interactive")]
+pub fn play_note(note: BlockKeyNote) {
+    use std::f32::consts::PI;
+    use std::io::Cursor;
+    use std::thread;
+
+    use rodio::{Decoder, OutputStreamBuilder, Sink};
+
+    thread::spawn(move || {
+        let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
+            return;
+        };
+        let sink = Sink::connect_new(&stream.mixer().clone());
+
+        let wav_data = generate_sine_wav(note.frequency());
+        let cursor = Cursor::new(wav_data);
+        if let Ok(source) = rodio::Decoder::new(cursor) {
+            sink.append(source);
+        }
+    });
+}
+
+#[cfg(not(feature = "interactive"))]
+pub fn play_note(_note: BlockKeyNote) {
+    // No-op when audio is disabled
+}
+
 /// Generate a 500ms sine-wave WAV at the given frequency, with 0.3 gain.
+#[cfg(feature = "interactive")]
 fn generate_sine_wav(freq: f32) -> Vec<u8> {
+    use std::f32::consts::PI;
+
     let sample_rate: u32 = 44100;
     let duration_secs: f32 = 0.5;
     let gain: f32 = 0.3;
@@ -132,23 +160,6 @@ fn generate_sine_wav(freq: f32) -> Vec<u8> {
     buf
 }
 
-/// Fire-and-forget: spawn a thread that plays the note.
-/// Audio initialization failures are silently ignored.
-pub fn play_note(note: BlockKeyNote) {
-    thread::spawn(move || {
-        let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
-            return;
-        };
-        let sink = Sink::connect_new(&stream.mixer().clone());
-
-        let wav_data = generate_sine_wav(note.frequency());
-        let cursor = Cursor::new(wav_data);
-        if let Ok(source) = rodio::Decoder::new(cursor) {
-            sink.append(source);
-        }
-    });
-}
-
 /// Tracks currently held keys to debounce key-repeat events.
 pub struct BlockKeyState {
     pressed: HashSet<char>,

From f1c75796603af55a3499115e64ed3ca2f8515760 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:42:36 +0000
Subject: [PATCH 14/29] Update piano keyboard system to use Salamander Grand
 Piano samples

Co-authored-by: Melo <5381032473@telegram>
---
 PianoKeyboard.md | 65 +++++++++++++++++++++++++++++++++
 README.md        | 28 ++++++++++++++
 src/block_key.rs | 95 +++++++++++++++++-------------------------------
 3 files changed, 127 insertions(+), 61 deletions(-)
 create mode 100644 PianoKeyboard.md

diff --git a/PianoKeyboard.md b/PianoKeyboard.md
new file mode 100644
index 0000000..1a63b29
--- /dev/null
+++ b/PianoKeyboard.md
@@ -0,0 +1,65 @@
+# Piano Keyboard Mapping
+
+Tinydew features two piano input systems:
+
+## 1. Block Key System (QWERTYUIOP)
+
+The default piano system uses keyboard keys Q, W, E, R, T, Y, U, I, O, P to play notes.
+
+| Key | Note | Frequency | Sample File | Playback Speed |
+|-----|------|-----------|-------------|----------------|
+| Q | C4 | 261.63 Hz | C4v8.flac | 1.0 |
+| W | D4 | 293.66 Hz | C4v8.flac | 1.1225 |
+| E | E4 | 329.63 Hz | C4v8.flac | 1.2599 |
+| R | F4 | 349.23 Hz | C4v8.flac | 0.9439 |
+| T | G4 | 392.00 Hz | C4v8.flac | 1.0595 |
+| Y | A4 | 440.00 Hz | A4v8.flac | 1.0 |
+| U | B4 | 493.88 Hz | A4v8.flac | 0.9439 |
+| I | C5 | 523.25 Hz | C5v8.flac | 1.0 |
+| O | D5 | 587.33 Hz | C5v8.flac | 1.1225 |
+| P | E5 | 659.25 Hz | C5v8.flac | 1.2599 |
+
+### Usage
+
+- Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
+- Press any of the above keys to play the corresponding note
+- Keys are debounced - press and release to hear the note again
+
+## 2. Traditional Piano System (ASDFGHJK)
+
+A secondary piano system uses keys A, S, D, F, G, H, J, K.
+
+| Key | Note | Sample File | Playback Speed |
+|-----|------|-------------|----------------|
+| A | Do (C4) | C4v8.flac | 1.0 |
+| S | Re (D4) | C4v8.flac | 1.1225 |
+| D | Mi (E4) | C4v8.flac | 1.2599 |
+| F | Fa (F4) | F#4v8.flac | 0.9439 |
+| G | So (G4) | F#4v8.flac | 1.0595 |
+| H | La (A4) | A4v8.flac | 1.0 |
+| J | Si (B4) | A4v8.flac | 0.9439 |
+| K | Do# (C5) | C5v8.flac | 1.0 |
+
+## Sound Source
+
+Both systems use the [Salamander Grand Piano](https://github.com/alexholm/salamander-grand-piano-in-rust) samples by Alexander Holm.
+
+## Requirements
+
+- Interactive mode must be enabled: `cargo build --features interactive`
+- Audio system must be available (rodio uses system audio API)
+- Sound samples must be present at: `../salamander-grand-piano-in-rust/Samples/`
+
+---
+
+## Building with Interactive Mode
+
+```bash
+cargo build --release --features interactive
+```
+
+Then run:
+
+```bash
+cargo run --features interactive
+```
diff --git a/README.md b/README.md
index 262b5e2..61ffbaf 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@ A cozy farming game with both interactive play and MCP automation support.
 Tinydew is a lightweight Rust game where you can:
 - move between regions (Farm, EastPath, Square, SouthRiver)
 - farm, fish, trade, and progress days
+- play piano with guests at the North Square
 - run fully in MCP mode for automation agents like OpenClaw
 
 ---
@@ -70,6 +71,33 @@ cargo test
 
 ---
 
+## Piano Keyboard
+
+Tinydew features a piano at the North Square where guests can play music.
+
+**Keyboard Mapping:**
+- Q, W, E, R, T, Y, U, I, O, P → C Major scale (C4–E5) using Salamander Grand Piano samples
+
+See [`PianoKeyboard.md`](./PianoKeyboard.md) for full details.
+
+---
+
+## Save Data
+
+Default save location:
+
+```text
+~/.local/share/tinydew/savegame.json
+```
+
+Reset save:
+
+```bash
+rm -f ~/.local/share/tinydew/savegame.json
+```
+
+---
+
 ## OpenClaw Installation Guide
 
 For full OpenClaw setup and usage notes, see:
diff --git a/src/block_key.rs b/src/block_key.rs
index 6c7e8ea..5d43986 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -77,26 +77,53 @@ impl BlockKeyNote {
     }
 }
 
+/// Map a BlockKeyNote to its corresponding sample file and playback speed.
+fn sample_info(note: BlockKeyNote) -> (&'static str, f32) {
+    match note {
+        BlockKeyNote::C4 => ("C4v8.flac", 1.0),
+        BlockKeyNote::D4 => ("C4v8.flac", 1.1225),
+        BlockKeyNote::E4 => ("C4v8.flac", 1.2599),
+        BlockKeyNote::F4 => ("C4v8.flac", 0.9439),
+        BlockKeyNote::G4 => ("C4v8.flac", 1.0595),
+        BlockKeyNote::A4 => ("A4v8.flac", 1.0),
+        BlockKeyNote::B4 => ("A4v8.flac", 0.9439),
+        BlockKeyNote::C5 => ("C5v8.flac", 1.0),
+        BlockKeyNote::D5 => ("C5v8.flac", 1.1225),
+        BlockKeyNote::E5 => ("C5v8.flac", 1.2599),
+    }
+}
+
 /// Fire-and-forget: spawn a thread that plays the note.
 /// Audio initialization failures are silently ignored.
 #[cfg(feature = "interactive")]
 pub fn play_note(note: BlockKeyNote) {
-    use std::f32::consts::PI;
-    use std::io::Cursor;
+    use std::path::PathBuf;
+    use rodio::source::Source;
+    use rodio::{Decoder, OutputStreamBuilder, Sink};
+    use std::fs::File;
+    use std::io::BufReader;
     use std::thread;
 
-    use rodio::{Decoder, OutputStreamBuilder, Sink};
+    let (sample_file, speed) = sample_info(note);
 
     thread::spawn(move || {
+        let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("..")
+            .join("salamander-grand-piano-in-rust")
+            .join("Samples")
+            .join(sample_file);
+
         let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
             return;
         };
         let sink = Sink::connect_new(&stream.mixer().clone());
 
-        let wav_data = generate_sine_wav(note.frequency());
-        let cursor = Cursor::new(wav_data);
-        if let Ok(source) = rodio::Decoder::new(cursor) {
-            sink.append(source);
+        if let Ok(file) = File::open(&path) {
+            let reader = BufReader::new(file);
+            if let Ok(source) = Decoder::new(reader) {
+                let source = source.speed(speed);
+                sink.append(source);
+            }
         }
     });
 }
@@ -106,60 +133,6 @@ pub fn play_note(_note: BlockKeyNote) {
     // No-op when audio is disabled
 }
 
-/// Generate a 500ms sine-wave WAV at the given frequency, with 0.3 gain.
-#[cfg(feature = "interactive")]
-fn generate_sine_wav(freq: f32) -> Vec<u8> {
-    use std::f32::consts::PI;
-
-    let sample_rate: u32 = 44100;
-    let duration_secs: f32 = 0.5;
-    let gain: f32 = 0.3;
-    let num_samples = (sample_rate as f32 * duration_secs) as usize;
-
-    let attack_samples = (sample_rate as f32 * 0.01) as usize;
-    let release_samples = (sample_rate as f32 * 0.01) as usize;
-
-    let mut samples: Vec<i16> = Vec::with_capacity(num_samples);
-    for i in 0..num_samples {
-        let t = i as f32 / sample_rate as f32;
-        let raw = (2.0 * PI * freq * t).sin();
-
-        let envelope = if i < attack_samples {
-            i as f32 / attack_samples as f32
-        } else if i > num_samples - release_samples {
-            (num_samples - i) as f32 / release_samples as f32
-        } else {
-            1.0
-        };
-
-        let sample = (raw * gain * envelope * i16::MAX as f32) as i16;
-        samples.push(sample);
-    }
-
-    let data_size = (num_samples * 2) as u32;
-    let file_size = 36 + data_size;
-    let mut buf: Vec<u8> = Vec::with_capacity(44 + data_size as usize);
-
-    buf.extend_from_slice(b"RIFF");
-    buf.extend_from_slice(&file_size.to_le_bytes());
-    buf.extend_from_slice(b"WAVE");
-    buf.extend_from_slice(b"fmt ");
-    buf.extend_from_slice(&16u32.to_le_bytes());
-    buf.extend_from_slice(&1u16.to_le_bytes());
-    buf.extend_from_slice(&1u16.to_le_bytes());
-    buf.extend_from_slice(&sample_rate.to_le_bytes());
-    buf.extend_from_slice(&(sample_rate * 2).to_le_bytes());
-    buf.extend_from_slice(&2u16.to_le_bytes());
-    buf.extend_from_slice(&16u16.to_le_bytes());
-    buf.extend_from_slice(b"data");
-    buf.extend_from_slice(&data_size.to_le_bytes());
-    for s in &samples {
-        buf.extend_from_slice(&s.to_le_bytes());
-    }
-
-    buf
-}
-
 /// Tracks currently held keys to debounce key-repeat events.
 pub struct BlockKeyState {
     pressed: HashSet<char>,

From 90fa4b718ccb9eb7b62f737a27251b3e195c32e3 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:48:48 +0000
Subject: [PATCH 15/29] Fix block key audio: use shared OutputStream instead of
 dropping stream per note

---
 src/block_key.rs | 89 +++++++++++++++++++++++++++++++++++-------------
 1 file changed, 66 insertions(+), 23 deletions(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index 5d43986..971e58f 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -1,6 +1,14 @@
 use std::collections::HashSet;
+use std::collections::VecDeque;
+use std::fs::File;
+use std::io::BufReader;
+use std::path::PathBuf;
+use std::sync::mpsc;
+use std::thread;
 
 use crossterm::event::KeyCode;
+use once_cell::sync::Lazy as OnceCellLazy;
+use rodio::{Decoder, OutputStreamBuilder, Sink, Source};
 
 /// Musical notes mapped to keyboard keys (C Major scale, C4–E5).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -93,39 +101,74 @@ fn sample_info(note: BlockKeyNote) -> (&'static str, f32) {
     }
 }
 
-/// Fire-and-forget: spawn a thread that plays the note.
-/// Audio initialization failures are silently ignored.
-#[cfg(feature = "interactive")]
-pub fn play_note(note: BlockKeyNote) {
-    use std::path::PathBuf;
-    use rodio::source::Source;
-    use rodio::{Decoder, OutputStreamBuilder, Sink};
-    use std::fs::File;
-    use std::io::BufReader;
-    use std::thread;
+/// Audio command for the shared audio thread.
+#[derive(Debug)]
+enum AudioCommand {
+    Play {
+        sample_file: String,
+        speed: f32,
+    },
+}
 
-    let (sample_file, speed) = sample_info(note);
+/// Shared audio sender for all block key notes.
+/// Uses a single OutputStream that lives for the duration of the program.
+#[cfg(feature = "interactive")]
+static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLazy::new(|| {
+    let (tx, rx) = mpsc::channel::<AudioCommand>();
 
     thread::spawn(move || {
-        let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-            .join("..")
-            .join("salamander-grand-piano-in-rust")
-            .join("Samples")
-            .join(sample_file);
-
         let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
+            eprintln!("[BlockKey] Failed to open audio stream");
             return;
         };
-        let sink = Sink::connect_new(&stream.mixer().clone());
+        let mixer = stream.mixer().clone();
+
+        let mut sinks: VecDeque<Sink> = VecDeque::new();
+
+        for cmd in rx {
+            let (sample_file, speed) = match cmd {
+                AudioCommand::Play { sample_file, speed } => (sample_file, speed),
+            };
+
+            let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+                .join("..")
+                .join("salamander-grand-piano-in-rust")
+                .join("Samples")
+                .join(&sample_file);
+
+            if let Ok(file) = File::open(&path) {
+                let reader = BufReader::new(file);
+                if let Ok(source) = Decoder::new(reader) {
+                    let source = source.speed(speed);
+                    let sink = Sink::connect_new(&mixer);
+                    sink.append(source);
+                    sinks.push_back(sink);
+                }
+            }
 
-        if let Ok(file) = File::open(&path) {
-            let reader = BufReader::new(file);
-            if let Ok(source) = Decoder::new(reader) {
-                let source = source.speed(speed);
-                sink.append(source);
+            // Clean up empty sinks
+            sinks.retain(|s| !s.empty());
+
+            // Limit concurrent sinks
+            if sinks.len() > 4 {
+                if let Some(old) = sinks.pop_front() {
+                    old.stop();
+                }
             }
         }
     });
+
+    tx
+});
+
+/// Play a note using the shared audio thread.
+#[cfg(feature = "interactive")]
+pub fn play_note(note: BlockKeyNote) {
+    let (sample_file, speed) = sample_info(note);
+    let _ = BLOCK_AUDIO_SENDER.send(AudioCommand::Play {
+        sample_file: sample_file.to_string(),
+        speed,
+    });
 }
 
 #[cfg(not(feature = "interactive"))]

From 61084ce8b19ee782f5cfb36d60639922e5756d30 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:49:32 +0000
Subject: [PATCH 16/29] Refactor block key audio to reuse piano.rs logic

Co-authored-by: Melo <5381032473@telegram>

Co-authored-by: OpenClaw <support@openclaw.dev>
---
 src/block_key.rs | 63 ++++++++++++++++++++++--------------------------
 1 file changed, 29 insertions(+), 34 deletions(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index 971e58f..5da3831 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -1,7 +1,5 @@
 use std::collections::HashSet;
 use std::collections::VecDeque;
-use std::fs::File;
-use std::io::BufReader;
 use std::path::PathBuf;
 use std::sync::mpsc;
 use std::thread;
@@ -9,6 +7,7 @@ use std::thread;
 use crossterm::event::KeyCode;
 use once_cell::sync::Lazy as OnceCellLazy;
 use rodio::{Decoder, OutputStreamBuilder, Sink, Source};
+use std::io::Cursor;
 
 /// Musical notes mapped to keyboard keys (C Major scale, C4–E5).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -42,19 +41,28 @@ impl BlockKeyNote {
         }
     }
 
-    /// Frequency in Hz for this note.
-    pub fn frequency(self) -> f32 {
+    /// File name for the Salamander Grand Piano sample used as the source.
+    pub fn sample_file(self) -> &'static str {
         match self {
-            BlockKeyNote::C4 => 261.63,
-            BlockKeyNote::D4 => 293.66,
-            BlockKeyNote::E4 => 329.63,
-            BlockKeyNote::F4 => 349.23,
-            BlockKeyNote::G4 => 392.00,
-            BlockKeyNote::A4 => 440.00,
-            BlockKeyNote::B4 => 493.88,
-            BlockKeyNote::C5 => 523.25,
-            BlockKeyNote::D5 => 587.33,
-            BlockKeyNote::E5 => 659.25,
+            BlockKeyNote::C4 | BlockKeyNote::D4 | BlockKeyNote::E4 | BlockKeyNote::F4 | BlockKeyNote::G4 => "C4v8.flac",
+            BlockKeyNote::A4 | BlockKeyNote::B4 => "A4v8.flac",
+            BlockKeyNote::C5 | BlockKeyNote::D5 | BlockKeyNote::E5 => "C5v8.flac",
+        }
+    }
+
+    /// Speed ratio applied to the source sample to reach the target pitch.
+    pub fn playback_speed(self) -> f32 {
+        match self {
+            BlockKeyNote::C4 => 1.0,
+            BlockKeyNote::D4 => 1.1225,
+            BlockKeyNote::E4 => 1.2599,
+            BlockKeyNote::F4 => 0.9439,
+            BlockKeyNote::G4 => 1.0595,
+            BlockKeyNote::A4 => 1.0,
+            BlockKeyNote::B4 => 0.9439,
+            BlockKeyNote::C5 => 1.0,
+            BlockKeyNote::D5 => 1.1225,
+            BlockKeyNote::E5 => 1.2599,
         }
     }
 
@@ -85,22 +93,6 @@ impl BlockKeyNote {
     }
 }
 
-/// Map a BlockKeyNote to its corresponding sample file and playback speed.
-fn sample_info(note: BlockKeyNote) -> (&'static str, f32) {
-    match note {
-        BlockKeyNote::C4 => ("C4v8.flac", 1.0),
-        BlockKeyNote::D4 => ("C4v8.flac", 1.1225),
-        BlockKeyNote::E4 => ("C4v8.flac", 1.2599),
-        BlockKeyNote::F4 => ("C4v8.flac", 0.9439),
-        BlockKeyNote::G4 => ("C4v8.flac", 1.0595),
-        BlockKeyNote::A4 => ("A4v8.flac", 1.0),
-        BlockKeyNote::B4 => ("A4v8.flac", 0.9439),
-        BlockKeyNote::C5 => ("C5v8.flac", 1.0),
-        BlockKeyNote::D5 => ("C5v8.flac", 1.1225),
-        BlockKeyNote::E5 => ("C5v8.flac", 1.2599),
-    }
-}
-
 /// Audio command for the shared audio thread.
 #[derive(Debug)]
 enum AudioCommand {
@@ -136,9 +128,11 @@ static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLa
                 .join("Samples")
                 .join(&sample_file);
 
-            if let Ok(file) = File::open(&path) {
-                let reader = BufReader::new(file);
-                if let Ok(source) = Decoder::new(reader) {
+            let source_data = std::fs::read(&path).ok();
+
+            if let Some(source_data) = source_data {
+                let cursor = Cursor::new(source_data);
+                if let Ok(source) = Decoder::new(cursor) {
                     let source = source.speed(speed);
                     let sink = Sink::connect_new(&mixer);
                     sink.append(source);
@@ -164,7 +158,8 @@ static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLa
 /// Play a note using the shared audio thread.
 #[cfg(feature = "interactive")]
 pub fn play_note(note: BlockKeyNote) {
-    let (sample_file, speed) = sample_info(note);
+    let sample_file = note.sample_file();
+    let speed = note.playback_speed();
     let _ = BLOCK_AUDIO_SENDER.send(AudioCommand::Play {
         sample_file: sample_file.to_string(),
         speed,

From 8aa70d729a1a7fad576e8329a8446ec210fdde2d Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:50:25 +0000
Subject: [PATCH 17/29] Update PianoKeyboard.md with audio implementation
 details

---
 PianoKeyboard.md | 59 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/PianoKeyboard.md b/PianoKeyboard.md
index 1a63b29..ce506f9 100644
--- a/PianoKeyboard.md
+++ b/PianoKeyboard.md
@@ -1,29 +1,30 @@
 # Piano Keyboard Mapping
 
-Tinydew features two piano input systems:
+Tinydew features two piano input systems that use the Salamander Grand Piano samples.
 
-## 1. Block Key System (QWERTYUIOP)
+## 1. Block Key System (QWERTYUIOP) - Default
 
 The default piano system uses keyboard keys Q, W, E, R, T, Y, U, I, O, P to play notes.
 
-| Key | Note | Frequency | Sample File | Playback Speed |
-|-----|------|-----------|-------------|----------------|
-| Q | C4 | 261.63 Hz | C4v8.flac | 1.0 |
-| W | D4 | 293.66 Hz | C4v8.flac | 1.1225 |
-| E | E4 | 329.63 Hz | C4v8.flac | 1.2599 |
-| R | F4 | 349.23 Hz | C4v8.flac | 0.9439 |
-| T | G4 | 392.00 Hz | C4v8.flac | 1.0595 |
-| Y | A4 | 440.00 Hz | A4v8.flac | 1.0 |
-| U | B4 | 493.88 Hz | A4v8.flac | 0.9439 |
-| I | C5 | 523.25 Hz | C5v8.flac | 1.0 |
-| O | D5 | 587.33 Hz | C5v8.flac | 1.1225 |
-| P | E5 | 659.25 Hz | C5v8.flac | 1.2599 |
+| Key | Note | Sample File | Playback Speed |
+|-----|------|-------------|----------------|
+| Q | C4 | C4v8.flac | 1.0 |
+| W | D4 | C4v8.flac | 1.1225 |
+| E | E4 | C4v8.flac | 1.2599 |
+| R | F4 | C4v8.flac | 0.9439 |
+| T | G4 | C4v8.flac | 1.0595 |
+| Y | A4 | A4v8.flac | 1.0 |
+| U | B4 | A4v8.flac | 0.9439 |
+| I | C5 | C5v8.flac | 1.0 |
+| O | D5 | C5v8.flac | 1.1225 |
+| P | E5 | C5v8.flac | 1.2599 |
 
 ### Usage
 
 - Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
 - Press any of the above keys to play the corresponding note
 - Keys are debounced - press and release to hear the note again
+- Uses shared audio thread ( OutputStream ) to prevent audio drop warnings
 
 ## 2. Traditional Piano System (ASDFGHJK)
 
@@ -40,18 +41,36 @@ A secondary piano system uses keys A, S, D, F, G, H, J, K.
 | J | Si (B4) | A4v8.flac | 0.9439 |
 | K | Do# (C5) | C5v8.flac | 1.0 |
 
+### Usage
+
+- Same position requirement: guest at (6, 3) on Square map
+- Uses the same `PianoNote` type as the traditional keyboard layout
+
+## Audio Implementation
+
+Both systems use identical audio logic:
+
+- **Shared OutputStream**: A single background thread owns the audio stream
+- **mpsc channel**: Key presses send `AudioCommand::Play` messages
+- **Sink cleanup**: Automatic cleanup of finished notes, max 4 concurrent sinks
+- **Sample format**: .flac files from Salamander Grand Piano project
+
 ## Sound Source
 
 Both systems use the [Salamander Grand Piano](https://github.com/alexholm/salamander-grand-piano-in-rust) samples by Alexander Holm.
 
+Available samples:
+- C4v8.flac (root C4, various speeds for pitch shifting)
+- F#4v8.flac (F#4 for Fa and So notes)
+- A4v8.flac (A4 for La note)
+- C5v8.flac (C5 for higher notes)
+
 ## Requirements
 
 - Interactive mode must be enabled: `cargo build --features interactive`
-- Audio system must be available (rodio uses system audio API)
+- Audio system must be available (rodio uses system audio API via cpal)
 - Sound samples must be present at: `../salamander-grand-piano-in-rust/Samples/`
 
----
-
 ## Building with Interactive Mode
 
 ```bash
@@ -63,3 +82,9 @@ Then run:
 ```bash
 cargo run --features interactive
 ```
+
+## Troubleshooting
+
+If you see "Dropping OutputStream" warnings:
+- Ensure only one audio stream is created (fixed in recent versions)
+- The block key system now uses a shared OutputStream for all notes

From eda002bab6edb97723db68faa63fb847a65e29f7 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:55:32 +0000
Subject: [PATCH 18/29] Update block key mapping to black keys (C#, D#, F#, G#,
 A#)

---
 src/block_key.rs | 88 +++++++++++++++++++++++-------------------------
 src/main.rs      |  2 +-
 2 files changed, 44 insertions(+), 46 deletions(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index 5da3831..efda7f3 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -9,76 +9,67 @@ use once_cell::sync::Lazy as OnceCellLazy;
 use rodio::{Decoder, OutputStreamBuilder, Sink, Source};
 use std::io::Cursor;
 
-/// Musical notes mapped to keyboard keys (C Major scale, C4–E5).
+/// Musical notes mapped to keyboard keys (black keys).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BlockKeyNote {
-    C4,
-    D4,
-    E4,
-    F4,
-    G4,
-    A4,
-    B4,
-    C5,
-    D5,
-    E5,
+    C4Sharp,    // C#
+    D4Sharp,    // D#
+    F4Sharp,    // F#
+    G4Sharp,    // G#
+    A4Sharp,    // A#
+    None,       // No sound
 }
 
 impl BlockKeyNote {
     /// Human-readable name displayed in the bottom message.
     pub fn display_name(self) -> &'static str {
         match self {
-            BlockKeyNote::C4 => "C4",
-            BlockKeyNote::D4 => "D4",
-            BlockKeyNote::E4 => "E4",
-            BlockKeyNote::F4 => "F4",
-            BlockKeyNote::G4 => "G4",
-            BlockKeyNote::A4 => "A4",
-            BlockKeyNote::B4 => "B4",
-            BlockKeyNote::C5 => "C5",
-            BlockKeyNote::D5 => "D5",
-            BlockKeyNote::E5 => "E5",
+            BlockKeyNote::C4Sharp => "C#",
+            BlockKeyNote::D4Sharp => "D#",
+            BlockKeyNote::F4Sharp => "F#",
+            BlockKeyNote::G4Sharp => "G#",
+            BlockKeyNote::A4Sharp => "A#",
+            BlockKeyNote::None => "",
         }
     }
 
     /// File name for the Salamander Grand Piano sample used as the source.
     pub fn sample_file(self) -> &'static str {
         match self {
-            BlockKeyNote::C4 | BlockKeyNote::D4 | BlockKeyNote::E4 | BlockKeyNote::F4 | BlockKeyNote::G4 => "C4v8.flac",
-            BlockKeyNote::A4 | BlockKeyNote::B4 => "A4v8.flac",
-            BlockKeyNote::C5 | BlockKeyNote::D5 | BlockKeyNote::E5 => "C5v8.flac",
+            BlockKeyNote::C4Sharp => "C4v8.flac",
+            BlockKeyNote::D4Sharp => "C4v8.flac",
+            BlockKeyNote::F4Sharp => "F#4v8.flac",
+            BlockKeyNote::G4Sharp => "F#4v8.flac",
+            BlockKeyNote::A4Sharp => "A4v8.flac",
+            BlockKeyNote::None => "",
         }
     }
 
     /// Speed ratio applied to the source sample to reach the target pitch.
     pub fn playback_speed(self) -> f32 {
         match self {
-            BlockKeyNote::C4 => 1.0,
-            BlockKeyNote::D4 => 1.1225,
-            BlockKeyNote::E4 => 1.2599,
-            BlockKeyNote::F4 => 0.9439,
-            BlockKeyNote::G4 => 1.0595,
-            BlockKeyNote::A4 => 1.0,
-            BlockKeyNote::B4 => 0.9439,
-            BlockKeyNote::C5 => 1.0,
-            BlockKeyNote::D5 => 1.1225,
-            BlockKeyNote::E5 => 1.2599,
+            BlockKeyNote::C4Sharp => 1.0595,   // C# = C4 * 2^(1/12)
+            BlockKeyNote::D4Sharp => 1.1892,   // D# = D4 * 2^(1/12)
+            BlockKeyNote::F4Sharp => 1.0,      // F#
+            BlockKeyNote::G4Sharp => 1.0595,   // G# = G4 * 2^(1/12)
+            BlockKeyNote::A4Sharp => 1.1892,   // A# = A4 * 2^(1/12)
+            BlockKeyNote::None => 1.0,
         }
     }
 
     /// Convert a lowercase character to its corresponding note.
     pub fn from_char(c: char) -> Option<Self> {
         match c.to_ascii_lowercase() {
-            'q' => Some(Self::C4),
-            'w' => Some(Self::D4),
-            'e' => Some(Self::E4),
-            'r' => Some(Self::F4),
-            't' => Some(Self::G4),
-            'y' => Some(Self::A4),
-            'u' => Some(Self::B4),
-            'i' => Some(Self::C5),
-            'o' => Some(Self::D5),
-            'p' => Some(Self::E5),
+            'q' => Some(BlockKeyNote::C4Sharp),   // C#
+            'w' => Some(BlockKeyNote::D4Sharp),   // D#
+            'e' => Some(BlockKeyNote::F4Sharp),   // F#
+            'r' => Some(BlockKeyNote::G4Sharp),   // G#
+            't' => Some(BlockKeyNote::A4Sharp),   // A#
+            'y' => Some(BlockKeyNote::None),      // No sound
+            'u' => Some(BlockKeyNote::None),      // No sound
+            'i' => Some(BlockKeyNote::None),      // No sound
+            'o' => Some(BlockKeyNote::None),      // No sound
+            'p' => Some(BlockKeyNote::None),      // No sound
             _ => None,
         }
     }
@@ -156,14 +147,21 @@ static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLa
 });
 
 /// Play a note using the shared audio thread.
+/// Returns true if note should be displayed in message, false otherwise.
 #[cfg(feature = "interactive")]
-pub fn play_note(note: BlockKeyNote) {
+pub fn play_note(note: BlockKeyNote) -> bool {
+    // Skip sound for None notes
+    if matches!(note, BlockKeyNote::None) {
+        return false;
+    }
+    
     let sample_file = note.sample_file();
     let speed = note.playback_speed();
     let _ = BLOCK_AUDIO_SENDER.send(AudioCommand::Play {
         sample_file: sample_file.to_string(),
         speed,
     });
+    true
 }
 
 #[cfg(not(feature = "interactive"))]
diff --git a/src/main.rs b/src/main.rs
index 0d0fe27..a93ff1e 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -512,7 +512,7 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                             if let Some(note) = BlockKeyNote::from_char(c) {
                                 if block_key_state.key_down(c) {
                                     game.message = format!("🎵 {}", note.display_name());
-                                    play_note(note);
+                                    let _ = play_note(note);
                                 }
                                 continue;
                             }

From a5147cde1d1fdf3998c8a782c25b1a6a4b3f594c Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 17:56:10 +0000
Subject: [PATCH 19/29] Update block key mapping to black keys (C#, D#, F#, G#,
 A#)

- Q, W, E, R, T play black keys (C#, D#, F#, G#, A#)

- Y, U, I, O, P produce no sound

- Uses shared OutputStream to prevent audio warnings

Co-authored-by: Melo <5381032473@telegram>

Co-authored-by: OpenClaw <support@openclaw.dev>
---
 PianoKeyboard.md | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/PianoKeyboard.md b/PianoKeyboard.md
index ce506f9..3bb534d 100644
--- a/PianoKeyboard.md
+++ b/PianoKeyboard.md
@@ -6,25 +6,26 @@ Tinydew features two piano input systems that use the Salamander Grand Piano sam
 
 The default piano system uses keyboard keys Q, W, E, R, T, Y, U, I, O, P to play notes.
 
-| Key | Note | Sample File | Playback Speed |
-|-----|------|-------------|----------------|
-| Q | C4 | C4v8.flac | 1.0 |
-| W | D4 | C4v8.flac | 1.1225 |
-| E | E4 | C4v8.flac | 1.2599 |
-| R | F4 | C4v8.flac | 0.9439 |
-| T | G4 | C4v8.flac | 1.0595 |
-| Y | A4 | A4v8.flac | 1.0 |
-| U | B4 | A4v8.flac | 0.9439 |
-| I | C5 | C5v8.flac | 1.0 |
-| O | D5 | C5v8.flac | 1.1225 |
-| P | E5 | C5v8.flac | 1.2599 |
+| Key | Note | Sample File | Playback Speed | Description |
+|-----|------|-------------|----------------|-------------|
+| Q | C# | C4v8.flac | 1.0595 | Black key |
+| W | D# | C4v8.flac | 1.1892 | Black key |
+| E | F# | F#4v8.flac | 1.0 | Black key |
+| R | G# | F#4v8.flac | 1.0595 | Black key |
+| T | A# | A4v8.flac | 1.1892 | Black key |
+| Y | No sound | - | - | Empty |
+| U | No sound | - | - | Empty |
+| I | No sound | - | - | Empty |
+| O | No sound | - | - | Empty |
+| P | No sound | - | - | Empty |
 
 ### Usage
 
 - Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
-- Press any of the above keys to play the corresponding note
+- Press Q, W, E, R, T to play black keys (C#, D#, F#, G#, A#)
+- Y, U, I, O, P produce no sound
 - Keys are debounced - press and release to hear the note again
-- Uses shared audio thread ( OutputStream ) to prevent audio drop warnings
+- Uses shared audio thread to prevent "Dropping OutputStream" warnings
 
 ## 2. Traditional Piano System (ASDFGHJK)
 

From 0d0638dde7d9e74c0387b5b932c45a208a94e103 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:02:24 +0000
Subject: [PATCH 20/29] Update block key mapping: A-M (C3-B3), A-J (C4-B4), Q-U
 (C5-B5)

---
 src/block_key.rs | 132 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 99 insertions(+), 33 deletions(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index efda7f3..e45f60b 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -9,26 +9,58 @@ use once_cell::sync::Lazy as OnceCellLazy;
 use rodio::{Decoder, OutputStreamBuilder, Sink, Source};
 use std::io::Cursor;
 
-/// Musical notes mapped to keyboard keys (black keys).
+/// Musical notes mapped to keyboard keys (C Major scale, C3-B5).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BlockKeyNote {
-    C4Sharp,    // C#
-    D4Sharp,    // D#
-    F4Sharp,    // F#
-    G4Sharp,    // G#
-    A4Sharp,    // A#
-    None,       // No sound
+    C3,
+    D3,
+    E3,
+    F3,
+    G3,
+    A3,
+    B3,
+    C4,
+    D4,
+    E4,
+    F4,
+    G4,
+    A4,
+    B4,
+    C5,
+    D5,
+    E5,
+    F5,
+    G5,
+    A5,
+    B5,
+    None, // No sound
 }
 
 impl BlockKeyNote {
     /// Human-readable name displayed in the bottom message.
     pub fn display_name(self) -> &'static str {
         match self {
-            BlockKeyNote::C4Sharp => "C#",
-            BlockKeyNote::D4Sharp => "D#",
-            BlockKeyNote::F4Sharp => "F#",
-            BlockKeyNote::G4Sharp => "G#",
-            BlockKeyNote::A4Sharp => "A#",
+            BlockKeyNote::C3 => "C3",
+            BlockKeyNote::D3 => "D3",
+            BlockKeyNote::E3 => "E3",
+            BlockKeyNote::F3 => "F3",
+            BlockKeyNote::G3 => "G3",
+            BlockKeyNote::A3 => "A3",
+            BlockKeyNote::B3 => "B3",
+            BlockKeyNote::C4 => "C4",
+            BlockKeyNote::D4 => "D4",
+            BlockKeyNote::E4 => "E4",
+            BlockKeyNote::F4 => "F4",
+            BlockKeyNote::G4 => "G4",
+            BlockKeyNote::A4 => "A4",
+            BlockKeyNote::B4 => "B4",
+            BlockKeyNote::C5 => "C5",
+            BlockKeyNote::D5 => "D5",
+            BlockKeyNote::E5 => "E5",
+            BlockKeyNote::F5 => "F5",
+            BlockKeyNote::G5 => "G5",
+            BlockKeyNote::A5 => "A5",
+            BlockKeyNote::B5 => "B5",
             BlockKeyNote::None => "",
         }
     }
@@ -36,11 +68,15 @@ impl BlockKeyNote {
     /// File name for the Salamander Grand Piano sample used as the source.
     pub fn sample_file(self) -> &'static str {
         match self {
-            BlockKeyNote::C4Sharp => "C4v8.flac",
-            BlockKeyNote::D4Sharp => "C4v8.flac",
-            BlockKeyNote::F4Sharp => "F#4v8.flac",
-            BlockKeyNote::G4Sharp => "F#4v8.flac",
-            BlockKeyNote::A4Sharp => "A4v8.flac",
+            BlockKeyNote::C3 | BlockKeyNote::D3 | BlockKeyNote::E3 => "C3v8.flac",
+            BlockKeyNote::F3 | BlockKeyNote::G3 => "F3v8.flac",
+            BlockKeyNote::A3 | BlockKeyNote::B3 => "A3v8.flac",
+            BlockKeyNote::C4 | BlockKeyNote::D4 | BlockKeyNote::E4 => "C4v8.flac",
+            BlockKeyNote::F4 | BlockKeyNote::G4 => "F#4v8.flac",
+            BlockKeyNote::A4 | BlockKeyNote::B4 => "A4v8.flac",
+            BlockKeyNote::C5 | BlockKeyNote::D5 | BlockKeyNote::E5 => "C5v8.flac",
+            BlockKeyNote::F5 | BlockKeyNote::G5 => "F#5v8.flac",
+            BlockKeyNote::A5 | BlockKeyNote::B5 => "A5v8.flac",
             BlockKeyNote::None => "",
         }
     }
@@ -48,11 +84,27 @@ impl BlockKeyNote {
     /// Speed ratio applied to the source sample to reach the target pitch.
     pub fn playback_speed(self) -> f32 {
         match self {
-            BlockKeyNote::C4Sharp => 1.0595,   // C# = C4 * 2^(1/12)
-            BlockKeyNote::D4Sharp => 1.1892,   // D# = D4 * 2^(1/12)
-            BlockKeyNote::F4Sharp => 1.0,      // F#
-            BlockKeyNote::G4Sharp => 1.0595,   // G# = G4 * 2^(1/12)
-            BlockKeyNote::A4Sharp => 1.1892,   // A# = A4 * 2^(1/12)
+            BlockKeyNote::C3 => 1.0,
+            BlockKeyNote::D3 => 1.1225,
+            BlockKeyNote::E3 => 1.2599,
+            BlockKeyNote::F3 => 0.9439,
+            BlockKeyNote::G3 => 1.0595,
+            BlockKeyNote::A3 => 1.0,
+            BlockKeyNote::B3 => 0.9439,
+            BlockKeyNote::C4 => 1.0,
+            BlockKeyNote::D4 => 1.1225,
+            BlockKeyNote::E4 => 1.2599,
+            BlockKeyNote::F4 => 0.9439,
+            BlockKeyNote::G4 => 1.0595,
+            BlockKeyNote::A4 => 1.0,
+            BlockKeyNote::B4 => 0.9439,
+            BlockKeyNote::C5 => 1.0,
+            BlockKeyNote::D5 => 1.1225,
+            BlockKeyNote::E5 => 1.2599,
+            BlockKeyNote::F5 => 0.9439,
+            BlockKeyNote::G5 => 1.0595,
+            BlockKeyNote::A5 => 1.0,
+            BlockKeyNote::B5 => 0.9439,
             BlockKeyNote::None => 1.0,
         }
     }
@@ -60,16 +112,30 @@ impl BlockKeyNote {
     /// Convert a lowercase character to its corresponding note.
     pub fn from_char(c: char) -> Option<Self> {
         match c.to_ascii_lowercase() {
-            'q' => Some(BlockKeyNote::C4Sharp),   // C#
-            'w' => Some(BlockKeyNote::D4Sharp),   // D#
-            'e' => Some(BlockKeyNote::F4Sharp),   // F#
-            'r' => Some(BlockKeyNote::G4Sharp),   // G#
-            't' => Some(BlockKeyNote::A4Sharp),   // A#
-            'y' => Some(BlockKeyNote::None),      // No sound
-            'u' => Some(BlockKeyNote::None),      // No sound
-            'i' => Some(BlockKeyNote::None),      // No sound
-            'o' => Some(BlockKeyNote::None),      // No sound
-            'p' => Some(BlockKeyNote::None),      // No sound
+            // Lower octave (C3-B3)
+            'z' => Some(BlockKeyNote::C3),
+            'x' => Some(BlockKeyNote::D3),
+            'c' => Some(BlockKeyNote::E3),
+            'v' => Some(BlockKeyNote::F3),
+            'b' => Some(BlockKeyNote::G3),
+            'n' => Some(BlockKeyNote::A3),
+            'm' => Some(BlockKeyNote::B3),
+            // Middle octave (C4-B4)
+            'a' => Some(BlockKeyNote::C4),
+            's' => Some(BlockKeyNote::D4),
+            'd' => Some(BlockKeyNote::E4),
+            'f' => Some(BlockKeyNote::F4),
+            'g' => Some(BlockKeyNote::G4),
+            'h' => Some(BlockKeyNote::A4),
+            'j' => Some(BlockKeyNote::B4),
+            // Upper octave (C5-B5)
+            'q' => Some(BlockKeyNote::C5),
+            'w' => Some(BlockKeyNote::D5),
+            'e' => Some(BlockKeyNote::E5),
+            'r' => Some(BlockKeyNote::F5),
+            't' => Some(BlockKeyNote::G5),
+            'y' => Some(BlockKeyNote::A5),
+            'u' => Some(BlockKeyNote::B5),
             _ => None,
         }
     }
@@ -154,7 +220,7 @@ pub fn play_note(note: BlockKeyNote) -> bool {
     if matches!(note, BlockKeyNote::None) {
         return false;
     }
-    
+
     let sample_file = note.sample_file();
     let speed = note.playback_speed();
     let _ = BLOCK_AUDIO_SENDER.send(AudioCommand::Play {

From 2e420481d866801ee04d807bcc34c1402c186b27 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:02:51 +0000
Subject: [PATCH 21/29] Update PianoKeyboard.md with full keyboard mapping
 (C3-B5)

---
 PianoKeyboard.md | 48 ++++++++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 22 deletions(-)

diff --git a/PianoKeyboard.md b/PianoKeyboard.md
index 3bb534d..32133c2 100644
--- a/PianoKeyboard.md
+++ b/PianoKeyboard.md
@@ -2,28 +2,33 @@
 
 Tinydew features two piano input systems that use the Salamander Grand Piano samples.
 
-## 1. Block Key System (QWERTYUIOP) - Default
-
-The default piano system uses keyboard keys Q, W, E, R, T, Y, U, I, O, P to play notes.
-
-| Key | Note | Sample File | Playback Speed | Description |
-|-----|------|-------------|----------------|-------------|
-| Q | C# | C4v8.flac | 1.0595 | Black key |
-| W | D# | C4v8.flac | 1.1892 | Black key |
-| E | F# | F#4v8.flac | 1.0 | Black key |
-| R | G# | F#4v8.flac | 1.0595 | Black key |
-| T | A# | A4v8.flac | 1.1892 | Black key |
-| Y | No sound | - | - | Empty |
-| U | No sound | - | - | Empty |
-| I | No sound | - | - | Empty |
-| O | No sound | - | - | Empty |
-| P | No sound | - | - | Empty |
+## 1. Block Key System (Full Keyboard)
+
+The block key system uses keys Z through U to play a full range of notes (C3-B5).
+
+### Full Key Mapping
+
+| Key | Note | Sample File | Playback Speed | Key | Note | Sample File | Playback Speed |
+|-----|------|-------------|----------------|-----|------|-------------|----------------|
+| Z | C3 | C3v8.flac | 1.0 | Q | C5 | C5v8.flac | 1.0 |
+| X | D3 | C3v8.flac | 1.1225 | W | D5 | C5v8.flac | 1.1225 |
+| C | E3 | C3v8.flac | 1.2599 | E | E5 | C5v8.flac | 1.2599 |
+| V | F3 | F3v8.flac | 0.9439 | R | F5 | F#5v8.flac | 0.9439 |
+| B | G3 | F3v8.flac | 1.0595 | T | G5 | F#5v8.flac | 1.0595 |
+| N | A3 | A3v8.flac | 1.0 | Y | A5 | A5v8.flac | 1.0 |
+| M | B3 | A3v8.flac | 0.9439 | U | B5 | A5v8.flac | 0.9439 |
+| A | C4 | C4v8.flac | 1.0 | | | | |
+| S | D4 | C4v8.flac | 1.1225 | | | | |
+| D | E4 | C4v8.flac | 1.2599 | | | | |
+| F | F4 | F#4v8.flac | 0.9439 | | | | |
+| G | G4 | F#4v8.flac | 1.0595 | | | | |
+| H | A4 | A4v8.flac | 1.0 | | | | |
+| J | B4 | A4v8.flac | 0.9439 | | | | |
 
 ### Usage
 
 - Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
-- Press Q, W, E, R, T to play black keys (C#, D#, F#, G#, A#)
-- Y, U, I, O, P produce no sound
+- Press any of the above keys to play the corresponding note
 - Keys are debounced - press and release to hear the note again
 - Uses shared audio thread to prevent "Dropping OutputStream" warnings
 
@@ -61,10 +66,9 @@ Both systems use identical audio logic:
 Both systems use the [Salamander Grand Piano](https://github.com/alexholm/salamander-grand-piano-in-rust) samples by Alexander Holm.
 
 Available samples:
-- C4v8.flac (root C4, various speeds for pitch shifting)
-- F#4v8.flac (F#4 for Fa and So notes)
-- A4v8.flac (A4 for La note)
-- C5v8.flac (C5 for higher notes)
+- C3v8.flac, C4v8.flac, C5v8.flac (root C notes, various speeds for pitch shifting)
+- F3v8.flac, F#4v8.flac, F#5v8.flac (F/F# notes)
+- A3v8.flac, A4v8.flac, A5v8.flac (A notes)
 
 ## Requirements
 

From d85f6d300f6e8f2d0ef898447ddc05bb92a4e9f0 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:08:23 +0000
Subject: [PATCH 22/29] Fix block key: use F#3v8.flac instead of F3v8.flac
 (missing sample)

---
 src/block_key.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index e45f60b..f45c5fa 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -69,7 +69,7 @@ impl BlockKeyNote {
     pub fn sample_file(self) -> &'static str {
         match self {
             BlockKeyNote::C3 | BlockKeyNote::D3 | BlockKeyNote::E3 => "C3v8.flac",
-            BlockKeyNote::F3 | BlockKeyNote::G3 => "F3v8.flac",
+            BlockKeyNote::F3 | BlockKeyNote::G3 => "F#3v8.flac",
             BlockKeyNote::A3 | BlockKeyNote::B3 => "A3v8.flac",
             BlockKeyNote::C4 | BlockKeyNote::D4 | BlockKeyNote::E4 => "C4v8.flac",
             BlockKeyNote::F4 | BlockKeyNote::G4 => "F#4v8.flac",

From c02570a70e5d87f15cbf9e9a948b63e11ca29d6b Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:09:53 +0000
Subject: [PATCH 23/29] Increase max concurrent notes from 4 to 8

---
 src/block_key.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index f45c5fa..42b2bce 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -201,7 +201,7 @@ static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLa
             sinks.retain(|s| !s.empty());
 
             // Limit concurrent sinks
-            if sinks.len() > 4 {
+            if sinks.len() > 8 {
                 if let Some(old) = sinks.pop_front() {
                     old.stop();
                 }

From 02c9559f53b08f2e2afa9e63600b20739a47e2bc Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:10:14 +0000
Subject: [PATCH 24/29] Revert max concurrent notes back to 4

---
 src/block_key.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index 42b2bce..f45c5fa 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -201,7 +201,7 @@ static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLa
             sinks.retain(|s| !s.empty());
 
             // Limit concurrent sinks
-            if sinks.len() > 8 {
+            if sinks.len() > 4 {
                 if let Some(old) = sinks.pop_front() {
                     old.stop();
                 }

From 84a8197188b81f491be6b2924961136f2a2bc5c7 Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:13:45 +0000
Subject: [PATCH 25/29] Fix B3 and B5 playback speed: 1.1225 (not 0.9439)

---
 src/block_key.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/block_key.rs b/src/block_key.rs
index f45c5fa..f624a23 100644
--- a/src/block_key.rs
+++ b/src/block_key.rs
@@ -90,7 +90,7 @@ impl BlockKeyNote {
             BlockKeyNote::F3 => 0.9439,
             BlockKeyNote::G3 => 1.0595,
             BlockKeyNote::A3 => 1.0,
-            BlockKeyNote::B3 => 0.9439,
+            BlockKeyNote::B3 => 1.1225,
             BlockKeyNote::C4 => 1.0,
             BlockKeyNote::D4 => 1.1225,
             BlockKeyNote::E4 => 1.2599,
@@ -104,7 +104,7 @@ impl BlockKeyNote {
             BlockKeyNote::F5 => 0.9439,
             BlockKeyNote::G5 => 1.0595,
             BlockKeyNote::A5 => 1.0,
-            BlockKeyNote::B5 => 0.9439,
+            BlockKeyNote::B5 => 1.1225,
             BlockKeyNote::None => 1.0,
         }
     }

From 292137001156a91d08f1fb785ee548fc2591865e Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:17:05 +0000
Subject: [PATCH 26/29] Remove block key system - only use piano key logic
 (A-J)

---
 src/main.rs | 25 ++-----------------------
 1 file changed, 2 insertions(+), 23 deletions(-)

diff --git a/src/main.rs b/src/main.rs
index a93ff1e..852a3f2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,16 +1,14 @@
 #![allow(clippy::needless_range_loop)]
 #![allow(dead_code, unused_imports)]
 
-mod block_key;
 mod mcp;
 mod piano;
 mod savegame;
 mod state;
 mod world;
 
-use crate::block_key::{BlockKeyNote, BlockKeyState, play_note};
 use crate::mcp::handler::ToolResponse;
-use crate::piano::{PianoNote, play_note as piano_play_note};
+use crate::piano::{PianoNote, play_note};
 use crate::state::GameState;
 use crate::world::Direction;
 use clap::Parser;
@@ -463,8 +461,6 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
 
         let _ = crossterm::execute!(std::io::stdout(), EnterAlternateScreen);
 
-        let mut block_key_state = BlockKeyState::new();
-
         loop {
             render(&game);
 
@@ -501,24 +497,11 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                     if guest_at_square_piano {
                         if let Some(note) = PianoNote::from_key_code(key.code) {
                             game.guest_play_piano(note.display_name());
-                            piano_play_note(note);
+                            play_note(note);
                             continue;
                         }
                     }
 
-                    // Block key sound system (QWERTYUIOP) - same piano location
-                    if guest_at_square_piano {
-                        if let KeyCode::Char(c) = key.code {
-                            if let Some(note) = BlockKeyNote::from_char(c) {
-                                if block_key_state.key_down(c) {
-                                    game.message = format!("🎵 {}", note.display_name());
-                                    let _ = play_note(note);
-                                }
-                                continue;
-                            }
-                        }
-                    }
-
                     match key.code {
                         KeyCode::Up => {
                             if game.guest_enabled {
@@ -593,10 +576,6 @@ fn run_interactive_mode() -> Result<(), InteractiveError> {
                                 game.message = game.guest_greeting_message();
                             }
                         }
-                        // Block key key release to allow re-triggering
-                        KeyCode::Char(c) => {
-                            block_key_state.key_up(c);
-                        }
                         _ => {}
                     }
                 }

From e96d783a77052ca51daa17e99b933730ebf0583e Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:17:28 +0000
Subject: [PATCH 27/29] Remove block_key.rs entirely

---
 src/block_key.rs | 259 -----------------------------------------------
 1 file changed, 259 deletions(-)
 delete mode 100644 src/block_key.rs

diff --git a/src/block_key.rs b/src/block_key.rs
deleted file mode 100644
index f624a23..0000000
--- a/src/block_key.rs
+++ /dev/null
@@ -1,259 +0,0 @@
-use std::collections::HashSet;
-use std::collections::VecDeque;
-use std::path::PathBuf;
-use std::sync::mpsc;
-use std::thread;
-
-use crossterm::event::KeyCode;
-use once_cell::sync::Lazy as OnceCellLazy;
-use rodio::{Decoder, OutputStreamBuilder, Sink, Source};
-use std::io::Cursor;
-
-/// Musical notes mapped to keyboard keys (C Major scale, C3-B5).
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub enum BlockKeyNote {
-    C3,
-    D3,
-    E3,
-    F3,
-    G3,
-    A3,
-    B3,
-    C4,
-    D4,
-    E4,
-    F4,
-    G4,
-    A4,
-    B4,
-    C5,
-    D5,
-    E5,
-    F5,
-    G5,
-    A5,
-    B5,
-    None, // No sound
-}
-
-impl BlockKeyNote {
-    /// Human-readable name displayed in the bottom message.
-    pub fn display_name(self) -> &'static str {
-        match self {
-            BlockKeyNote::C3 => "C3",
-            BlockKeyNote::D3 => "D3",
-            BlockKeyNote::E3 => "E3",
-            BlockKeyNote::F3 => "F3",
-            BlockKeyNote::G3 => "G3",
-            BlockKeyNote::A3 => "A3",
-            BlockKeyNote::B3 => "B3",
-            BlockKeyNote::C4 => "C4",
-            BlockKeyNote::D4 => "D4",
-            BlockKeyNote::E4 => "E4",
-            BlockKeyNote::F4 => "F4",
-            BlockKeyNote::G4 => "G4",
-            BlockKeyNote::A4 => "A4",
-            BlockKeyNote::B4 => "B4",
-            BlockKeyNote::C5 => "C5",
-            BlockKeyNote::D5 => "D5",
-            BlockKeyNote::E5 => "E5",
-            BlockKeyNote::F5 => "F5",
-            BlockKeyNote::G5 => "G5",
-            BlockKeyNote::A5 => "A5",
-            BlockKeyNote::B5 => "B5",
-            BlockKeyNote::None => "",
-        }
-    }
-
-    /// File name for the Salamander Grand Piano sample used as the source.
-    pub fn sample_file(self) -> &'static str {
-        match self {
-            BlockKeyNote::C3 | BlockKeyNote::D3 | BlockKeyNote::E3 => "C3v8.flac",
-            BlockKeyNote::F3 | BlockKeyNote::G3 => "F#3v8.flac",
-            BlockKeyNote::A3 | BlockKeyNote::B3 => "A3v8.flac",
-            BlockKeyNote::C4 | BlockKeyNote::D4 | BlockKeyNote::E4 => "C4v8.flac",
-            BlockKeyNote::F4 | BlockKeyNote::G4 => "F#4v8.flac",
-            BlockKeyNote::A4 | BlockKeyNote::B4 => "A4v8.flac",
-            BlockKeyNote::C5 | BlockKeyNote::D5 | BlockKeyNote::E5 => "C5v8.flac",
-            BlockKeyNote::F5 | BlockKeyNote::G5 => "F#5v8.flac",
-            BlockKeyNote::A5 | BlockKeyNote::B5 => "A5v8.flac",
-            BlockKeyNote::None => "",
-        }
-    }
-
-    /// Speed ratio applied to the source sample to reach the target pitch.
-    pub fn playback_speed(self) -> f32 {
-        match self {
-            BlockKeyNote::C3 => 1.0,
-            BlockKeyNote::D3 => 1.1225,
-            BlockKeyNote::E3 => 1.2599,
-            BlockKeyNote::F3 => 0.9439,
-            BlockKeyNote::G3 => 1.0595,
-            BlockKeyNote::A3 => 1.0,
-            BlockKeyNote::B3 => 1.1225,
-            BlockKeyNote::C4 => 1.0,
-            BlockKeyNote::D4 => 1.1225,
-            BlockKeyNote::E4 => 1.2599,
-            BlockKeyNote::F4 => 0.9439,
-            BlockKeyNote::G4 => 1.0595,
-            BlockKeyNote::A4 => 1.0,
-            BlockKeyNote::B4 => 0.9439,
-            BlockKeyNote::C5 => 1.0,
-            BlockKeyNote::D5 => 1.1225,
-            BlockKeyNote::E5 => 1.2599,
-            BlockKeyNote::F5 => 0.9439,
-            BlockKeyNote::G5 => 1.0595,
-            BlockKeyNote::A5 => 1.0,
-            BlockKeyNote::B5 => 1.1225,
-            BlockKeyNote::None => 1.0,
-        }
-    }
-
-    /// Convert a lowercase character to its corresponding note.
-    pub fn from_char(c: char) -> Option<Self> {
-        match c.to_ascii_lowercase() {
-            // Lower octave (C3-B3)
-            'z' => Some(BlockKeyNote::C3),
-            'x' => Some(BlockKeyNote::D3),
-            'c' => Some(BlockKeyNote::E3),
-            'v' => Some(BlockKeyNote::F3),
-            'b' => Some(BlockKeyNote::G3),
-            'n' => Some(BlockKeyNote::A3),
-            'm' => Some(BlockKeyNote::B3),
-            // Middle octave (C4-B4)
-            'a' => Some(BlockKeyNote::C4),
-            's' => Some(BlockKeyNote::D4),
-            'd' => Some(BlockKeyNote::E4),
-            'f' => Some(BlockKeyNote::F4),
-            'g' => Some(BlockKeyNote::G4),
-            'h' => Some(BlockKeyNote::A4),
-            'j' => Some(BlockKeyNote::B4),
-            // Upper octave (C5-B5)
-            'q' => Some(BlockKeyNote::C5),
-            'w' => Some(BlockKeyNote::D5),
-            'e' => Some(BlockKeyNote::E5),
-            'r' => Some(BlockKeyNote::F5),
-            't' => Some(BlockKeyNote::G5),
-            'y' => Some(BlockKeyNote::A5),
-            'u' => Some(BlockKeyNote::B5),
-            _ => None,
-        }
-    }
-
-    /// Converts an interactive key press into a `BlockKeyNote`.
-    pub fn from_key_code(key: KeyCode) -> Option<Self> {
-        if let KeyCode::Char(ch) = key {
-            Self::from_char(ch)
-        } else {
-            None
-        }
-    }
-}
-
-/// Audio command for the shared audio thread.
-#[derive(Debug)]
-enum AudioCommand {
-    Play {
-        sample_file: String,
-        speed: f32,
-    },
-}
-
-/// Shared audio sender for all block key notes.
-/// Uses a single OutputStream that lives for the duration of the program.
-#[cfg(feature = "interactive")]
-static BLOCK_AUDIO_SENDER: OnceCellLazy<mpsc::Sender<AudioCommand>> = OnceCellLazy::new(|| {
-    let (tx, rx) = mpsc::channel::<AudioCommand>();
-
-    thread::spawn(move || {
-        let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
-            eprintln!("[BlockKey] Failed to open audio stream");
-            return;
-        };
-        let mixer = stream.mixer().clone();
-
-        let mut sinks: VecDeque<Sink> = VecDeque::new();
-
-        for cmd in rx {
-            let (sample_file, speed) = match cmd {
-                AudioCommand::Play { sample_file, speed } => (sample_file, speed),
-            };
-
-            let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-                .join("..")
-                .join("salamander-grand-piano-in-rust")
-                .join("Samples")
-                .join(&sample_file);
-
-            let source_data = std::fs::read(&path).ok();
-
-            if let Some(source_data) = source_data {
-                let cursor = Cursor::new(source_data);
-                if let Ok(source) = Decoder::new(cursor) {
-                    let source = source.speed(speed);
-                    let sink = Sink::connect_new(&mixer);
-                    sink.append(source);
-                    sinks.push_back(sink);
-                }
-            }
-
-            // Clean up empty sinks
-            sinks.retain(|s| !s.empty());
-
-            // Limit concurrent sinks
-            if sinks.len() > 4 {
-                if let Some(old) = sinks.pop_front() {
-                    old.stop();
-                }
-            }
-        }
-    });
-
-    tx
-});
-
-/// Play a note using the shared audio thread.
-/// Returns true if note should be displayed in message, false otherwise.
-#[cfg(feature = "interactive")]
-pub fn play_note(note: BlockKeyNote) -> bool {
-    // Skip sound for None notes
-    if matches!(note, BlockKeyNote::None) {
-        return false;
-    }
-
-    let sample_file = note.sample_file();
-    let speed = note.playback_speed();
-    let _ = BLOCK_AUDIO_SENDER.send(AudioCommand::Play {
-        sample_file: sample_file.to_string(),
-        speed,
-    });
-    true
-}
-
-#[cfg(not(feature = "interactive"))]
-pub fn play_note(_note: BlockKeyNote) {
-    // No-op when audio is disabled
-}
-
-/// Tracks currently held keys to debounce key-repeat events.
-pub struct BlockKeyState {
-    pressed: HashSet<char>,
-}
-
-impl BlockKeyState {
-    pub fn new() -> Self {
-        Self {
-            pressed: HashSet::new(),
-        }
-    }
-
-    /// Returns true if this is a fresh press (not a repeat).
-    pub fn key_down(&mut self, c: char) -> bool {
-        self.pressed.insert(c.to_ascii_lowercase())
-    }
-
-    /// Call on key release to allow re-triggering.
-    pub fn key_up(&mut self, c: char) {
-        self.pressed.remove(&c.to_ascii_lowercase());
-    }
-}

From c705cc97bfe70585ef93f313c9ea1277adf4e04a Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:18:20 +0000
Subject: [PATCH 28/29] Update PianoNote to support all 3 octaves (C3-B5) via
 keys Z-U

---
 src/piano.rs | 153 ++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 108 insertions(+), 45 deletions(-)

diff --git a/src/piano.rs b/src/piano.rs
index 71be692..ddfc80b 100644
--- a/src/piano.rs
+++ b/src/piano.rs
@@ -1,54 +1,101 @@
 use crossterm::event::KeyCode;
 
-/// Represents a piano note that the guest can play at the North Square piano.
+/// Represents a piano note across 3 octaves (C3-B5).
 #[derive(Debug, Clone, Copy)]
 pub enum PianoNote {
-    Do,
-    Re,
-    Mi,
-    Fa,
-    So,
-    La,
-    Si,
-    DoSharp,
+    // Lower Octave (C3-B3)
+    Do3,
+    Re3,
+    Mi3,
+    Fa3,
+    So3,
+    La3,
+    Si3,
+    // Middle Octave (C4-B4)
+    Do4,
+    Re4,
+    Mi4,
+    Fa4,
+    So4,
+    La4,
+    Si4,
+    // Upper Octave (C5-B5)
+    Do5,
+    Re5,
+    Mi5,
+    Fa5,
+    So5,
+    La5,
+    Si5,
 }
 
 impl PianoNote {
     /// Human-readable name displayed in the bottom message.
     pub fn display_name(self) -> &'static str {
         match self {
-            PianoNote::Do => "Do",
-            PianoNote::Re => "Re",
-            PianoNote::Mi => "Mi",
-            PianoNote::Fa => "Fa",
-            PianoNote::So => "So",
-            PianoNote::La => "La",
-            PianoNote::Si => "Si",
-            PianoNote::DoSharp => "DO#",
+            PianoNote::Do3 => "C3",
+            PianoNote::Re3 => "D3",
+            PianoNote::Mi3 => "E3",
+            PianoNote::Fa3 => "F3",
+            PianoNote::So3 => "G3",
+            PianoNote::La3 => "A3",
+            PianoNote::Si3 => "B3",
+            PianoNote::Do4 => "C4",
+            PianoNote::Re4 => "D4",
+            PianoNote::Mi4 => "E4",
+            PianoNote::Fa4 => "F4",
+            PianoNote::So4 => "G4",
+            PianoNote::La4 => "A4",
+            PianoNote::Si4 => "B4",
+            PianoNote::Do5 => "C5",
+            PianoNote::Re5 => "D5",
+            PianoNote::Mi5 => "E5",
+            PianoNote::Fa5 => "F5",
+            PianoNote::So5 => "G5",
+            PianoNote::La5 => "A5",
+            PianoNote::Si5 => "B5",
         }
     }
 
     /// File name for the Salamander Grand Piano sample used as the source.
     pub fn sample_file(self) -> &'static str {
         match self {
-            PianoNote::Do | PianoNote::Re | PianoNote::Mi => "C4v8.flac",
-            PianoNote::Fa | PianoNote::So => "F#4v8.flac",
-            PianoNote::La => "A4v8.flac",
-            PianoNote::Si | PianoNote::DoSharp => "C5v8.flac",
+            PianoNote::Do3 | PianoNote::Re3 | PianoNote::Mi3 => "C3v8.flac",
+            PianoNote::Fa3 | PianoNote::So3 => "F#3v8.flac",
+            PianoNote::La3 | PianoNote::Si3 => "A3v8.flac",
+            PianoNote::Do4 | PianoNote::Re4 | PianoNote::Mi4 => "C4v8.flac",
+            PianoNote::Fa4 | PianoNote::So4 => "F#4v8.flac",
+            PianoNote::La4 | PianoNote::Si4 => "A4v8.flac",
+            PianoNote::Do5 | PianoNote::Re5 | PianoNote::Mi5 => "C5v8.flac",
+            PianoNote::Fa5 | PianoNote::So5 => "F#5v8.flac",
+            PianoNote::La5 | PianoNote::Si5 => "A5v8.flac",
         }
     }
 
     /// Speed ratio applied to the source sample to reach the target pitch.
     pub fn playback_speed(self) -> f32 {
         match self {
-            PianoNote::Do => 1.0,
-            PianoNote::Re => 1.1225,
-            PianoNote::Mi => 1.2599,
-            PianoNote::Fa => 0.9439,
-            PianoNote::So => 1.0595,
-            PianoNote::La => 1.0,
-            PianoNote::Si => 0.9439,
-            PianoNote::DoSharp => 1.0,
+            PianoNote::Do3 => 1.0,
+            PianoNote::Re3 => 1.1225,
+            PianoNote::Mi3 => 1.2599,
+            PianoNote::Fa3 => 0.9439,
+            PianoNote::So3 => 1.0595,
+            PianoNote::La3 => 1.0,
+            PianoNote::Si3 => 1.1225,
+            PianoNote::Do4 => 1.0,
+            PianoNote::Re4 => 1.1225,
+            PianoNote::Mi4 => 1.2599,
+            PianoNote::Fa4 => 0.9439,
+            PianoNote::So4 => 1.0595,
+            PianoNote::La4 => 1.0,
+            PianoNote::Si4 => 1.1225,
+            PianoNote::Do5 => 1.0,
+            PianoNote::Re5 => 1.1225,
+            PianoNote::Mi5 => 1.2599,
+            PianoNote::Fa5 => 0.9439,
+            PianoNote::So5 => 1.0595,
+            PianoNote::La5 => 1.0,
+            PianoNote::Si5 => 1.1225,
         }
     }
 
@@ -56,14 +103,30 @@ impl PianoNote {
     pub fn from_key_code(key: KeyCode) -> Option<Self> {
         if let KeyCode::Char(ch) = key {
             match ch.to_ascii_lowercase() {
-                'a' => Some(PianoNote::Do),
-                's' => Some(PianoNote::Re),
-                'd' => Some(PianoNote::Mi),
-                'f' => Some(PianoNote::Fa),
-                'g' => Some(PianoNote::So),
-                'h' => Some(PianoNote::La),
-                'j' => Some(PianoNote::Si),
-                'k' => Some(PianoNote::DoSharp),
+                // Lower Octave (Z-M)
+                'z' => Some(PianoNote::Do3),
+                'x' => Some(PianoNote::Re3),
+                'c' => Some(PianoNote::Mi3),
+                'v' => Some(PianoNote::Fa3),
+                'b' => Some(PianoNote::So3),
+                'n' => Some(PianoNote::La3),
+                'm' => Some(PianoNote::Si3),
+                // Middle Octave (A-J)
+                'a' => Some(PianoNote::Do4),
+                's' => Some(PianoNote::Re4),
+                'd' => Some(PianoNote::Mi4),
+                'f' => Some(PianoNote::Fa4),
+                'g' => Some(PianoNote::So4),
+                'h' => Some(PianoNote::La4),
+                'j' => Some(PianoNote::Si4),
+                // Upper Octave (Q-U)
+                'q' => Some(PianoNote::Do5),
+                'w' => Some(PianoNote::Re5),
+                'e' => Some(PianoNote::Mi5),
+                'r' => Some(PianoNote::Fa5),
+                't' => Some(PianoNote::So5),
+                'y' => Some(PianoNote::La5),
+                'u' => Some(PianoNote::Si5),
                 _ => None,
             }
         } else {
@@ -92,7 +155,7 @@ mod audio {
             .join(note.sample_file());
         let speed = note.playback_speed();
         let source_data = std::fs::read(&path).ok();
-        
+
         if let Some(source_data) = source_data {
             // Send the note info to the audio thread via channel
             let _ = AUDIO_SENDER.send(AudioCommand::Play {
@@ -114,7 +177,7 @@ mod audio {
     // Channel sender for audio commands
     static AUDIO_SENDER: once_cell::sync::Lazy<mpsc::Sender<AudioCommand>> = once_cell::sync::Lazy::new(|| {
         let (tx, rx) = mpsc::channel::<AudioCommand>();
-        
+
         // Spawn audio thread that owns the OutputStream
         thread::spawn(move || {
             let Ok(stream) = OutputStreamBuilder::open_default_stream() else {
@@ -122,9 +185,9 @@ mod audio {
                 return;
             };
             let mixer = stream.mixer().clone();
-            
+
             let mut sinks: VecDeque<Sink> = VecDeque::new();
-            
+
             for cmd in rx {
                 match cmd {
                     AudioCommand::Play { source_data, speed } => {
@@ -133,7 +196,7 @@ mod audio {
                             let source = source
                                 .speed(speed)
                                 .fade_in(std::time::Duration::from_millis(8));
-                            
+
                             let sink = Sink::connect_new(&mixer);
                             sink.append(source);
                             sinks.push_back(sink);
@@ -145,10 +208,10 @@ mod audio {
                         }
                     }
                 }
-                
+
                 // Clean up empty sinks
                 sinks.retain(|s| !s.empty());
-                
+
                 // Limit concurrent sinks
                 if sinks.len() > 4 {
                     if let Some(old) = sinks.pop_front() {
@@ -157,7 +220,7 @@ mod audio {
                 }
             }
         });
-        
+
         tx
     });
 }

From e2b0ad1efeaf8b688ba540f1b614244f198cbfaa Mon Sep 17 00:00:00 2001
From: Laze <laze@openclaw.dev>
Date: Thu, 26 Mar 2026 18:18:48 +0000
Subject: [PATCH 29/29] Update PianoNote to support all 3 octaves (C3-B5) via
 keys Z-U

- Lower Octave (Z-M): C3-B3

- Middle Octave (A-J): C4-B4

- Upper Octave (Q-U): C5-B5

All use PianoNote system with correct sample files and playback speeds

Co-authored-by: Melo <5381032473@telegram>

Co-authored-by: OpenClaw <support@openclaw.dev>
---
 PianoKeyboard.md | 87 ++++++++++++++++++++----------------------------
 1 file changed, 36 insertions(+), 51 deletions(-)

diff --git a/PianoKeyboard.md b/PianoKeyboard.md
index 32133c2..764fca8 100644
--- a/PianoKeyboard.md
+++ b/PianoKeyboard.md
@@ -1,74 +1,59 @@
 # Piano Keyboard Mapping
 
-Tinydew features two piano input systems that use the Salamander Grand Piano samples.
+Tinydew uses the PianoNote system to play notes across 3 octaves using the Salamander Grand Piano samples.
 
-## 1. Block Key System (Full Keyboard)
+## Keyboard Mapping
 
-The block key system uses keys Z through U to play a full range of notes (C3-B5).
+| Key | Note | Key | Note | Key | Note |
+|-----|------|-----|------|-----|------|
+| Z | C3 | A | C4 | Q | C5 |
+| X | D3 | S | D4 | W | D5 |
+| C | E3 | D | E4 | E | E5 |
+| V | F3 | F | F4 | R | F5 |
+| B | G3 | G | G4 | T | G5 |
+| N | A3 | H | A4 | Y | A5 |
+| M | B3 | J | B4 | U | B5 |
 
-### Full Key Mapping
+### Octave Breakdown
 
-| Key | Note | Sample File | Playback Speed | Key | Note | Sample File | Playback Speed |
-|-----|------|-------------|----------------|-----|------|-------------|----------------|
-| Z | C3 | C3v8.flac | 1.0 | Q | C5 | C5v8.flac | 1.0 |
-| X | D3 | C3v8.flac | 1.1225 | W | D5 | C5v8.flac | 1.1225 |
-| C | E3 | C3v8.flac | 1.2599 | E | E5 | C5v8.flac | 1.2599 |
-| V | F3 | F3v8.flac | 0.9439 | R | F5 | F#5v8.flac | 0.9439 |
-| B | G3 | F3v8.flac | 1.0595 | T | G5 | F#5v8.flac | 1.0595 |
-| N | A3 | A3v8.flac | 1.0 | Y | A5 | A5v8.flac | 1.0 |
-| M | B3 | A3v8.flac | 0.9439 | U | B5 | A5v8.flac | 0.9439 |
-| A | C4 | C4v8.flac | 1.0 | | | | |
-| S | D4 | C4v8.flac | 1.1225 | | | | |
-| D | E4 | C4v8.flac | 1.2599 | | | | |
-| F | F4 | F#4v8.flac | 0.9439 | | | | |
-| G | G4 | F#4v8.flac | 1.0595 | | | | |
-| H | A4 | A4v8.flac | 1.0 | | | | |
-| J | B4 | A4v8.flac | 0.9439 | | | | |
+**Lower Octave (Z-M):** C3 to B3
+- Z, X, C → C3v8.flac
+- V, B → F#3v8.flac
+- N, M → A3v8.flac
 
-### Usage
+**Middle Octave (A-J):** C4 to B4
+- A, S, D → C4v8.flac
+- F, G → F#4v8.flac
+- H, J → A4v8.flac
 
-- Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
-- Press any of the above keys to play the corresponding note
-- Keys are debounced - press and release to hear the note again
-- Uses shared audio thread to prevent "Dropping OutputStream" warnings
-
-## 2. Traditional Piano System (ASDFGHJK)
-
-A secondary piano system uses keys A, S, D, F, G, H, J, K.
+**Upper Octave (Q-U):** C5 to B5
+- Q, W, E → C5v8.flac
+- R, T → F#5v8.flac
+- Y, U → A5v8.flac
 
-| Key | Note | Sample File | Playback Speed |
-|-----|------|-------------|----------------|
-| A | Do (C4) | C4v8.flac | 1.0 |
-| S | Re (D4) | C4v8.flac | 1.1225 |
-| D | Mi (E4) | C4v8.flac | 1.2599 |
-| F | Fa (F4) | F#4v8.flac | 0.9439 |
-| G | So (G4) | F#4v8.flac | 1.0595 |
-| H | La (A4) | A4v8.flac | 1.0 |
-| J | Si (B4) | A4v8.flac | 0.9439 |
-| K | Do# (C5) | C5v8.flac | 1.0 |
+## Usage
 
-### Usage
-
-- Same position requirement: guest at (6, 3) on Square map
-- Uses the same `PianoNote` type as the traditional keyboard layout
+- Guest must be at position (6, 3) on the Square map (directly in front of the piano at 6, 2)
+- Press any of the above keys to play the corresponding note
+- Notes are debounced - press and release to hear the note again
+- Uses shared audio thread with max 4 concurrent notes
 
 ## Audio Implementation
 
-Both systems use identical audio logic:
-
 - **Shared OutputStream**: A single background thread owns the audio stream
 - **mpsc channel**: Key presses send `AudioCommand::Play` messages
 - **Sink cleanup**: Automatic cleanup of finished notes, max 4 concurrent sinks
 - **Sample format**: .flac files from Salamander Grand Piano project
+- **Pitch shifting**: Uses playback speed ratios to transpose samples
 
 ## Sound Source
 
-Both systems use the [Salamander Grand Piano](https://github.com/alexholm/salamander-grand-piano-in-rust) samples by Alexander Holm.
+Uses the [Salamander Grand Piano](https://github.com/alexholm/salamander-grand-piano-in-rust) samples by Alexander Holm.
 
 Available samples:
-- C3v8.flac, C4v8.flac, C5v8.flac (root C notes, various speeds for pitch shifting)
-- F3v8.flac, F#4v8.flac, F#5v8.flac (F/F# notes)
-- A3v8.flac, A4v8.flac, A5v8.flac (A notes)
+- C3v8.flac, C4v8.flac, C5v8.flac
+- F#3v8.flac, F#4v8.flac, F#5v8.flac
+- A3v8.flac, A4v8.flac, A5v8.flac
 
 ## Requirements
 
@@ -91,5 +76,5 @@ cargo run --features interactive
 ## Troubleshooting
 
 If you see "Dropping OutputStream" warnings:
-- Ensure only one audio stream is created (fixed in recent versions)
-- The block key system now uses a shared OutputStream for all notes
+- Ensure only one audio stream is created
+- The piano system uses a shared OutputStream for all notes