If you have ever tried to build a tool around osu! skins (a previewer, a converter, a "which skin is this?" bot), you hit skin.ini within the first hour. It looks like a plain INI file. It is not quite one. Here are the quirks I ran into while indexing a few thousand skins for osuskins.org, and a small Python parser that survives real-world files.
What is actually inside an .osk
An .osk file is just a ZIP archive with a different extension. Inside you get images (hitcircle.png, cursor@2x.png, default-0.png...), sounds (normal-hitclap.wav...) and, usually, a skin.ini. Sometimes the whole skin sits inside one extra top-level folder, so do not assume skin.ini is at the root:
import zipfile
def find_skin_ini(osk_path):
with zipfile.ZipFile(osk_path) as z:
candidates = [n for n in z.namelist() if n.lower().endswith("skin.ini")]
# shortest path wins: the real one, not a backup in a subfolder
candidates.sort(key=lambda n: n.count("/"))
return candidates[0] if candidates else None
Note .lower(): file names inside skins come from Windows users, so Skin.ini, SKIN.INI and skin.ini all appear in the wild.
The quirks
1. Encoding is a lottery. Most files are UTF-8, many have a BOM, and older ones from Japanese, Korean or Russian creators are in Shift-JIS, CP949 or CP1251. Decode with utf-8-sig first and fall back, rather than crashing on byte 0x82.
2. Comments are //, not ;. Python's configparser will choke on them, and on duplicate keys, and on the repeated [Mania] sections (see below). Write your own line parser; it is 30 lines.
3. Sections repeat. [Mania] appears once per key count, each block starting with Keys: 4, Keys: 7 and so on. Treat it as a list, keyed by the Keys value.
4. Separators are : and whitespace is everywhere. Name: Rafis, Name:Rafis and Name : Rafis all show up.
5. Colours are r,g,b or r,g,b,a, sometimes with spaces, occasionally with a stray trailing comma. Combo1 to Combo8 define combo colours; if none are given the game uses its defaults.
6. Version changes behaviour. Version: 1.0, 2.0, 2.5, 2.7 or latest controls how some elements are drawn (for example the old vs. new spinner and the mania layout). A missing Version key in an existing skin.ini means 1.0, which surprises people whose "modern" skin suddenly renders with legacy rules.
7. Missing files fall back to the default skin. A skin that only ships a cursor and hit circles is perfectly valid. Your previewer needs the default assets on hand, or it will show holes.
A parser that survives real files
import re
ENCODINGS = ("utf-8-sig", "shift_jis", "cp949", "cp1251", "latin-1")
def decode(raw: bytes) -> str:
for enc in ENCODINGS:
try:
return raw.decode(enc)
except UnicodeDecodeError:
continue
return raw.decode("utf-8", errors="replace")
def parse_skin_ini(raw: bytes) -> dict:
data = {"mania": []}
section = None
current = None
for line in decode(raw).splitlines():
line = line.split("//", 1)[0].strip()
if not line:
continue
m = re.match(r"^\[(.+?)\]$", line)
if m:
section = m.group(1).strip().lower()
if section == "mania":
current = {}
data["mania"].append(current)
else:
current = data.setdefault(section, {})
continue
if ":" not in line or current is None:
continue
key, value = (p.strip() for p in line.split(":", 1))
current[key] = value # last one wins, like the game
return data
def colour(value: str):
parts = [p.strip() for p in value.split(",") if p.strip()]
nums = [max(0, min(255, int(float(p)))) for p in parts[:4]]
return tuple(nums) if len(nums) >= 3 else None
Usage:
ini = parse_skin_ini(open("skin.ini", "rb").read())
general = ini.get("general", {})
print(general.get("Name"), "by", general.get("Author"))
combos = [colour(v) for k, v in sorted(ini.get("colours", {}).items())
if k.lower().startswith("combo")]
print([c for c in combos if c])
for block in ini["mania"]:
print(block.get("Keys"), "keys, column width:", block.get("ColumnWidth"))
Splitting on // naively would break a URL in a value, but skin.ini values almost never contain URLs, and the game itself treats // as a comment start, so matching the game is the right call.
Things worth extracting for a catalogue
When I index skins, these fields turned out to be the most useful for players browsing:
-
Name,Author,Versionfrom[General] - combo colours (great for "show me blue skins" filters)
- which modes the skin actually skins: look for
taiko-*,fruit-*andmania-*images, plus[Mania]blocks - whether HD (
@2x) assets exist - cursor settings like
CursorExpandandCursorRotate, which players care about a lot
Try it on real skins
If you want a pile of real-world files to test against, osuskins.org lists thousands of skins with the creator credited and direct, link-checked downloads (no ad-gate, no login). The install guide is handy if you are new to osu! and want to see how the game loads what you just parsed, and the in-browser skin editor shows the same skin.ini fields as a form.
If you find a skin.ini quirk I missed, tell me in the comments. There is always one more.
Top comments (0)