https://github.com/pcs-electronics/volumio-control
A command-line tool to control a local Volumio music player instance.
https://github.com/pcs-electronics/volumio-control
Last synced: 8 days ago
JSON representation
A command-line tool to control a local Volumio music player instance.
- Host: GitHub
- URL: https://github.com/pcs-electronics/volumio-control
- Owner: pcs-electronics
- License: mit
- Created: 2026-04-04T13:21:26.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T18:53:11.000Z (2 months ago)
- Last Synced: 2026-04-04T20:07:39.122Z (2 months ago)
- Language: Python
- Size: 15.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Volumio Control
A command-line tool to control a local Volumio music player instance.
## Features
- Play music by name, playlist, album, or web radio
- Search for files, albums, and web radios
- Stop playback
- Support for direct stream URLs and Volumio media URIs
- Dry run mode for testing
## Installation
1. Ensure Python 3 is installed on your system.
2. Clone or download this repository.
3. Make the script executable: `chmod +x volumio-control.py`
## Usage
The tool communicates with Volumio at `http://127.0.0.1:3000` by default. You can change this by setting the `VOLUMIO_BASE_URL` environment variable.
### Commands
- `python3 volumio-control.py play` - Resume playback
- `python3 volumio-control.py play ` - Play an exact matched playlist, file, album, or web radio
- `python3 volumio-control.py play ` - Play a direct stream URL or Volumio media URI
- `python3 volumio-control.py queue ` - Queue an exact matched playlist, file, album, or web radio (adds to queue if playing file, stops stream and plays immediately if playing stream)
- `python3 volumio-control.py queue ` - Queue a direct stream URL or Volumio media URI, then start playback
- `python3 volumio-control.py show-queue` - Show the current Volumio queue
- `python3 volumio-control.py clear-queue` - Clear the current Volumio queue
- `python3 volumio-control.py remove-queue ` - Remove item(s) from the current queue by song name or URI
- `python3 volumio-control.py status` - Show the current playback status, including file/stream details
- `python3 volumio-control.py stop` - Stop playback
- `python3 volumio-control.py search ` - Search for files, albums, and web radios
> Note: queueing an internet radio URL may still fail if the stream URL itself is invalid or unreachable. The script now validates stream URLs before adding them to the queue.
### Environment Variables
- `VOLUMIO_BASE_URL`: Base URL of the Volumio instance (default: http://127.0.0.1:3000)
- `VOLUMIO_DRY_RUN`: Enable dry run mode (set to 1, true, yes, or on)
## Examples
```bash
# Resume playback
python3 volumio-control.py play
# Play a specific song
python3 volumio-control.py play "Bohemian Rhapsody"
# Play a web radio stream
python3 volumio-control.py play "http://example.com/stream.mp3"
# Search for music
python3 volumio-control.py search jazz
# Queue a song (adds to queue if playing file, stops stream and plays if playing stream)
python3 volumio-control.py queue "Bohemian Rhapsody"
# Show the current queue
python3 volumio-control.py show-queue
# Remove a queued item by name or URL
python3 volumio-control.py remove-queue "Bohemian Rhapsody"
# Clear the current queue
python3 volumio-control.py clear-queue
# Show current playback status
python3 volumio-control.py status
# Stop playback
python3 volumio-control.py stop
```
## Development
This project was built with AI coding tools.
## AI Agent Integration
A `SKILL.md` file is included in the `skills/volumio-control/` folder. This file provides a structured skill definition that can be used by AI agents to control Volumio playback.
To use this skill with your AI agent:
1. Copy the `skills/volumio-control/SKILL.md` file to your agent's skills folder.
2. Configure your agent to recognize the skill by placing it in the appropriate path according to your agent framework's conventions.
3. Your agent can then:
- Control Volumio playback (play, stop, resume, queue)
- Search for web radios, albums, and files
- Play or queue playlists by exact name
- Handle direct stream URLs and Volumio media URIs
- Resolve ambiguous media names into candidate matches
The skill includes command categories, matching behavior, workflow guidance, and examples for all supported operations.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.