Metadata-Version: 2.4
Name: volumito
Version: 0.0.10
Summary: Python client library and CLI tool for Volumio
Author-email: Alberto Pettarin <alberto@albertopettarin.it>
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: python-mpd2>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: setuptools>=80.9.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: wheel>=0.45.1; extra == "dev"
Dynamic: license-file

# volumito

Python client library and CLI tool for Volumio.


## Overview

`volumito` is a Python library and a command-line tool
that allows you to interact with your
[Volumio](https://volumio.com/)
player, programmatically or on a shell.


## Features

- Clean Python API to connect to and control a Volumio player
- Built-in comprehensive command-line tool with a lot of options
- Optional YAML configuration file for connection and output defaults
- Type-safe implementation with full type hints
- Comprehensive test coverage (100%)


## Requirements

- Python 3.13 or later
- A running Volumio player


## Installation

### From PyPI

Activate your virtual environment (`volumito_env`),
and install:

```bash
(volumito_env) $ pip install volumito
```

### From Source

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

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

$ # here Micromamba is used, choose your favorite
$ # package/virtual environment manager
$ micromamba env create -f environment.yml
$ micromamba activate volumito_dev

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

(volumito_dev) $ # for developing volumito, use the dev configuration:
(volumito_dev) $ pip install -e .[dev]
(volumito_dev) $ # or
(volumito_dev) $ make install-e-this-dev
```

## Usage

### Basic Command

Query a Volumio instance at the default location (`volumio.local:3000`):

```bash
volumito player state
```

`volumito info` is a synonym for `volumito player state`.

### Version

Print the `volumito` version:

```bash
volumito version

# Quoted version string, consumable by jq/yq (e.g. "0.0.9")
volumito --machine-readable version
```

### Connection Options

Specify custom connection parameters:

```bash
# Custom host (-H is a shorthand for --host)
volumito player state --host my-volumio.local
volumito player state -H 192.168.1.100

# HTTPS connection
volumito player state --scheme https

# Custom ports (-P for --rest-api-port, -M for --mpd-port)
volumito player state --rest-api-port 8080 --mpd-port 7000
volumito player state -P 8080 -M 7000

# Custom timeouts (in seconds)
volumito player state --rest-api-timeout 10
volumito track audio --mpd-timeout 3

# Pause before the resulting-state fetch (default 1.0 s; see Resulting State)
volumito --rest-api-sleep-before-next-call 0.5 player pause
```

The default MPD port is `6600`, as used by Volumio 4.
For Volumio 3 and earlier, which use MPD port `6599`,
pass `--mpd-port 6599`.

### Configuration File

Rather than passing connection and output options on every invocation, you can store them in a
YAML configuration file. Its values are used as **defaults**: an explicit command-line option always
overrides the file, and if neither is given the built-in defaults apply. The precedence is:

```
command-line option  >  configuration file  >  built-in default
```

Point at an explicit file with `-c`/`--configuration-file`:

```bash
volumito -c /path/to/volumito.yaml player state
```

If `-c` is omitted, the following directories are probed in order (highest priority first), and within
each directory `volumito.yaml` is tried before `.volumito.yaml`. The first file that exists is used:

1. the current working directory
2. the home directory (`~`)
3. `~/.volumito`
4. `~/.config/volumito`
5. `/etc` (lowest priority)

If none exists, the built-in defaults are used. A file named with `-c` that does not exist, invalid
YAML, or an unrecognized section/key is an error.

All sections and keys are optional. Keys mirror the CLI long options (without the leading `--`):

```yaml
volumio:
  host: volumio.local
  scheme: https
  rest-api-port: 3000
  mpd-port: 6600
timeouts:
  rest-api-timeout: 5.0
  mpd-timeout: 5.0
  rest-api-sleep-before-next-call: 1.0
output:
  verbose: true
  machine-readable: false
  print-resulting-state: true
  # fields/format/raw here apply to all display commands...
  format: pretty
  player-state:
    # ...and can be overridden per command.
    format: table
  track-info:
    format: json
downloads:
  # Keys here apply to both track download commands...
  overwrite-existing-files: false
  track-audio:
    # ...and can be overridden per command.
    file-name-template: "{position:03d}_{title}.{extension}"
    output-directory: ~/Music
  track-albumart:
    file-name-template: "{album}.{extension}"
    output-directory: ~/Covers
```

The `output` section's `fields`, `format`, and `raw` keys set the defaults for the corresponding
`--fields`/`--format`/`--raw` options of the commands that support them (`player state`, `info`,
`track info`, and `queue list`). A key placed directly under `output` applies to all of them; the optional
`player-state`, `track-info`, and `queue-list` subsections hold the same keys and override the shared value
for that command (`player-state` also governs the `info` synonym). The `print-resulting-state` key sets the
default for the `-r` option of the `player` action commands (`toggle`, `play`, `pause`, `stop`, `next`,
`previous`, `volume`, `mute`, `unmute`).

The `downloads` section sets the defaults for the `--file-name-template`, `--output-directory`,
`--output-file`, and `--overwrite-existing-files` options of `track audio` and `track albumart`. A key
placed directly under `downloads` applies to both commands; the optional `track-audio` and `track-albumart`
subsections hold the same keys and override the shared value for that command (so each can have its own
`file-name-template`).

The `configuration` command group helps manage these files:

```bash
# Create a volumito.yaml with all keys set to their default values
volumito configuration create                       # in the current directory
volumito configuration create -d ~/.config/volumito # in a directory (created if needed)
volumito configuration create -f ./my-config.yaml   # at an exact path
# By default an existing file is not overwritten; pass --overwrite-existing-files to force it.

# Validate a configuration file and print the values read from it
volumito configuration check ./volumito.yaml
volumito configuration check            # no path: check the file that would be used

# Show which configuration files exist and which one would be used
volumito configuration search

# Print the directories searched for a configuration file, in probing order
volumito configuration locations
```

### Output Formats

Choose from multiple output formats:

```bash
# Pretty JSON with 4-space indentation (default)
volumito player state --format pretty

# Compact JSON with 2-space indentation
volumito player state --format json

# Human-readable table (-F is a shorthand for --format)
volumito player state --format table
volumito player state -F table

# Raw unformatted JSON (-R is a shorthand for --raw)
volumito player state --raw
volumito player state -R
```

### Field Filtering

Control which fields are displayed:

```bash
# Show only key playback information (default)
volumito player state --fields short

# Show all available fields (-L is a shorthand for --fields)
volumito player state --fields all
volumito player state -L all
```

Short fields include:
- status
- position
- title
- artist
- album
- duration
- seek
- volume
- mute
- trackType
- samplerate
- bitdepth
- channels

### Verbosity Control

```bash
# Verbose mode
volumito player state --verbose

# Machine-readable mode (always supersedes the verbose option)
volumito player state --machine-readable
```

### Volume Control

Set, adjust, or show the playback volume:

```bash
# Print the current volume (no value)
volumito player volume

# Set an absolute level (integer between 0 and 100)
volumito player volume 75

# Step the volume one click up or down
volumito player volume plus     # also: increase, up
volumito player volume minus    # also: decrease, down

# Mute and unmute
volumito player volume mute
volumito player volume unmute

# `player mute` and `player unmute` are synonyms for the two commands above
volumito player mute
volumito player unmute
```

### Playing A Queue Position

Start playback of a specific track in the queue (1-indexed):

```bash
# -p is a shorthand for --position
volumito player play --position 3
volumito player play -p 3
```

### Resulting State

By default, every `player` action subcommand (`toggle`, `play`, `pause`, `stop`, `next`, `previous`,
`volume`, `mute`, `unmute`) waits before fetching and printing the resulting `player state`. The pause
is 1 second by default; change it with the global `--rest-api-sleep-before-next-call` option. Disable
the whole behavior with `--no-print-resulting-state`:

```bash
# Pause, then show the resulting state (default)
volumito player pause

# Use a shorter pause before the resulting state
volumito --rest-api-sleep-before-next-call 0.5 player pause

# Pause without printing the resulting state
volumito player pause --no-print-resulting-state
```

### Examples

Combine options for specific use cases:

```bash
# Table format with all fields
volumito player state --format table --fields all

# Pipe to jq for advanced JSON processing
volumito player state --raw | jq '.title, .artist'

# Save state to file
volumito player state --format json > volumio_state.json

# Monitor playback every 5 seconds
while true; do
    clear
    volumito player state --format table
    sleep 5
done
```

### Track Information

Show metadata for the currently playing track. This works like `player state`
(same `--fields`/`--format`/`--raw` options, and their `-L`/`-F`/`-R` shorthands),
but its default `short` field set is track-oriented:

```bash
# Track-oriented short fields (default)
volumito track info

# All available fields, as compact JSON
volumito track info -L all -F json

# Raw unfiltered JSON
volumito track info -R
```

Its short fields are:
- position
- title
- artist
- album
- duration
- trackType
- samplerate
- bitdepth
- channels

### Album Art

Get the current album art URI:

```bash
# Get URI only
volumito track albumart

# Download to an exact file path (-o)
volumito track albumart -o /path/to/cover.jpg

# Download into a directory, using the file name from the URI (-d)
volumito track albumart -d /path/to/covers/

# Machine-readable mode prints the URI as a quoted string, consumable by jq/yq
volumito -m track albumart          # => "http://volumio.local:3000/albumart?..."
volumito -m track audio             # => "http://volumio.local:8000/music/..."
```

The `-o`/`--output-file` and `-d`/`--output-directory` options are mutually exclusive.
`track audio` accepts the same two download options:

```bash
# Download the current track to an exact file path
volumito track audio -o /path/to/song.flac

# Download the current track into a directory (file name taken from the URI)
volumito track audio -d /path/to/music/
```

By default, a download will not overwrite an existing destination file (it errors
out instead). Pass `--overwrite-existing-files` to allow overwriting:

```bash
volumito track albumart -o /path/to/cover.jpg --overwrite-existing-files
volumito track audio -d /path/to/music/ --overwrite-existing-files
```

When downloading into a directory with `-d`, the file name is built from
`-f`/`--file-name-template` (Python `str.format` syntax, default
`{file_name_from_uri}`). Any space in the resulting name becomes an underscore:

```bash
# e.g. writes /path/to/music/001_La_rondine.flac
volumito track audio -d /path/to/music/ -f "{position:03d}_{title}.{extension}"
```

Supported template keys:
- `file_name_from_uri` — the file name taken from the URI (the default)
- `position` — 1-indexed track position (e.g. `{position:03d}` → `001`)
- `title`, `album`, `artist`, `trackType`, `bitdepth`, `samplerate` — strings
- `duration` — track length as `HH:MM:SS`
- `channels` — integer
- `extension` — the file extension from the URI, defaulting to `flac` for
  `track audio` and `jpg` for `track albumart`

## API Reference

TODO


## Releases And Changelog

See the [CHANGELOG](CHANGELOG.md) file for the list of releases and their changes.


## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for how to set up a development environment,
run the tests, the project structure, and contributing.


## License

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

See the [LICENSE](LICENSE) file for details.


## Authors

- Alberto Pettarin ([Web](https://www.albertopettarin.it))


## Legal Disclaimers

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

Please refer to the [Volumio Terms Of Service](https://volumio.com/terms-of-service/).

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