Play Local Music

Control local music playback with play, pause, resume, stop commands; supports listing and playing specified songs from a configured music directory.

Security Scan

The code and docs mostly match a local music player, but there are inconsistencies (the advertised entry-point script is missing) and a minor security/robustness issue (world-writable lock file) that warrant review before installing.

Purpose & Capability

The skill claims a single entry point './play-music' and documents a client/server architecture, but the package files do not include the 'play-music' client script referenced throughout README/SKILL.md/SETUP.md — only music-server.py is present. Aside from that missing client, the code (pygame-based local playback, local TCP control on 127.0.0.1:12346) is coherent with the stated purpose of playing local music.

Instruction Scope

SKILL.md instructs you to run './play-music' and configure MUSIC_DIR/MUSIC_LOCK_FILE; the runtime server code listens on localhost and operates only on the local music directory. However, because the documented client entry-point is not included, following the instructions as-is will fail or require running music-server.py directly. Instructions do not attempt to read unrelated system data or exfiltrate network data — they are narrowly scoped to local playback control.

Install Mechanism

No install script is provided (instruction-only with a bundled Python server file). The only recommended dependency is pygame via pip, which is reasonable and declared. No remote downloads, URL-based installers, or binaries are fetched by the skill itself.

Credentials

The skill does not require credentials or external service tokens and only uses environment variables for MUSIC_DIR, DEFAULT_SONG, and MUSIC_LOCK_FILE (all declared in metadata). A minor concern: the server creates a lock file at /tmp/music_player.lock by default and sets its permissions to 0o666 (world-writable/readable). That is unnecessary for a local-only server and can introduce race/symlink or tampering risks if an attacker can control the filesystem namespace. The code allows overriding the lock file path via MUSIC_LOCK_FILE, which is convenient but also means a misconfigured environment could cause the server to overwrite an unexpected path.

Persistence & Privilege

The skill does not request 'always: true' or system-wide privileges. It runs a local server bound to 127.0.0.1 and writes a lock file in a configurable location. It does not modify other skills' configs or request elevated privileges. The server writes to disk only its lock file and does not persist other state.

What to consider before installing

This skill appears to be a straightforward local music server, but review before installing: - Missing entry-point: The documentation repeatedly references a './play-music' client script, but that file is not included. Either the client was omitted or you must run music-server.py directly. Ask the author for the client script or inspect how they expect the skill to be invoked. - Lock file permissions: The server writes a lock file (default /tmp/music_player.lock) and sets it to mode 666 (world-writable). This is unnecessary and risky. If you install/run it, consider setting MUSIC_LOCK_FILE to a safe path you control and change permissions (e.g., 600) to avoid tampering, or patch the code to use a safer mode. - Local-only networking: The server binds to 127.0.0.1:12346 (local only), so it does not expose a public network endpoint by default. Still, confirm that your environment doesn't forward or expose localhost ports if you run this on a shared machine. - Dependency: The skill uses pygame; install via pip in a virtualenv if you want to isolate it. - Basic safety checks: Inspect or run the code in a sandbox/container before trusting it in a production or multi-user environment. If you plan to enable autonomous agent invocation, be aware the skill can start a local server process; ensure the agent's permissions and environment variables are restricted. If you want to proceed: obtain or add the missing 'play-music' client, fix the lock-file permission behavior (or set MUSIC_LOCK_FILE to a safe path), and run the skill in a contained environment first. If the author cannot explain the missing client or justify the 0o666 lock file, do not install.

🎵 Play Music Skill

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

Quick Start

1. Place music files in a music folder (default) or set MUSIC_DIR environment variable
2. Install pygame (recommended for full control): pip install pygame
3. 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:

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:

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.