osrparse, a python parser for osu! replays

This is a parser for osu! replay files (.osr) as described by https://osu.ppy.sh/wiki/en/osu%21_File_Formats/Osr_%28file_format%29.

Installation

To install, simply:

pip install osrparse

Documentation

Parsing

To parse a replay from a filepath:

from osrparse import parse_replay_file

# returns a Replay object
replay = parse_replay_file("path/to/osr.osr")

To parse a replay from an lzma string (such as the one returned from the /get_replay osu! api endpoint):

from osrparse import parse_replay

# returns a Replay object that only has a `play_data` attribute
replay = parse_replay(lzma_string, pure_lzma=True)

Note that if you use the /get_replay endpoint to retrieve a replay, you must decode the response before passing it to osrparse, as the response is encoded in base 64 by default.

Dumping

Existing Replay objects can be "dumped" back to a .osr file:

replay.dump("path/to/osr.osr")
# or to an opened file object
with open("path/to/osr.osr") as f:
    replay.dump(f)

You can also edit osr files by parsing a replay, editing an attribute, and dumping it back to its file:

replay = parse_replay_file("path/to/osr.osr")
replay.player_name = "fake username"
replay.dump(""path/to/osr.osr")

Attributes

Replay objects have the following attibutes:

self.game_mode        # GameMode enum
self.game_version     # int
self.beatmap_hash     # str
self.player_name      # str
self.replay_hash      # str
self.number_300s      # int
self.number_100s      # int
self.number_50s       # int
self.gekis            # int
self.katus            # int
self.misses           # int
self.score            # int
self.max_combo        # int
self.is_perfect_combo # bool
self.mod_combination  # Mod enum
self.life_bar_graph   # str, currently unparsed
self.timestamp        # datetime.datetime object
# list of either ReplayEventOsu, ReplayEventTaiko, ReplayEventCatch,
# or ReplayEventMania objects, depending on self.game_mode
self.play_data

ReplayEventOsu objects have the following attributes:

self.time_delta # int, time since previous event in milliseconds
self.x          # float, x axis location
self.y          # float, y axis location
self.keys       # Key enum, keys pressed

ReplayEventTaiko objects have the following attributes:

self.time_delta # int, time since previous event in milliseconds
self.x          # float, x axis location
self.keys       # KeyTaiko enum, keys pressed

ReplayEventCatch objects have the following attributes:

self.time_delta # int, time since previous event in milliseconds
self.x          # float, x axis location
self.dashing    # bool, whether the player was dashing or not

ReplayEventMania objects have the following attributes:

self.time_delta # int, time since previous event in milliseconds
self.keys       # KeyMania enum

The Key enums used in the above ReplayEvents are defined as follows: