# How to Troubleshoot Audio Issues on Linux with osu-winello: A Complete Guide

> Troubleshoot Linux audio issues with osu-winello. Fix pops, latency, or glitches by checking PipeWire, updating wine-osu, setting global offset, and disabling Esync Fsync.

- Repository: [NelloKudo/osu-winello](https://github.com/nellokudo/osu-winello)
- Tags: how-to-guide
- Published: 2026-03-07

---

**To eliminate audio glitches, pops, or latency in osu-winello, ensure PipeWire is active, verify your wine-osu binary is up-to-date, apply the correct global offset (-40 ms or -25 ms), and disable Esync/Fsync if timing conflicts occur.**

osu-winello runs the Windows osu! stable client inside a patched Wine environment optimized for low-latency audio. Because the game is highly sensitive to timing, the script bundles a custom **wine-osu** build with specific audio patches and runtime knobs that affect sound output. This guide walks you through the technical layers—from driver verification to configuration flags—to systematically resolve audio problems.

## Understanding the Audio Architecture in osu-winello

### The wine-osu Low-Latency Patches

The bundled Wine binaries contain patches that replace the standard Windows audio driver with a Wine-specific low-latency implementation. In [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 10–15), the `WINEVERSION` constant defines the patch level, while the `WINELINK` variable points to the pre-compiled binaries. If these patches fail to apply or the binary is outdated, the game falls back to the default Windows audio path, introducing higher latency and drop-outs.

### PipeWire vs. PulseAudio Detection

osu-winello prefers **PipeWire** for audio routing. The launcher checks the active sound server by running `LANG=C pactl info | grep "Server Name"`. If the output shows `PulseAudio (on PipeWire)`, the script proceeds with optimized settings. On systems using legacy PulseAudio without PipeWire, the script may introduce extra buffering, causing audible delay. The README.md (lines 81 and 84) documents these requirements and warns against manual PipeWire installations on Steam Deck, where it is already present.

## Step-by-Step Troubleshooting Workflow

### Verify 64-bit GPU Drivers

osu! requires a 64-bit GPU driver stack. Ensure `nvidia-utils`, `mesa-dri`, or equivalent packages are installed. A driver mismatch can force Wine to disable low-latency audio patches, falling back to the slower generic path.

### Confirm PipeWire is Active

Run the detection command to verify your audio server:

```bash
LANG=C pactl info | grep "Server Name"

```

Expected output:

```text
Server Name: PulseAudio (on PipeWire)

```

If you see `Server Name: PulseAudio` without the PipeWire suffix, install PipeWire for your distribution. Refer to the Prerequisites section in README.md for distro-specific commands.

### Check wine-osu Version and Patches

Inspect the `WINEVERSION` constant in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 10–15) and compare it with the latest release on the WineBuilder page. When you launch the game, check `~/.local/share/osuconfig/winello.log` for the message "Your Wine-osu is already up-to-date!" If this line is absent, run the fix command to update:

```bash
./osu-winello.sh fixyawl

```

### Configure Global Audio Offset

Even with low-latency audio, Wine’s timer-driven sound buffer is offset from the system clock. Create a configuration file to set the recommended offset:

```bash
mkdir -p ~/.local/share/osuconfig/configs
cat > ~/.local/share/osuconfig/configs/audio.cfg << 'EOF'

# Low-latency mode (default)

POST_LAUNCH_ARGS="-offset -40"

# For audio-compatibility mode, use -25 instead

#POST_LAUNCH_ARGS="-offset -25"
EOF

```

The `-40` ms value aligns the game’s internal audio clock for the patched Wine build. If you switch to compatibility mode, change this to `-25` ms.

### Toggle Audio Compatibility Mode

If you experience instability with the low-latency patches, force the generic Windows audio stack by adding to your config:

```bash
echo 'WINEDEBUG="-wineboot"' >> ~/.local/share/osuconfig/configs/audio.cfg

```

This disables the custom patches, trading latency for stability. Remove or comment out this line to re-enable low-latency mode.

### Adjust Esync and Fsync Settings

Esync and Fsync can interfere with audio buffer timing on some kernels. Disable them by adding to your configuration file (as shown in [`example.cfg`](https://github.com/nellokudo/osu-winello/blob/main/example.cfg), lines 29–33):

```bash
cat >> ~/.local/share/osuconfig/configs/audio.cfg << 'EOF'

# Disable synchronization primitives if audio crackles

WINEFSYNC=0
WINEESYNC=0
EOF

```

Test the game after each change to isolate which flag affects your hardware.

### Inspect Launch Logs

After running `osu-wine`, examine the runtime log for environment details and warnings:

```bash
cat ~/.local/share/osuconfig/winello.log

```

Look for lines containing `WINEDEBUG` or "audio" warnings. The log reveals the exact flags used and may indicate if "low-latency audio unavailable."

### Reinstall wine-osu Binaries

If logs suggest missing patches or corruption, force a re-download:

```bash
./osu-winello.sh --fixprefix

# or

./osu-winello.sh fixyawl

```

These commands re-install the `yawl` wrapper and `wine-osu` binaries, ensuring the low-latency patches are present in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (line 518).

### Test with Minimal Configuration

Isolate configuration side-effects by temporarily removing custom settings:

```bash
mv ~/.local/share/osuconfig/configs ~/.local/share/osuconfig/configs.backup
osu-wine

```

If audio works, restore files one by one to identify the problematic variable.

## Summary

- **osu-winello** relies on patched **wine-osu** binaries to deliver low-latency audio; verify the `WINEVERSION` in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) is current.
- **PipeWire** is the preferred sound server; check status with `LANG=C pactl info` and install if missing.
- Apply a **global offset** of `-40` ms for low-latency mode or `-25` ms for audio-compatibility mode to align the game clock.
- Disable **Esync/Fsync** (`WINEFSYNC=0`, `WINEESYNC=0`) if you experience crackling or timing issues.
- Use **`./osu-winello.sh fixyawl`** to re-download binaries and inspect `~/.local/share/osuconfig/winello.log` for diagnostic clues.

## Frequently Asked Questions

### Why does osu! audio sound delayed or out of sync on Linux?

The Windows osu! client relies on timer-driven audio buffers that are offset from the Linux system clock. The wine-osu patches reduce this gap, but you must apply a **global offset** (typically `-40` ms) in your config file to fully align the audio. Without this offset, hitsound feedback arrives late relative to the music.

### How do I switch between low-latency and audio-compatibility mode?

Create or edit `~/.local/share/osuconfig/configs/audio.cfg`. For **low-latency mode** (default), ensure `WINEDEBUG` is unset and use `POST_LAUNCH_ARGS="-offset -40"`. For **audio-compatibility mode**, add `WINEDEBUG="-wineboot"` and change the offset to `-25` ms. Restart the game after saving the file.

### What should I do if I hear crackling or popping sounds during gameplay?

First, verify **PipeWire** is active by running `LANG=C pactl info | grep "Server Name"`. If PipeWire is running, try disabling **Esync** and **Fsync** by adding `WINEFSYNC=0` and `WINEESYNC=0` to your config file. These synchronization primitives can interfere with audio buffer timing on certain kernels, causing audible artifacts.

### Where can I find logs to diagnose persistent audio failures?

After launching osu!, examine `~/.local/share/osuconfig/winello.log`. This file contains the exact environment variables (including `WINEDEBUG` flags) and any warnings about low-latency audio availability. If the log indicates missing patches, run `./osu-winello.sh fixyawl` to force a fresh download of the wine-osu binaries.