volumito

Python client library and CLI tool for Volumio.

Overview

volumito is a Python library and a CLI tool that allows querying and controlling a Volumio host.

Features

• Clean Python API to query the state of a Volumio host and to control it
• Extensive and configurable CLI tool
• AI-generated, Human-reviewed code
• Type-safe implementation with type hints
• Comprehensive unit test coverage (100%)

Requirements

• Python 3.13 or later
• A package/virtual environment manager tool (e.g., micromamba, conda, uv, etc.)
• A running Volumio host

Installation

IMPORTANT: the examples in the documentation use micromamba to manage virtual environments; feel free to replace it with your favorite tool (conda, uv, etc.).

From PyPI (Recommended)

volumito is published on PyPI as the same-name package volumito , and this is the recommended way of installing it for most users.

Only the first time: create a virtual environment, activate it, and install the latest release of volumito available on PyPI with pip:

$ micromamba create -n volumito_env python=3.13
$ micromamba activate volumito_env

(volumito_env) $ pip install volumito

To download the tracks stored on the Volumio host, which are copied over SCP, install the scp extra as well:

(volumito_env) $ pip install volumito[scp]

You should be able to run:

(volumito_env) $ volumito version
volumito, version 0.1.0

The next time you want to use volumito, you will only need to activate the existing virtual environment:

$ micromamba activate volumito_env

(volumito_env) $ volumito version
volumito, version 0.1.0

To update volumito, use the -U/--upgrade option:

$ micromamba activate volumito_env

(volumito_env) $ pip install volumito --upgrade

From Source

Clone this repository and install from source in a virtual environment:

$ git clone https://github.com/pettarin/volumito
$ cd volumito

$ micromamba create -n volumito_env python=3.13
$ micromamba activate volumito_env

(volumito_env) $ pip install -e .
(volumito_env) $ # or
(volumito_env) $ make install-e-this

You should be able to run:

(volumito_env) $ volumito version
volumito, version 0.1.0

Usage

CLI Usage

Some examples of the commands made available by the CLI tool volumito in the virtual enviroment where it is installed:

$ # print help/usage messages; it works globally and on commands and subcommands
$ volumito --help
$ volumito playback --help

$ # create a configuration file (you might want to inspect/edit it later)
$ volumito configuration create -o ~/volumito.yaml
Created configuration file ~/volumito.yaml

$ # print information about the Volumio host
$ volumito system info
{
    "builddate": "Tue Mar 24 17:20:52 UTC 2026",
    "hardware": "pi",
    "host": "http://192.168.1.122",
    "hwUuid": "<REDACTED>",
    "id": "<REDACTED>",
    "isPremiumDevice": false,
    "isVolumioProduct": false,
    "name": "volumio",
    "os": "12",
    "serviceName": "Volumio",
    "state": {
        "albumart": "https://static.qobuz.com/images/covers/64/04/0639842660464_600.jpg",
        "artist": "Mango",
        "mute": false,
        "status": "play",
        "track": "Nella mia città",
        "volume": 20
    },
    "systemversion": "4.119",
    "type": "device",
    "variant": "volumio"
}

$ # print the playback status
$ volumito playback status
{
    "album": "Sirtaki",
    "artist": "Mango",
    "bitdepth": "16 bit",
    "channels": 2,
    "duration": "00:04:34",
    "mute": false,
    "position": 2,
    "samplerate": "44 KHz",
    "seek": "00:00:21.528",
    "status": "play",
    "title": "I giochi del vento sul lago salato",
    "trackType": "qobuz",
    "volume": 20
}

$ # print the list of tracks currently in the reproduction queue
$ volumito queue get
[
    {
        "album": "Polvere",
        "artist": "Enrico Ruggeri",
        "duration": "00:03:15",
        "position": 1,
        "title": "Va tutto bene",
        "tracknumber": 1,
        "volumeNumber": 1
    },
    {
        "album": "Polvere",
        "artist": "Enrico Ruggeri",
        "duration": "00:03:56",
        "position": 2,
        "title": "Fuoco sui giocattoli",
        "tracknumber": 2,
        "volumeNumber": 1
    },
    {
        "album": "La Vie En Rouge",
        "artist": "Enrico Ruggeri",
        "duration": "00:04:07",
        "position": 3,
        "title": "La Vie En Rouge",
        "tracknumber": 1,
        "volumeNumber": 1
    },
    ...
    {
        "album": "La Vie En Rouge",
        "artist": "Enrico Ruggeri",
        "duration": "00:04:49",
        "position": 11,
        "title": "La Bandiera",
        "tracknumber": 3,
        "volumeNumber": 2
    }
]

$ # print information about the current track,
$ # with a short format (a subset of all available fields)
$ volumito track info
{
    "album": "Sirtaki",
    "artist": "Mango",
    "bitdepth": "16 bit",
    "channels": 2,
    "duration": "00:04:34",
    "position": 2,
    "samplerate": "44 KHz",
    "title": "I giochi del vento sul lago salato",
    "trackType": "qobuz"
}

$ # print information about the current track,
$ # with all the available fields
$ volumito track info --fields all
{
    "album": "Sirtaki",
    "albumart": "https://static.qobuz.com/images/covers/64/04/0639842660464_600.jpg",
    "artist": "Mango",
    "bitdepth": "16 bit",
    "channels": 2,
    "consume": false,
    "dbVolume": null,
    "disableVolumeControl": false,
    "duration": "00:04:34",
    "mute": false,
    "position": 2,
    "random": false,
    "repeat": false,
    "repeatSingle": false,
    "samplerate": "44 KHz",
    "seek": "00:01:53.135",
    "service": "qobuz",
    "status": "play",
    "stream": "qobuz",
    "title": "I giochi del vento sul lago salato",
    "trackType": "qobuz",
    "updatedb": false,
    "uri": "qobuz://song/2581513",
    "volatile": false,
    "volume": 20
}

$ # control the playback on the Volumio host
$ volumito playback play
$ volumito playback pause
$ volumito playback stop
$ volumito playback previous
$ volumito playback next
$ volumito playback seek 00:01:02
$ volumito playback mute
$ volumito playback unmute
$ volumito playback volume 80

$ # print the list of all available playlists
$ volumito playlist list
[
    "another playlist",
    "my awesome playlist",
    "volumito test playlist"
]

$ # play the specified playlist, replacing the current queue
$ volumito playlist play "my awesome playlist"
Command 'playplaylist my awesome playlist' executed successfully
{
    "album": "Sirtaki",
    "artist": "Mango",
    "bitdepth": "16 bit",
    "channels": 2,
    "duration": "00:06:59",
    "mute": false,
    "position": 1,
    "samplerate": "44.1 kHz",
    "seek": "00:00:01.001",
    "status": "play",
    "title": "Nella mia città",
    "trackType": "qobuz",
    "volume": 30
}

The CLI USAGE document describes all the commands, subcommands, and options of the CLI tool volumito.

Library Usage

A quick example:

from volumito import (
    VolumioHostConfiguration,
    VolumioRESTAPIClient,
)

# replace with your Volumio host
host = VolumioHostConfiguration(host="volumio.local")
client = VolumioRESTAPIClient(host)


# retrieve the system information
info = client.system_info
print(info.name, info.system_version, info.is_premium_device)
# volumio 4.119 False


# retrieve the current playing state
state = client.state
print(state.title, "---", state.artist, "---", state.album)
# Recitando --- Paolo Conte --- Paolo Conte Alla Scala - il Maestro è nell'anima
print(state.status, state.volume, state.seek, state.duration)
# play 49 125029 229
print(state.is_playing, state.is_paused, state.is_stopped)
# True False False

# the payload the Volumio host returned is always available
print(state.raw["trackType"], state.raw["samplerate"])
# qobuz 44.1 kHz

# pause/play/stop the current track (and check the playback status)
client.pause()
print(client.is_paused)
client.play()
print(client.is_playing)
client.stop()
print(client.is_stopped)

# read and control the volume
print(client.volume)
client.volume = 50
client.mute()
print(client.is_muted)
client.unmute()

# print the current queue (which is a sequence of its tracks)
for index, track in enumerate(client.queue, 1):
    print(f"{index}. {track.title} - {track.artist}")
# 1. Aguaplano - Paolo Conte
# 2. Sotto Le Stelle Del Jazz - Paolo Conte
# 3. Come Di - Paolo Conte
# 4. Alle Prese Con Una Verde Milonga - Paolo Conte
# 5. Ratafià - Paolo Conte
# ...

# play the 4th track of the current queue, by track or by position
# (positions start at index zero)
client.play(client.queue[3])
client.play(3)

# read the seek position, then seek to 01:42 (both in seconds)
print(client.seek)
client.seek = 102

# play the previous/next track
client.previous()
client.next()


# list the saved playlists (which are a sequence of their playlists)
for playlist in client.playlists:
    print(playlist.name)
# Jazz Classics
# Rock
# ...

# play one, checking that it exists first
playlist_name = "Jazz Classics"
if playlist_name in client.playlists:
    client.play_playlist(playlist_name)
else:
    print(f"No such playlist: '{playlist_name}'")

The LIBRARY_USAGE document contains the API reference of the Python library volumito.

Releases And Changelog

The list of releases and their changes is contained in the CHANGELOG document.

Development

Consult the DEVELOPMENT document to learn how to set up a development environment, run the tests, and browse the project structure.

The CONTRIBUTING document explains how to report issues and propose changes.

License

This project is licensed under the GNU General Public License v3.0 or later (GPLv3+).

See the LICENSE file for details.

Authors

• Alberto Pettarin (Web)

Legal Disclaimers

Volumio and the Volumio logo are registered trademarks of Volumio SRL, a company registered in Italy (VAT ID: IT07009020483).

Please refer to the Volumio Terms Of Service.

This project and its authors are not affiliated nor endorsed by Volumio SRL.