# How the osu! Handler Works for Importing Beatmaps and Skins in osu-winello

> Learn how the osu handler imports beatmaps and skins in osu-winello. Discover how it bridges Linux and your Windows osu client for seamless file handling.

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

---

**TLDR:** The osu! handler acts as a bridge between the Linux host and the Windows osu! client, registering MIME types and URL schemes on the host system while injecting Windows registry entries that map beatmap (.osz), skin (.osk), and replay (.osr) files to the Wine environment, then dispatching them via `start.exe` to the game executable.

The open-source tool osu-winello (nellokudo/osu-winello) streamlines running osu! on Linux through Wine. Central to its functionality is the **osu! handler**, which eliminates manual file copying by enabling direct import of beatmaps and skins from the Linux desktop into the Windows game client running under Wine.

## Stage 1: Registering MIME Types and Windows Registry Entries

The setup process begins with the `osuHandlerSetup()` function defined in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 21-66). This function performs dual registration: it configures the Linux desktop environment and prepares the Wine prefix to recognize osu! file formats.

First, it creates two desktop entry files:

- `osuwinello-file-extensions-handler.desktop` associates the MIME types `application/x-osu-beatmap-archive` and `application/x-osu-skin-archive` with the command `osu-wine --osuhandler %f`.
- `osuwinello-url-handler.desktop` registers the `osu://` URL scheme with the command `osu-wine --osuhandler %u`.

Second, it imports `stuff/osu-handler.reg` into the Wine registry using `waitWine regedit /s stuff/osu-handler.reg`. This registry file maps file extensions—including `.osz`, `.osk`, `.osr`, and `.osz2`—to specific ProgIDs (e.g., `osustable.File.osz`) that resolve to the executable path `D:\osu!.exe`.

## Stage 2: Runtime Dispatch via osuHandlerHandle()

When a user opens a registered file or clicks an `osu://` link, the desktop entry invokes `osu-wine --osuhandler <argument>`, triggering the `osuHandlerHandle()` function (lines 68-100) in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh).

This function inspects the incoming argument and branches accordingly:

- **For `osu://` URLs:** It passes the URL directly to Wine's `start.exe`, which forwards the deep-link to the running Windows client.
- **For local files:** It resolves the absolute path, accounts for the Wine filesystem view using `PRESSURE_VESSEL_FILESYSTEMS_RW`, and executes `start.exe /ProgIDOpen "osustable.File.<ext>" <full-path>`. The ProgID lookup routes the request to `D:\osu!.exe` based on the registry entries created during setup.

## Stage 3: Process Reuse and Wine Session Management

To optimize performance, `osuHandlerHandle()` checks for an existing osu! process before launching a new Wine session. If the game is already running (detected via PID), the function sets `YAWL_VERBS=enter=$OSUPID` to inject the operation into the current Wine process (lines 74-80). This avoids the overhead of initializing a new Wine prefix session. If no instance exists, the handler launches a fresh Wine session using the `osm-handler-wine` executable.

## Practical Usage Examples

To activate or repair the handler associations, run the setup command:

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

```

To import a beatmap or skin from the Linux filesystem:

```bash
osu-wine --osuhandler /home/user/Downloads/cool_song.osz
osu-wine --osuhandler /home/user/Downloads/new_skin.osk

```

To open an osu! direct link from a browser or terminal:

```bash
osu-wine --osuhandler "osu://s/123456"

```

These commands trigger the desktop entries created by `osuHandlerSetup()`, which ultimately invoke the dispatch logic in `osuHandlerHandle()`.

## Summary

- **Dual registration system:** The handler creates Linux desktop entries for MIME types and URL schemes while simultaneously importing Windows registry entries via `stuff/osu-handler.reg`.
- **Path translation:** `osuHandlerHandle()` converts Linux paths to Wine-compatible views using `PRESSURE_VESSEL_FILESYSTEMS_RW` before passing them to `start.exe`.
- **ProgID delegation:** File associations rely on Windows ProgIDs (e.g., `osustable.File.osz`) mapped to `D:\osu!.exe` in the registry.
- **Process optimization:** The handler reuses existing Wine processes via `YAWL_VERBS=enter=$OSUPID` to avoid redundant initialization.

## Frequently Asked Questions

### How do I repair or reinstall the osu! handler file associations?

Run `./osu-winello.sh fixosuhandler`. This command triggers `osuHandlerSetup()` in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh), which regenerates the desktop entries in `~/.local/share/applications/` and re-imports `stuff/osu-handler.reg` into the Wine prefix.

### Can I click osu:// links in my browser to import beatmaps?

Yes. Once `osuHandlerSetup()` has registered the URL scheme handler (`osuwinello-url-handler.desktop`), clicking an `osu://` link in Firefox or Chrome launches `osu-wine --osuhandler %u`, which passes the URL directly to the Windows client via Wine's `start.exe`.

### Why does the handler use `start.exe` instead of launching `osu!.exe` directly?

The Windows osu! client relies on registry-based file associations (ProgIDs) to handle different file types correctly. By using `start.exe /ProgIDOpen`, the handler delegates file type detection to the Windows registry entries defined in `stuff/osu-handler.reg`, ensuring `.osz`, `.osk`, and `.osr` files open with the correct in-game importers.

### What file formats does the osu! handler support?

According to the registry entries in `stuff/osu-handler.reg` and the dispatch logic in `osuHandlerHandle()`, the handler supports `.osz` (beatmaps), `.osk` (skins), `.osr` (replays), and `.osz2` (osu!lazer archives). Each extension maps to a specific ProgID that resolves to `D:\osu!.exe`.