The project wiim-java-api is a implementation of the WiiM HTTP API written in java to interact with WiiM devices.
The api is compatible with the following WiiM devices WiiMhome
- WiiM Pro See product
- Wiim mini See product
Other WiiM devices may also work if they using the same httpAPI.
This library was built for Java 11.
<!-- https://builds.mirranet.de/plugin/repository/everything/de/linzn/wiim-java-api/ -->
<dependency>
<groupId>de.linzn</groupId>
<artifactId>wiim-java-api</artifactId>
<version>2.0.0</version>
</dependency>The version 2.x of this api was generated by anthropic claude code. Use always with attention!
import de.linzn.wiim.api.WiiMClient;
import de.linzn.wiim.api.model.*;
// Create wiim client with ip address
WiiMClient client = new WiiMClient("192.168.1.42");
// ── Device information ──────────────────────────────────────────────────
DeviceStatus status = client.getDeviceStatus();
System.out.println(status.getDeviceName()); // e.g. "WiiM Mini-8FA2"
System.out.println(status.getFirmware()); // e.g. "Linkplay.4.6.425351"
System.out.println(status.isUpdateAvailable()); // true/false
// ── Connection status ────────────────────────────────────────────────────
System.out.println(client.isConnected()); // true when wifi is connected
// ── Play control ──────────────────────────────────────────────────────────
client.play("http://stream.radioparadise.com/flacm");
client.pause();
client.resume();
client.togglePause(); // Switch play/pause
client.next();
client.previous();
client.seek(30); // Seek 30 seconds
client.stop();
// ── Volume & Mute ───────────────────────────────────────────────────
client.setVolume(60); // 0–100
client.setMute(true);
client.setMute(false);
// ── Loop-Modus ──────────────────────────────────────────────────────────
client.setLoopMode(PlayerStatus.LoopMode.SHUFFLE_LOOP);
client.setLoopMode(PlayerStatus.LoopMode.NO_SHUFFLE_NO_LOOP);
// ── Player status ────────────────────────────────────────────────────
PlayerStatus ps = client.getPlayerStatus();
System.out.println(ps.getStatus()); // "play", "pause", "stop"
System.out.println(ps.getPlaybackMode()); // SPOTIFY, TIDAL, BLUETOOTH, …
System.out.println(ps.getVolumeInt()); // 0–100
System.out.println(ps.getCurrentPositionMs()); // Position in ms
// ── Track-Metadata ─────────────────────────────────────────────────────
TrackMetadata.MetaData meta = client.getTrackMetadata();
if(meta !=null){
System.out.println(meta.getArtist() +" – "+meta.getTitle());
System.out. println(meta.getAlbumArtUri());
}
// ── Equalizer ───────────────────────────────────────────────────────────
client.eqOn();
List<String> presets = client.getEqList(); // ["Flat", "Rock", "Jazz", …]
client.loadEq("Rock");
boolean eqOn = client.isEqOn();
client.eqOff();
// ── Presets (1–12) ──────────────────────────────────────────────────────
client.playPreset(1);
PresetList presetList = client.getPresetList();
presetList.getPresets().forEach(p -> System.out.println(p.getNumber() +": "+p.getName()));
// ── Switch input source ──────────────────────────────────────────────
client.switchSource(WiiMClient.SourceInput.BLUETOOTH);
client.switchSource(WiiMClient.SourceInput.OPTICAL);
client.switchSource(WiiMClient.SourceInput.LINE_IN);
client.switchSource(WiiMClient.SourceInput.WIFI);
// ── Audio output ───────────────────────────────────────────────────────
AudioOutputMode audioMode = client.getAudioOutputMode();
System.out.println(audioMode.getHardwareMode()); // SPDIF, AUX, COAX
client.setAudioOutputMode(AudioOutputMode.HardwareMode.SPDIF);
// ── Playlist ────────────────────────────────────────────────────────────
client.playPlaylist("http://example.com/mylist.m3u",0);
// ── Device control ───────────────────────────────────────────────────────
client.reboot();
client.shutdownNow();
client.shutdown(60); // Shutdown deice in 60 seconds
client.cancelShutdown();
int remaining = client.getShutdownTimer();
// ── Sync clock ─────────────────────────────────────────────────
client.syncTimeNow(); // Sync time with ntp server
// ── Alarm (Slots 0–2) ──────────────────────────────────────────────────
// Daily alarm at 07:00 UTC with the given steam input
client.setAlarmEveryDay(0,"073000","http://stream.example.com/radio");
// Onetime alarm on 2025-06-01 at 08:00 UTC
client.setAlarmOnce(1,"080000","20250601","http://stream.example.com/radio");
// Check Alarm
AlarmClock alarm = client.getAlarm(0);
System.out.println(alarm.isEnabled() +" – "+alarm.getTime());
// Delete Alarm
client.cancelAlarm(0);
client.stopAlarm(); // Stop current running alarmWiiMClient client = new WiiMClient("192.168.1.42");
public TestApp(){
DeviceMonitor monitor = new DeviceMonitor(client) {
/**
* Called whenever the raw playback status string changes
* (play → pause, pause → stop, etc.).
*
* @param previous previous status snapshot
* @param current new status snapshot
*/
@Override
protected void onPlaybackStatusChanged(PlayerStatus previous, PlayerStatus current) {
System.out.println("onPlaybackStatusChanged: " + previous.getStatus()
+ " → " + current.getStatus());
}
/**
* Called when the device starts playing
* (from stopped, paused, or loading).
*/
@Override
protected void onStartedPlaying(PlayerStatus status) {
System.out.println("onStartedPlaying: vol=" + status.getVolumeInt()
+ " mode=" + status.getPlaybackMode());
}
/**
* Called when playback is paused.
*/
@Override
protected void onPaused(PlayerStatus status) {
System.out.println("onPaused: pos=" + status.getCurrentPositionMs() + "ms");
}
/**
* Called when paused playback resumes.
*/
@Override
protected void onResumed(PlayerStatus status) {
System.out.println("onResumed: pos=" + status.getCurrentPositionMs() + "ms");
}
/**
* Called when playback stops completely.
* Note: after 2 minutes in this state,
* onStandby() is also called.
*/
@Override
protected void onStopped(PlayerStatus status) {
System.out.println("onStopped");
}
/**
* Called when the device is buffering / loading a new stream.
*/
@Override
protected void onLoading(PlayerStatus status) {
System.out.println("onLoading");
}
/**
* Called when the device has been stopped for
* 2 minutes without resuming.
*
* <p>Override this to cut power relays, dim displays, notify a home
* automation system, etc.
*/
@Override
protected void onStandby() {
System.out.println("onStandby: device idle for 2 minutes.");
}
/**
* Called when the volume level changes.
*
* @param previous volume before the change (0–100)
* @param current new volume (0–100)
*/
@Override
protected void onVolumeChanged(int previous, int current) {
System.out.println("onVolumeChanged: " + previous + " → " + current);
}
/**
* Called when the device is muted.
*/
@Override
protected void onMuted() {
System.out.println("onMuted");
}
/**
* Called when the device is unmuted.
*/
@Override
protected void onUnmuted() {
System.out.println("onUnmuted");
}
/**
* Called when the playback source/mode changes
* (e.g. Bluetooth → Spotify, Wi-Fi → optical in).
*
* @param previous previous playback mode
* @param current new playback mode
*/
@Override
protected void onModeChanged(PlayerStatus.PlaybackMode previous,
PlayerStatus.PlaybackMode current) {
System.out.println("onModeChanged: " + previous + " → " + current);
}
/**
* Called when the active track in a playlist changes.
*/
@Override
protected void onTrackChanged(PlayerStatus status) {
System.out.println("onTrackChanged: index=" + status.getPlaylistCurrent());
}
/**
* Called when the loop/shuffle mode changes.
*/
@Override
protected void onLoopModeChanged(PlayerStatus.LoopMode newMode) {
System.out.println("onLoopModeChanged: " + newMode);
}
/**
* Called when the polling request fails (network error, device unreachable).
*
* @param error the exception that was thrown
*/
@Override
protected void onPollError(Exception error) {
System.out.println("onPollError: " + error.getMessage());
}
};
// Available also with monitor.start(); Default is 1000ms
monitor.start(800);
}- WiiM devices use self-signed TLS certificates. This client intentionally disable certificate validation. Use only in local networks.
- All methods throws
WiiMApiException(RuntimeException) by network or api errors! - HTTP-Requests are using
java.net.http.HttpClient(Java 11+)