README

Introduction

This package provides a simple and elegant way to interact with the Volumio audio player API from your Laravel application. Volumio is a free and open source Linux distribution designed for music playback with a focus on sound quality.

With this package, you can:

Control playback (play, pause, stop, next, previous)
Adjust volume
Manage the queue
Get player state and queue information
Control playback modes (repeat, random)
Manage playlists
Browse and search the music library
Add items to the queue or replace the queue
Get collection statistics
Manage multi-room zones
Get system information
Set up push notifications

This package is compatible with Laravel 12 and connects to the Volumio REST API.

Official Docs

Installation

You can install the package via composer:

composer require dweb-x/volumio

You can publish the config file with:

php artisan vendor:publish --tag="volumio-config"

This is the contents of the published config file:

return [
    // The base URL of your Volumio instance
    'base_url' => env('VOLUMIO_API_URL', 'http://localhost:3000'),

    // API request timeout in seconds
    'timeout' => env('VOLUMIO_API_TIMEOUT', 10),

    // Connection retry attempts
    'retries' => env('VOLUMIO_API_RETRIES', 3),

    // Default request options for Guzzle
    'http_options' => [
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ],
    ],
];

Configuration

The package comes with a configuration file that allows you to customize how the Volumio API client behaves. Here's a detailed explanation of each configuration option:

Base URL

'base_url' => env('VOLUMIO_API_URL', 'http://localhost:3000'),

This is the URL of your Volumio instance. By default, it points to http://localhost:3000, which is the standard address for a Volumio instance running on the same machine. If your Volumio instance is running on a different machine or port, you should set the VOLUMIO_API_URL environment variable in your .env file:

VOLUMIO_API_URL=http://192.168.1.100:3000

Timeout

'timeout' => env('VOLUMIO_API_TIMEOUT', 10),

This setting controls how long (in seconds) the client will wait for a response from the Volumio API before timing out. The default is 10 seconds, which should be sufficient for most use cases. If you're experiencing timeout issues, you can increase this value in your .env file:

VOLUMIO_API_TIMEOUT=30

Retries

'retries' => env('VOLUMIO_API_RETRIES', 3),

If an API request fails, the client will automatically retry the request. This setting controls how many retry attempts will be made before giving up. The default is 3 retries. You can adjust this in your .env file:

VOLUMIO_API_RETRIES=5

The client uses an exponential backoff strategy for retries, meaning each subsequent retry will wait longer before attempting again.

HTTP Options

'http_options' => [
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
],

These are the default HTTP headers that will be sent with every request to the Volumio API. The default headers are set to work with the Volumio API's JSON responses. You typically won't need to modify these.

Usage

You can use the facade to interact with the Volumio API:

use Dwebx\Volumio\Facades\Volumio;

// Get the current player state
$state = Volumio::getState();

// Get the current queue
$queue = Volumio::getQueue();

// Playback controls
Volumio::toggle(); // Play/pause
Volumio::pause(); // Pause playback
Volumio::next(); // Next track
Volumio::previous(); // Previous track
Volumio::stop(); // Stop playback

// Volume controls
Volumio::setVolume(75); // Set volume (0-100)
Volumio::volumeUp(); // Increase volume
Volumio::volumeDown(); // Decrease volume
Volumio::mute(); // Mute volume
Volumio::unmute(); // Unmute volume

// You can also use the Volume enum
use Dwebx\Volumio\Enums\Volume;
Volumio::setVolume(Volume::PLUS); // Increase volume
Volumio::setVolume(Volume::MINUS); // Decrease volume
Volumio::setVolume(Volume::MUTE); // Mute
Volumio::setVolume(Volume::UNMUTE); // Unmute

// Queue management
Volumio::play(2); // Play a specific item from the queue (0-based index)
Volumio::clearQueue(); // Clear the queue

// Playback modes
Volumio::repeat(); // Toggle repeat mode
Volumio::repeat(true); // Enable repeat mode
Volumio::repeat(false); // Disable repeat mode
Volumio::random(); // Toggle random mode
Volumio::random(true); // Enable random mode
Volumio::random(false); // Disable random mode

// Playlist management
$playlists = Volumio::listPlaylists(); // Get list of playlists
Volumio::playPlaylist('Rock'); // Play a specific playlist

// Browsing and searching
$root = Volumio::browse(); // Browse root directory
$musicLibrary = Volumio::browse('music-library'); // Browse music library
$limitedResults = Volumio::browse('music-library', 10, 5); // Limit to 10 results, starting from the 5th
$searchResults = Volumio::search('Pink Floyd'); // Search for content

// Advanced queue management
$items = [
    [
        'uri' => 'music-library/song.flac',
        'service' => 'mpd',
        'title' => 'Song Title',
        'artist' => 'Artist Name',
        'album' => 'Album Name',
        'type' => 'song',
    ],
];
Volumio::addToQueue($items); // Add items to queue

$data = [
    'item' => [
        'uri' => 'music-library/song.flac',
        'service' => 'mpd',
        'title' => 'Song Title',
    ],
    'list' => $items,
    'index' => 0,
];
Volumio::replaceAndPlay($data); // Replace queue and play

// System information
$stats = Volumio::getCollectionStats(); // Get collection statistics
$zones = Volumio::getZones(); // Get information about Volumio zones
$pong = Volumio::ping(); // Ping the Volumio API
$version = Volumio::getSystemVersion(); // Get system version
$info = Volumio::getSystemInfo(); // Get system information

// Push notifications
$urls = Volumio::getPushNotificationUrls(); // Get list of push notification URLs
Volumio::addPushNotificationUrl('http://example.com/callback'); // Add a push notification URL
Volumio::removePushNotificationUrl('http://example.com/callback'); // Remove a push notification URL

Or you can inject the Volumio service:

use Dwebx\Volumio\Volumio;

class MyController
{
    public function index(Volumio $volumio)
    {
        $state = $volumio->getState();

        return view('my-view', [
            'playerState' => $state,
        ]);
    }
}

Response Format

All methods return an array containing the response from the Volumio API. The exact structure of the response depends on the method called. For example:

// Example response from getState()
[
    'status' => 'play',
    'title' => 'Song Title',
    'artist' => 'Artist Name',
    'album' => 'Album Name',
    'volume' => 50,
    // ... other state information
]

Error Handling

The package will automatically retry failed requests based on your configuration. If all retry attempts fail, an exception will be thrown. You should wrap your API calls in a try-catch block to handle potential errors:

use Dwebx\Volumio\Facades\Volumio;

try {
    $state = Volumio::getState();
    // Process the state
} catch (\Exception $e) {
    // Handle the error
    Log::error('Volumio API error: ' . $e->getMessage());
}

Testing

composer test

Credits

License

The MIT License (MIT). Please see License File for more information.

dweb-x / volumio

Maintainers

Details