WiiM API - Rust Library

A Rust library for controlling WiiM audio streaming devices via their HTTP API.

Features

• Now Playing Info - Get current track metadata including title, artist, album, and cover art
• Playback Control - Play, pause, stop, next/previous track
• Volume Control - Set volume (0-100), mute/unmute
• Connection Management - Test connectivity and configure target IP
• Async & Safe - Built with tokio and proper error handling

Installation

Add this to your Cargo.toml:

[dependencies]
wiim_api = "0.1"
tokio = { version = "1.0", features = ["full"] }

Usage

use wiim_api::{WiimClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = WiimClient::connect("192.168.1.100").await?;

    let now_playing = client.get_now_playing().await?;
    println!("{} - {}",
        now_playing.artist.unwrap_or_default(),
        now_playing.title.unwrap_or_default()
    );

    client.set_volume(75).await?;
    client.pause().await?;

    Ok(())
}

API Reference

Client Creation

let client = WiimClient::new("192.168.1.100");
let client = WiimClient::connect("192.168.1.100").await?;

Playback Control

client.play().await?;
client.pause().await?;
client.stop().await?;
client.toggle_play_pause().await?;
client.next_track().await?;
client.previous_track().await?;

Volume Control

client.set_volume(75).await?;
client.volume_up(Some(5)).await?;
client.volume_down(Some(3)).await?;
client.mute().await?;
client.unmute().await?;

Information

let info = client.get_now_playing().await?;
let status = client.get_player_status().await?;
let metadata = client.get_meta_info().await?;

Device IP Discovery

Find your WiiM device's IP address via:

• WiiM Home app - Settings → Device Info
• Router admin page - Usually 192.168.1.1 or 192.168.0.1
• Network scanner - Apps like "Fing" or nmap -sn 192.168.1.0/24

API Coverage

Current implementation: 52% of WiiM HTTP API

This library focuses on playback monitoring and control. Key implemented features:

• Now playing information and track metadata
• Playback control (play/pause/stop/next/prev)
• Volume control and muting
• Connection testing and IP configuration

Key limitations:

• Cannot start playback from URLs or playlists
• No preset access (quick stations/playlists)
• No input source switching (Bluetooth/optical/aux)
• No equalizer or device configuration

See API_COVERAGE.md for detailed gap analysis and roadmap.

Supported Devices

This library works with all WiiM devices that support the HTTP API:

• WiiM Mini
• WiiM Pro
• WiiM Pro Plus
• WiiM Amp

Examples

The examples/ directory contains basic_usage.rs - Simple getting started example.

Run examples with: cargo run --example basic_usage

CLI Tool

This library includes a command-line tool for integration with status bars and automation. For detailed CLI usage, template system, and status bar integration guides, see CLI.md.

Error Handling

The library uses a custom Result<T> type with WiimError:

match client.get_now_playing().await {
    Ok(info) => println!("Playing: {:?}", info.title),
    Err(wiim_api::WiimError::Request(_)) => println!("Network error"),
    Err(wiim_api::WiimError::Json(_)) => println!("Invalid response"),
    Err(e) => println!("Other error: {}", e),
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Clone the repository:

git clone https://github.com/carloseberhardt/wiim_api.git
cd wiim_api

Install pre-commit hooks:

pip install pre-commit
pre-commit install

Run tests: cargo test, cargo fmt --check, cargo clippy

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Disclaimer

This is an unofficial library. WiiM is a trademark of Linkplay. This project is not affiliated with or endorsed by Linkplay or WiiM.