./play-music help          - Show this help
./play-music list          - List available songs
./play-music play          - Play default song
./play-music pause         - Pause currently playing music
./play-music resume        - Resume paused music
./play-music stop          - Stop currently playing music
./play-music status        - Show playback status
./play-music <filename>    - Play specific song (e.g., song.mp3)
./play-music server-start  - Start music server manually
./play-music server-stop   - Stop music server

## Features

✅ **Single entry point** - No confusion about which script to use  
✅ **Full playback control** - Play, pause, resume, stop  
✅ **Resource-efficient** - Server auto-starts when needed, auto-stops when music stops  
✅ **Clean architecture** - Client-server separation  
✅ **Pygame-based** - High quality audio playback  
✅ **Cross-platform** - macOS/Windows/Linux compatible  

## Setup

### 1. Install Pygame (Recommended)
For full pause/resume/stop control:

### 2. Add Music Files
Place your music files in:
- Default: `./music` (relative to script location)
- Custom: Set `MUSIC_DIR` environment variable

### 3. Configuration

## How It Works

The skill uses a clean client-server architecture:

1. **`play-music`** - Single entry point (Python script combining client functionality)
2. **`music-server.py`** - Background server that handles music playback
3. **Pygame mixer** - For high-quality audio with full control

**Resource-efficient design:** The server auto-starts when you play music and auto-shuts down when you stop music. This saves system resources while maintaining the convenience of the client-server architecture.

## Troubleshooting

**"No music playing" when trying to pause/resume/stop**  
Start playing music first: `./play-music play`

**"Music directory not found"**  
Create the directory: `mkdir music` or set `MUSIC_DIR` environment variable

**"Pygame not installed"**  
Install it: `pip install pygame`

**Server won't start**  
Check if port 12346 is available, or kill existing servers:

# Play the default song
./play-music play

# Play a specific song
./play-music song.mp3

# Control playback
./play-music pause
./play-music resume
./play-music stop

# See what's available
./play-music list

# Set custom music directory
export MUSIC_DIR="/path/to/your/music"

# Set default song name
export DEFAULT_SONG="my-song.mp3"

play-music/
├── play-music           # Single entry point (Python script)
├── music-server.py      # Background server
├── SKILL.md            # This documentation
├── README.md           # User documentation
├── _meta.json          # Skill metadata
└── .gitignore          # Git ignore file