How do I list available songs?

Run ./play-music list to see songs in MUSIC_DIR.

How do I play a specific song?

Run ./play-music , e.g., ./play-music song.mp3; ensure the file exists in MUSIC_DIR or set MUSIC_DIR accordingly.

How do I stop playback or shut down the server?

Use ./play-music stop to stop playback, or ./play-music server-stop to stop the background server; you can also kill the music-server.py process if needed.

Play Local Music

Scanned

@awspace

npx machina-cli add skill @awspace/play-music --openclaw

Files (1)

SKILL.md

3.6 KB

🎵 Play Music Skill

Controlled music player with pause/resume/stop support
Single entry point, background server for full control

Quick Start

Place music files in a music folder (default) or set MUSIC_DIR environment variable
Install pygame (recommended for full control): pip install pygame
Use: ./play-music play

Single Entry Point

The skill has one clear entry point: ./play-music

Command Interface

./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

Examples

# 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

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:

pip install pygame

2. Add Music Files

Place your music files in:

Default: ./music (relative to script location)
Custom: Set MUSIC_DIR environment variable

3. Configuration

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

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

How It Works

The skill uses a clean client-server architecture:

play-music - Single entry point (Python script combining client functionality)
music-server.py - Background server that handles music playback
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:

pkill -f "music-server.py"
./play-music server-start

File Structure

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

Clean and minimal - No redundant files, clear structure.

Integration with OpenClaw

When this skill is registered with OpenClaw, use it for music playback tasks. The skill provides the knowledge and tools to control music playback with pause/resume/stop support.

Source

git clone https://clawhub.ai/awspace/play-musicView on GitHub

Overview

Play Music is a single-entry, client-server music player for local playback. It can list available songs, play a default or specified track, and control playback with pause, resume, stop, and status commands. It uses Pygame mixer for high-quality audio and auto-starts/stops the server to save resources.

How This Skill Works

The skill exposes a single entry point ./play-music that acts as a client to a background music-server.py. The server handles all playback using the Pygame mixer, enabling pause/resume/stop and status queries. It is resource-efficient: the server auto-starts when playback begins and auto-stops when music ends, with MUSIC_DIR and DEFAULT_SONG configuring location and fallback.

When to Use It

You want to play local audio files from a folder without a GUI.
You need to quickly see which songs are available in MUSIC_DIR.
You want precise playback controls (play, pause, resume, stop) during a session.
You're running headless or in an automation context and want a lightweight background music player.
You prefer a single, consistent entry point for music tasks across platforms (macOS/Windows/Linux).

Quick Start

Step 1: Place music files in a music folder (default) or set MUSIC_DIR environment variable
Step 2: Install pygame (recommended) with: pip install pygame
Step 3: Run a sample command, e.g., ./play-music play, to verify playback

Best Practices

Ensure MUSIC_DIR exists and contains your audio files.
Set DEFAULT_SONG to a valid file that exists in MUSIC_DIR for fallback playback.
Install pygame (pip install pygame) for full control over playback.
Use explicit commands (play, list, pause, resume, stop, status) rather than invoking files directly.
If running long sessions, rely on the server auto-start/auto-stop or manage lifecycle with server-start/server-stop.

Example Use Cases

./play-music list
./play-music play
./play-music song.mp3
./play-music pause
./play-music server-start

Frequently Asked Questions

Add this skill to your agents