# Piano Player Test Game

I've created a standalone 2-octave piano player and integrated it into the feed for testing!

## What's Been Built

### ✅ Piano Player App (`/games-test`)
- **Route**: `http://localhost:3002/games-test`
- **Independent Layout**: Completely separate from main app layout
- **2 Octaves**: C4 to B5 (24 keys including black keys)
- **Web Audio API**: Real piano-like sounds using triangle wave synthesis
- **ADSR Envelope**: Attack-Decay-Sustain-Release for realistic piano sound
- **Interactive**: Click or tap keys to play notes
- **Visual Feedback**: Keys animate when pressed
- **PostMessage Integration**: Notifies parent window when game starts

### ✅ Feed Integration
- **Test Game Card**: Automatically injected at the top of the feed
- **Dynamic Port Detection**: Works on any localhost port
- **Iframe Embedded**: Fully sandboxed and secure
- **Cover Image**: Beautiful piano image from Unsplash

## How to Test

### 1. Make Sure Both Servers Are Running

**Terminal 1 - Convex (port 3000):**
```bash
npx convex dev
```

**Terminal 2 - Next.js (port 3002):**
```bash
npm run dev
# Already running at http://localhost:3002
```

### 2. View the Piano in the Feed

Open your browser to:
```
http://localhost:3002
```

You'll see:
- **Piano Player (Test)** card at the top of the feed
- Click "Open" to see it in a dedicated page
- Or interact directly in the iframe card

### 3. Play the Piano

**Direct Access:**
```
http://localhost:3002/games-test
```

**How to Use:**
- Click anywhere to enable Web Audio (browser requirement)
- Click or tap piano keys to play notes
- Multiple keys can be pressed simultaneously
- Each key shows its note name (C4, D4, etc.)
- White keys are natural notes, black keys are sharps/flats

### 4. Test PostMessage API

Open browser DevTools Console and watch for:
```javascript
// When you first click a piano key:
{
  type: "game:start",
  slug: "piano-test"
}
```

## Technical Implementation

### Audio System
```typescript
- Oscillator Type: Triangle wave (piano-like timbre)
- ADSR Envelope:
  - Attack: 10ms (quick key press)
  - Decay: 90ms (transition to sustain)
  - Sustain: 0.1 (holds while key is pressed)
  - Release: 100ms (fade out when released)
```

### Visual Design
- **Gradient Background**: Purple to indigo
- **Responsive Keys**: Scale on press
- **Touch Support**: Works on mobile devices
- **Accessibility**: Note labels on each key

### Integration with Feed
```typescript
// app/page.tsx - Lines 94-118
// Test game is dynamically injected using useMemo
// Automatically detects current port for srcUrl
```

## File Structure

```
app/
├── games-test/
│   ├── layout.tsx        # Independent layout (no nav/ConvexProvider)
│   └── page.tsx          # Piano player component
└── page.tsx              # Feed with injected test game

lib/
└── types.ts              # Updated Game interface with _creationTime
```

## Features Demonstrated

### ✅ Iframe Embedding
- Test game loads in sandboxed iframe
- No CORS issues with same-origin
- Proper sandbox permissions for audio

### ✅ Independent Layout
- Games-test route has its own layout
- No navigation, no headers, no footers
- Clean fullscreen game experience

### ✅ Web Audio API
- AudioContext initialization on user interaction
- Multiple oscillators for polyphony
- Gain nodes for volume control
- ADSR envelope for realistic piano sound

### ✅ PostMessage Communication
- Game notifies parent when started
- Ready for future score tracking
- Can receive pause/resume commands from host

## Next Steps

### Add to Feed Permanently
To make this game permanent (not just for testing):

```bash
npx convex run admin:seedGame \
  '{
    "title": "Piano Player",
    "slug": "piano-player",
    "srcUrl": "/games-test",
    "runtime": "external",
    "description": "A 2-octave piano player",
    "tags": ["piano", "music", "interactive"]
  }'
```

Then remove the test game injection from `app/page.tsx` (lines 94-118).

### Enhancements
- [ ] Add keyboard shortcuts (Q-I for notes)
- [ ] Add sustain pedal
- [ ] Record and playback functionality
- [ ] Different instrument sounds
- [ ] Visual music notation display
- [ ] MIDI input support

## Troubleshooting

### No Sound?
- Click anywhere in the piano to enable Web Audio
- Check browser console for audio errors
- Make sure audio isn't muted

### Iframe Not Loading?
- Check that Next.js dev server is running on correct port
- Open browser console for CORS errors
- Try accessing `/games-test` directly

### Port 3002 Instead of 3000?
- This is normal - Convex dev uses port 3000
- The feed automatically detects the correct port
- Everything works the same on any port

---

**Ready to test!** Open http://localhost:3002 and start playing! 🎹🎵