⭐ Love this integration? Please star us on GitHub if you use this integration! It helps others discover the project and shows your support for the development effort.

Transform your WiiM and LinkPlay speakers into powerful Home Assistant media players with full multiroom support. Built on the brand new, fully async pywiim library we wrote for reliable, high-performance device communication.

• 🎵 Complete Media Control - Full transport controls, volume, sources, presets, TTS, and media browsing
• 🔗 True Multiroom - Uses Home Assistant's native grouping for reliable synchronized playback
• ⚡ Powered by pywiim - Built on the brand new, fully async pywiim library we wrote for robust, high-performance device communication
• 🚀 Auto-Discovery - Finds speakers automatically via UPnP/SSDP/Zeroconf
• 📱 Universal Compatibility - Works with all Home Assistant dashboards, voice assistants, and media sources
• ⚡ Hybrid State Updates - UPnP events for real-time updates + HTTP polling for reliability
• 🎛️ Advanced Audio - 10-band EQ, audio quality sensors, output mode control, and format support
• ⏰ Timer & Alarms - Sleep timer and alarm management for WiiM devices
• 📊 Rich Diagnostics - Comprehensive statistics, health monitoring, and troubleshooting tools
• 🔄 Scene Support - Full scene restoration including EQ presets and playback state
• 🎯 Smart Features - Optimistic UI updates, adaptive polling, and intelligent source detection

• WiiM: Mini, Pro, Pro Plus, Amp, Ultra
• LinkPlay Compatible: Arylic, Audio Pro (including Gen1: A26, C10, C5a and MkII models), Dayton Audio, DOSS, and many more
• Enhanced Compatibility: Automatic protocol fallback for devices with non-standard configurations
• Requirements: Home Assistant 2024.12.0+ on same network as speakers

1. Find in HACS: HACS → Integrations → Search "WiiM Audio"
2. Install: Download → Restart Home Assistant
3. Configure: Settings → Devices & Services → Add Integration → "WiiM Audio"

1. Download latest release
2. Extract to /config/custom_components/wiim/
3. Restart Home Assistant and add integration

The integration uses a hybrid approach combining UPnP event subscriptions and HTTP polling for optimal reliability and responsiveness:

• UPnP Events (Primary): Real-time state updates via DLNA DMR event subscriptions

  • Instant updates when device state changes (play/pause/volume/mute)
  • Reduces network traffic and improves responsiveness
  • Automatically falls back to polling if UPnP becomes unavailable

• HTTP Polling (Fallback): Adaptive polling strategy ensures reliability

  • 1-second polling during active playback for position updates
  • 5-second polling when idle for resource efficiency
  • Always available as fallback if UPnP subscriptions fail
  • Gracefully handles network issues and device restarts

This dual approach ensures you get the best of both worlds: real-time responsiveness when UPnP is working, and reliable operation even when it's not.

# Create speaker group
service: media_player.join
target:
  entity_id: media_player.living_room
data:
  group_members:
    - media_player.kitchen
    - media_player.bedroom

# Remove from group
service: media_player.unjoin
target:
  entity_id: media_player.living_room

Create wiim_stations.yaml in your config folder:

- name: BBC Radio 2
  url: http://stream.live.vc.bbcmedia.co.uk/bbc_radio_two
- name: Groove Salad (SomaFM)
  url: http://ice2.somafm.com/groovesalad-128-mp3

Access via Browse Media → Quick Stations on any WiiM device.

# Switch to Bluetooth output
- service: select.select_option
  target: select.living_room_audio_output_mode
  data:
    option: "Bluetooth Out"

# Switch to Line Out
- service: select.select_option
  target: select.living_room_audio_output_mode
  data:
    option: "Line Out"

# Morning radio with TTS announcement
- alias: "Morning Routine"
  trigger:
    platform: time
    at: "07:00:00"
  action:
    - service: tts.google_translate_say
      target:
        entity_id: media_player.kitchen
      data:
        message: "Good morning! Starting your favorite radio station."
    - service: media_player.play_media
      target:
        entity_id: media_player.kitchen
      data:
        media_content_type: url
        media_content_id: "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_two"

# Play preset button
- service: wiim.play_preset
  target:
    entity_id: media_player.living_room
  data:
    preset: 1

# Set sleep timer before bed
- alias: "Bedtime Sleep Timer"
  trigger:
    platform: time
    at: "22:30:00"
  action:
    - service: wiim.set_sleep_timer
      target:
        entity_id: media_player.bedroom
      data:
        sleep_time: 3600 # 1 hour

# Create morning alarm
- service: wiim.update_alarm
  target:
    entity_id: media_player.bedroom
  data:
    alarm_id: 0
    time: "07:00:00" # UTC time
    trigger: "daily"
    operation: "playback"

# Set EQ for different music types
- alias: "Rock Music EQ"
  trigger:
    platform: state
    entity_id: media_player.living_room
    attribute: source
    to: "Spotify"
  action:
    - service: wiim.set_eq
      target:
        entity_id: media_player.living_room
      data:
        preset: "rock"

Note: Home Assistant now calls "services" as "actions" in the UI. Both terms refer to the same functionality.

⚠️ Limited Device Support: Queue browsing (get_queue) only works on WiiM Amp and Ultra with USB drive connected. Other devices (Mini, Pro, Pro Plus) do not support ContentDirectory service. Queue position/count is available on all devices. See pywiim documentation for details.

⚠️ Advanced users only - These actions use reverse-engineered API endpoints that may not work on all firmware versions:

See the User Guide for complete action documentation with examples.

The WiiM integration doesn't support custom source names for several reasons:

• Device Limitation: Source names come directly from the device's firmware and API
• Consistency: Other major integrations (Sonos, Denon, Yamaha) also don't support source renaming
• API Compatibility: The device expects specific source names for proper functionality
• Automation Reliability: Custom names could break existing automations and scripts

Instead of renaming sources, you can customize the display in several ways:

# In customize.yaml
media_player.living_room_speaker:
  friendly_name: "Living Room TV Audio"

# In automations.yaml
- alias: "When HDMI is selected"
  trigger:
    platform: state
    entity_id: media_player.living_room_speaker
    attribute: source
    to: "HDMI"
  action:
    - service: notify.persistent_notification
      data:
        message: "TV audio is now active"

# In Lovelace dashboard
type: entities
entities:
  - entity: media_player.living_room_speaker
    name: "TV Audio"
    secondary_info: "{{ states('media_player.living_room_speaker').attributes.source }}"

The integration creates multiple entity types for comprehensive control:

• Main media player entity with full transport controls
• Group coordinator entities for multiroom groups
• Browse media support for all Home Assistant media sources

• Multiroom Role - Current role (Master/Slave/Solo)
• Input Source - Current audio input
• Audio Quality - Sample rate, bit depth, bit rate (when available)
• Firmware Version - Device firmware tracking
• Bluetooth Status - Bluetooth output and connected device
• Diagnostic - Comprehensive device health and statistics

• Audio Output Mode - Line Out, Optical, Coax, Bluetooth, Headphone (device dependent)
• EQ Preset - 24 equalizer presets
• Sound Mode - Audio processing modes

• Sync Time - Synchronize device clock
• Reboot Device - Restart device
• Clear Sleep Timer - Clear active sleep timer

• Mute - Toggle mute state
• Shuffle - Toggle shuffle mode
• Repeat - Toggle repeat mode

• Status LED - Control device LED indicators

When experiencing issues, you can download comprehensive diagnostic information to help with troubleshooting:

1. Device Diagnostics: Go to Settings → Devices & Services → WiiM Audio → (Select device) → Download Diagnostics
2. Integration Diagnostics: Go to Settings → Devices & Services → WiiM Audio → (⋮ Menu) → Download Diagnostics

The diagnostics include:

• Device information (model, firmware, network status)
• Multiroom group configuration and roles
• Media playback state and current sources
• HTTP polling statistics (total polls, success rate, response times)
• Command statistics (total commands, success rate, failure tracking)
• UPnP subscription status and health
• EQ settings and sound modes
• Audio output configuration

All sensitive data (IP addresses, MAC addresses, network names) is automatically redacted.

For real-time device monitoring and debugging, use the monitor_cli tool from the pywiim library:

# Install pywiim
pip3 install pywiim

# Monitor a device (replace with your device IP)
python3 -m pywiim.cli.monitor_cli YOUR_DEVICE_IP

This shows real-time device state including audio output mode, playback state, and multiroom status. Use --verbose for detailed logging or --no-tui for scrolling log output. Press Ctrl+C to stop.

• 📚 Quick Start Guide - Installation and basic setup
• 🎛️ User Guide - Complete features and configuration
• 🤖 Automation Cookbook - Ready-to-use automation patterns
• ❓ FAQ & Troubleshooting - Quick answers to common questions and solutions to common problems

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🏠 Community: Home Assistant Community

We welcome contributions! See CONTRIBUTING.md for guidelines:

• Code improvements and bug fixes
• Documentation updates
• Testing on different speaker models
• Example automations and scripts

This integration builds upon excellent work from:

• pywiim - The brand new, fully async Python library we wrote that powers this integration's device communication
• python-linkplay - Comprehensive LinkPlay library (inspiration for pywiim)
• LinkPlay HA Integration - Original LinkPlay integration

MIT License - see LICENSE for details.

This integration is not affiliated with WiiM or LinkPlay. All trademarks belong to their respective owners.