Appendix

Beatmap

class slider.beatmap.Beatmap(format_version, audio_filename, audio_lead_in, preview_time, countdown, sample_set, stack_leniency, mode, letterbox_in_breaks, widescreen_storyboard, bookmarks, distance_spacing, beat_divisor, grid_size, timeline_zoom, title, title_unicode, artist, artist_unicode, creator, version, source, tags, beatmap_id, beatmap_set_id, hp_drain_rate, circle_size, overall_difficulty, approach_rate, slider_multiplier, slider_tick_rate, timing_points, hit_objects)

A beatmap for osu! standard.

Parameters:

format_version : int

The version of the beatmap file.

audio_filename : str

The location of the audio file relative to the unpacked .osz directory.

audio_lead_in : timedelta

The amount of time added before the audio file begins playing. Useful selection menu.

preview_time : timedelta

When the audio file should begin playing when selected in the song for audio files that begin immediately.

countdown : bool

Should the countdown be displayed before the first hit object.

sample_set : str

The set of hit sounds to use through the beatmap.

stack_leniency : float

How often closely placed hit objects will be placed together.

mode : GameMode

The game mode.

letterbox_in_breaks : bool

Should the letterbox appear during breaks.

widescreen_storyboard : bool

Should the storyboard be widescreen?

bookmarks : list[timedelta]

The time for all of the bookmarks.

distance_spacing : float

A multiplier for the ‘distance snap’ feature.

beat_divisor : int

The beat division for placing objects.

grid_size : int

The size of the grid for the ‘grid snap’ feature.

timeline_zoom : float

The zoom in the editor timeline.

title : str

The title of the song limited to ascii characters.

title_unicode : str

The title of the song with unicode support.

artist : str

The name of the song artist limited to ascii characters.

artist_unicode : str

The name of the song artist with unicode support.

creator : str

The username of the mapper.

version : str

The name of the beatmap’s difficulty.

source : str

The origin of the song.

tags : list[str]

A collection of words describing the song. This is searchable on the osu! website.

beatmap_id : int or None

The id of this single beatmap. Old beatmaps did not store this in the file.

beatmap_set_id : int or None

The id of this beatmap set. Old beatmaps did not store this in the file.

hp_drain_rate : float

The HP attribute of the beatmap.

circle_size, : float

The CS attribute of the beatmap.

overall_difficulty : float

The OD attribute of the beatmap.

approach_rate : float

The AR attribute of the beatmap.

slider_multiplier : float

The multiplier for slider velocity.

slider_tick_rate : float

How often slider ticks appear.

timing_points : list[TimingPoint]

The timing points the the map.

hit_objects : list[HitObject]

The hit objects in the map.

Notes

This is currently missing the storyboard data.

aim_stars(*, easy=False, hard_rock=False, double_time=False, half_time=False)

The aim part of the stars.

Parameters:

easy : bool, optional

Stars with the easy mod applied.

hard_rock : bool, optional

Stars with the hard rock mod applied.

double_time : bool, optional

Stars with the double time mod applied.

half_time : bool, optional

Stars with the half time mod applied.

Returns:

aim_stars : float

The aim component of the stars.

ar(*, easy=False, hard_rock=False, half_time=False, double_time=False)

Compute the Approach Rate (AR) value for different mods.

Parameters:

easy : bool, optional

AR with the easy mod enabled.

hard_rock : bool, optional

AR with the hard rock mod enabled.

half_time : bool, optional

Effective AR with the half time mod enabled.

double_time : bool, optional

Effective AR with the double time mod enabled.

Returns:

ar : float

The effective AR value.

Notes

double_time and half_time do not actually affect the in game AR; however, because the map is sped up or slowed down, the effective approach rate is changed.

bpm_max

The maximum BPM in this beatmap.

Parameters:

half_time : bool

The BPM with half time enabled.

double_time : bool

The BPM with double time enabled.

Returns:

bpm : float

The maximum BPM in this beatmap.

bpm_min

The minimum BPM in this beatmap.

Parameters:

half_time : bool

The BPM with half time enabled.

double_time : bool

The BPM with double time enabled.

Returns:

bpm : float

The minimum BPM in this beatmap.

cs(*, easy=False, hard_rock=False)

Compute the Circle Size (CS) value for different mods.

Parameters:

easy : bool, optional

CS with the easy mod enabled.

hard_rock : bool, optional

CS with the hard rock mod enabled.

Returns:

cs : float

The CS value.

display_name

The name of the map as it appears in game.

classmethod from_file(file)

Read in a Beatmap object from an open file object.

Parameters:

file : file-like

The file object to read from.

Returns:

beatmap : Beatmap

The parsed beatmap object.

Raises:

ValueError

Raised when the file cannot be parsed as a .osu file.

classmethod from_osz_file(file)

Read a beatmap collection from a .osz file on disk.

Parameters:

file : zipfile.ZipFile

The zipfile to read from.

Returns:

beatmaps : dict[str, Beatmap]

A mapping from difficulty name to the parsed Beatmap.

Raises:

ValueError

Raised when the file cannot be parsed as a .osz file.

classmethod from_osz_path(path)

Read a beatmap collection from an .osz file on disk.

Parameters:

path : str or pathlib.Path

The file path to read from.

Returns:

beatmaps : dict[str, Beatmap]

A mapping from difficulty name to the parsed Beatmap.

Raises:

ValueError

Raised when the file cannot be parsed as a .osz file.

classmethod from_path(path)

Read in a Beatmap object from a file on disk.

Parameters:

path : str or pathlib.Path

The path to the file to read from.

Returns:

beatmap : Beatmap

The parsed beatmap object.

Raises:

ValueError

Raised when the file cannot be parsed as a .osu file.

hit_object_difficulty(*, easy=False, hard_rock=False, double_time=False, half_time=False)

Compute the difficulty of each hit object.

Parameters:

easy : bool

Compute difficulty with easy.

hard_rock : bool

Compute difficulty with hard rock.

double_time : bool

Compute difficulty with double time.

half_time : bool

Compute difficulty with half time.

Returns:

times : np.ndarray

Single column array of times as timedelta64[ns]

difficulties : np.ndarray

Array of difficulties as float64. Speed in the first column, aim in the second.

hp(*, easy=False, hard_rock=False)

Compute the Health Drain (HP) value for different mods.

Parameters:

easy : bool, optional

HP with the easy mod enabled.

hard_rock : bool, optional

HP with the hard rock mod enabled.

Returns:

hp : float

The HP value.

od(*, easy=False, hard_rock=False, half_time=False, double_time=False)

Compute the Overall Difficulty (OD) value for different mods.

Parameters:

easy : bool, optional

OD with the easy mod enabled.

hard_rock : bool, optional

OD with the hard rock mod enabled.

half_time : bool, optional

Effective OD with the half time mod enabled.

double_time : bool, optional

Effective OD with the double time mod enabled.

Returns:

od : float

The OD value.

classmethod parse(data)

Parse a Beatmap from text in the .osu format.

Parameters:

data : str

The data to parse.

Returns:

beatmap : Beatmap

The parsed beatmap object.

Raises:

ValueError

Raised when the data cannot be parsed in the .osu format.

performance_points(*, combo=None, accuracy=None, count_300=None, count_100=None, count_50=None, count_miss=None, no_fail=False, easy=False, hidden=False, hard_rock=False, double_time=False, half_time=False, flashlight=False, spun_out=False, version=1)

Compute the performance points for the given map.

Parameters:

combo : int, optional

The combo achieved on the map. Defaults to max combo.

accuracy : float, optional

The accuracy achieved in the range [0, 1]. If not provided and none of count_300, count_100, or count_50 provided then the this defaults to 100%

count_300 : int, optional

The number of 300s hit.

count_100 : int, optional

The number of 100s hit.

count_50 : int, optional

The number of 50s hit.

count_miss : int, optional

The number of misses.

no_fail : bool, optional

Account for no fail mod.

easy : bool, optional

Account for the easy mod.

hidden : bool, optional

Account for the hidden mod.

hard_rock : bool, optional

Account for the hard rock mod.

double_time : bool, optional

Account for the double time mod.

half_time : bool, optional

Account for the half time mod.

flashlight : bool, optional

Account for the flashlight mod.

spun_out : bool, optional

Account for the spun out mod.

version : int, optional

The version of the performance points calculation to use.

Returns:

pp : float

The performance points awarded for the specified play.

Notes

accuracy or hit counts may be passed as array-likes in which case the resulting pp will be a sequence of the same length. This is more efficient for computing PP with different results on the same beatmap.

Examples

>>> from slider.example_data.beatmaps import sendan_life
>>> beatmap = sendan_life("Crystal's Garakowa")
>>> # compute for 100%
>>> beatmap.performance_points(accuracy=1.0)
274.487178791355
>>> # compute for 95%  accuracy
>>> beatmap.performance_points(accuracy=0.95)
219.09554433691147
>>> # compute with explicit hit counts
>>> beatmap.performance_points(
...     count_300=330,
...     count_100=2,
...     count_50=0,
...     count_miss=0,
... )
265.20230843362657
>>> # vectorized accuracy
>>> beatmap.performance_points(
...     accuracy=[0.95, 0.96, 0.97, 0.98, 0.99, 1.0],
... )
array([ 219.09554434,  223.67413382,  230.20890527,  239.72525216, 253.74272587,  274.48717879])
>>> # with mods
>>> beatmap.performance_points(
...     accuracy=[0.95, 0.96, 0.97, 0.98, 0.99, 1.0],
...     hidden=True,
... )
array([ 245.0240618 ,  249.77318802,  256.50049755,  266.24423831, 280.54452189,  301.66016166])

rhythm_awkwardness(*, easy=False, hard_rock=False, double_time=False, half_time=False)

The rhythm awkwardness component of the song.

Parameters:

easy : bool, optional

Rhythm awkwardness with the easy mod applied.

hard_rock : bool, optional

Rhythm awkwardness with the hard rock mod applied.

double_time : bool, optional

Rhythm awkwardness with the double time mod applied.

half_time : bool, optional

Rhythm awkwardness with the half time mod applied.

Returns:

rhythm_awkwardness : float

The rhythm awkwardness score.

smoothed_difficulty(smoothing_window, num_points, *, easy=False, hard_rock=False, double_time=False, half_time=False)

Calculate a smoothed difficulty at evenly spaced points in time between the beginning of the song and the last hit object of the map.

Done by taking an average of difficulties of hit objects within a certain time window of each point

Useful if you want to calculate a difficulty curve for the map since the unsmoothed values vary locally a lot.

Parameters:

smoothing_window : int or float

Time window (in seconds) for the moving average. Bigger will make a smoother curve.

num_points : int

Number of points to calculate the average at.

easy : bool

Compute difficulty with easy.

hard_rock : bool

Compute difficulty with hard rock.

double_time : bool

Compute difficulty with double time.

half_time : bool

Compute difficulty with half time.

Returns:

difficulties : array

2D array containing smoothed time, difficulty pairs.

speed_stars(*, easy=False, hard_rock=False, double_time=False, half_time=False)

The speed part of the stars.

Parameters:

easy : bool, optional

Stars with the easy mod applied.

hard_rock : bool, optional

Stars with the hard rock mod applied.

double_time : bool, optional

Stars with the double time mod applied.

half_time : bool, optional

Stars with the half time mod applied.

Returns:

speed_stars : float

The aim component of the stars.

stars(*, easy=False, hard_rock=False, double_time=False, half_time=False)

The stars as seen in osu!.

Parameters:

easy : bool, optional

Stars with the easy mod applied.

hard_rock : bool, optional

Stars with the hard rock mod applied.

double_time : bool, optional

Stars with the double time mod applied.

half_time : bool, optional

Stars with the half time mod applied.

Returns:

stars : float

The total stars for the map.

timing_point_at(time)

Get the slider.beatmap.TimingPoint at the given time.

Parameters:

time : datetime.timedelta

The time to lookup the slider.beatmap.TimingPoint for.

Returns:

timing_point : TimingPoint

The slider.beatmap.TimingPoint at the given time.

class slider.beatmap.HitObject(position, time, hitsound, addition='0:0:0:0')

An abstract hit element for osu! standard.

Parameters:

position : Position

Where this element appears on the screen.

time : timedelta

When this element appears in the map.

hitsound : int

The hitsound to play when this object is hit.

addition : str, optional

Unknown currently.

classmethod parse(data, timing_points, slider_multiplier, slider_tick_rate)

Parse a HitObject object from a line in a .osu file.

Parameters:

data : str

The line to parse.

timing_points : list[TimingPoint]

The timing points in the map.

slider_multiplier : float

The slider multiplier for computing slider end_time and ticks.

slider_tick_rate : float

The slider tick rate for computing slider end_time and ticks.

Returns:

hit_objects : HitObject

The parsed hit object. This will be the concrete subclass given the type.

Raises:

ValueError

Raised when data does not describe a HitObject object.

class slider.beatmap.Circle(position, time, hitsound, addition='0:0:0:0')

A circle hit element.

Parameters:

position : Position

Where this circle appears on the screen.

time : timedelta

When this circle appears in the map.

class slider.beatmap.Slider(position, time, end_time, hitsound, curve, repeat, length, ticks, num_beats, tick_rate, ms_per_beat, edge_sounds, edge_additions, addition='0:0:0:0')

A slider hit element.

Parameters:

position : Position

Where this slider appears on the screen.

time : datetime.timedelta

When this slider appears in the map.

end_time : datetime.timedelta

When this slider ends in the map

hitsound : int

The sound played on the ticks of the slider.

curve : Curve

The slider’s curve function.

length : int

The length of this slider in osu! pixels.

ticks : int

The number of slider ticks including the head and tail of the slider.

num_beats : int

The number of beats that this slider spans.

tick_rate : float

The rate at which ticks appear along sliders.

ms_per_beat : int

The milliseconds per beat during the segment of the beatmap that this slider appears in.

edge_sounds : list[int]

A list of hitsounds for each edge.

edge_additions : list[str]

A list of additions for each edge.

addition : str

Hitsound additions.

class slider.beatmap.Spinner(position, time, hitsound, end_time, addition='0:0:0:0:')

A spinner hit element

Parameters:

position : Position

Where this spinner appears on the screen.

time : timedelta

When this spinner appears in the map.

end_time : timedelta

When this spinner ends in the map.

addition : str

Hitsound additions.

class slider.beatmap.HoldNote(position, time, hitsound, addition='0:0:0:0')

A HoldNote hit element.

Parameters:

position : Position

Where this HoldNote appears on the screen.

time : timedelta

When this HoldNote appears in the map.

Notes

A HoldNote can only appear in an osu!mania map.

Library

class slider.library.Library(path, *, cache=2048, download_url='https://osu.ppy.sh/osu')

A library of beatmaps backed by a local directory.

Parameters:

path : path-like

The path to a local library directory.

cache : int, optional

The amount of beatmaps to cache in memory. This uses functools.lru_cache(), and if set to None will cache everything.

download_url : str, optional

The default location to download beatmaps from.

close()

Close any resources used by this library.

copy()

Create a copy suitable for use in a new thread.

Returns:

Library

The new copy.

classmethod create_db(path, *, recurse=True, cache=2048, download_url='https://osu.ppy.sh/osu', show_progress=False)

Create a Library from a directory of .osu files.

Parameters:

path : path-like

The path to the directory to read.

recurse : bool, optional

Recursively search for beatmaps?

cache : int, optional

The amount of beatmaps to cache in memory. This uses functools.lru_cache(), and if set to None will cache everything.

download_url : str, optional

The default location to download beatmaps from.

show_progress : bool, optional

Display a progress bar?

Notes

Moving the underlying .osu files invalidates the library. If this happens, just re-run create_db again.

delete(beatmap, *, remove_file=True)

Remove a beatmap from the library.

Parameters:

beatmap : Beatmap

The beatmap to delete.

remove_file : bool, optional

Remove the .osu file from disk.

download(beatmap_id, *, save=False)

Download a beatmap.

Parameters:

beatmap_id : int or str

The id of the beatmap to download.

save : bool, optional

Save the beatmap to disk?

Returns:

beatmap : Beatmap

The downloaded beatmap.

ids

All of the beatmap ids that this has downloaded.

lookup_by_id(beatmap_id, *, download=False, save=False)

Retrieve a beatmap by its beatmap id.

Parameters:

beatmap_id : int or str

The id of the beatmap to lookup.

Returns:

beatmap : Beatmap

The beatmap with the given id.

download : bool. optional

Download the map if it doesn’t exist.

save : bool, optional

If the lookup falls back to a download, should the result be saved?

Raises:

KeyError

Raised when the given id is not in the library.

lookup_by_md5(beatmap_md5)

Retrieve a beatmap by its md5 hash.

Parameters:

beatmap_md5 : bytes

The md5 hash of the beatmap to lookup.

Returns:

beatmap : Beatmap

The beatmap with the given md5 hash.

Raises:

KeyError

Raised when the given md5 hash is not in the library.

md5s

All of the beatmap hashes that this has downloaded.

save(data, *, beatmap=None)

Save raw data for a beatmap at a given location.

Parameters:

data : bytes

The unparsed beatmap data.

beatmap : Beatmap, optional

The parsed beatmap. If not provided, the raw data will be parsed.

Returns:

beatmap : Beatmap

The parsed beatmap.

Client

class slider.client.Client(library, api_key, api_url='https://osu.ppy.sh/api')

A client for interacting with the osu! rest API.

Parameters:

library : Library

The library used to look up or cache beatmap objects.

api_key : str

The api key to use.

beatmap(*, since=None, beatmap_set_id=None, beatmap_id=None, beatmap_md5=None, user_id=None, user_name=None, game_mode=None, include_converted_beatmaps=False, limit=500)

Retrieve information about a beatmap or set of beatmaps from the osu! API.

Parameters:

since : datetime.date, optional

Return all beatmaps ranked since this date.

beatmap_set_id : str, optional

Return all beatmaps in this set.

beatmap_id : str, optional

Return the single beatmap with the given id.

beatmap_md5 : str, optional

Return the single beatmap with the given hash.

user_id : int, optional

Return beatmaps made by the given user.

user_name : str, optional

Return beatmaps made by the given user.

game_mode : GameMode, optional

Return beatmaps for the given game mode.

include_converted_beatmaps : bool, optional

Return converted beatmaps. This only applies for non-osu!standard game modes.

limit : int, optional

The maximum number of beatmaps to return. This must be less than 500.

copy()

Create a copy suitable for use in a new thread.

Returns:

Client

The new copy.

user(*, user_name=None, user_id=None, game_mode=<GameMode.standard: 0>, event_days=1)

Retrieve information about a user.

Parameters:

user_name : str

The name of the user to look up. This cannot be passed with user_id.

user_id : int

The id of the user to look up. This cannot be passed with user_name

game_mode : GameMode, optional

The game mode to look up stats for.

event_days : int, optional

Max number of days between now and last event date in the range [1, 31].

Returns:

user : User

The requested user.

user_best(*, user_name=None, user_id=None, game_mode=<GameMode.standard: 0>, limit=10, _user_ob=None)

Retrieve information about a user’s best scores.

Parameters:

user_name : str

The name of the user to look up. This cannot be passed with user_id.

user_id : int

The id of the user to look up. This cannot be passed with user_name

game_mode : GameMode, optional

The game mode to look up stats for. Defaults to osu! standard.

limit : int, optional

The number of results to return in the range [1, 100].

Returns:

high_scores : list[HighScore]

The user’s best scores.

class slider.client.BeatmapResult(library, title, version, beatmap_id, approved, approved_date, last_update, star_rating, hit_length, genre, language, total_length, beatmap_md5, favourite_count, play_count, pass_count, max_combo)

A beatmap as represented by the osu! API.

Parameters:

library : Library

The library used to store the Beatmap object.

title : str

The beatmap’s title.

version : str

The beatmap’s version.

beatmap_id : int

The beatmap_id.

approved : ApprovedState

The state of the beatmap’s approved.

approved_date : datetime.datetime

The date when this map was approved.

last_update : datetime.datetime

The last date when this map was updated.

star_rating : float

The star rating for the song.

hit_length : datetime.timedelta

The amount of time from the first element to the last, not counting breaks.

genre : Genre

The genre that appears on the osu! website.

language : Language

The language that appears on the osu! website.

total_length : datetime.timedelta

The amount of time from the first element to the last, counting breaks.

beatmap_md5 : str

The md5 hash of the beatmap.

favourite_count : int

The number of times the beatmap has been favorited.

play_count : int

The number of times this beatmap has been played.

pass_count : int

The number of times this beatmap has been passed.

max_combo : int

The maximum combo that could be achieved on this beatmap.

beatmap(*, save=False)

Lookup the associated beatmap object.

Parameters:

save : bool

If the beatmap is not in the library, should it be saved?

Returns:

beatmap : Beatmap

The associated beatmap object.

class slider.client.UnknownBeatmap(kind, id_)

Raised when a beatmap id or md5 is not known.

Parameters:

kind : {‘id’, ‘md5’}

The kind of identifier used.

id_ : str

The unknown beatmap id.

class slider.client.User(client, user_id, user_name, count_300, count_100, count_50, play_count, ranked_score, total_score, pp_rank, level, pp_raw, accuracy, count_ss, count_s, count_a, country, pp_country_rank, events, game_mode)

Information about an osu! user.

Parameters:

client : Client

The client needed to make further requests.

user_id : int

The user id.

user_name : str

The user name.

count_300 : int

The total number of 300s ever hit.

count_100 : int

The total number of 100s ever hit.

count_50 : int

The total number of 50s ever hit.

play_count : int

The total number of plays.

ranked_score : int

The user’s ranked score.

total_score : int

The user’s total score.

pp_rank : int

The user’s rank with the PP system.

level : float

The user’s level.

pp_raw : float

The user’s total unweighted PP.

accuracy : float

The user’s ranked accuracy.

count_ss : int

The number of SSs scored.

count_s : int

The number of Ss scored.

count_a : int

The number of As scored.

country : str

The country code for the user’s home country.

pp_country_rank : int

The user’s rank with the PP system limited to other players in their country.

events : list[UserEvent]

Recent user events.

game_mode : GameMode

The game mode the user information is for.

high_scores(limit=10)

Lookup the user’s high scores.

Parameters:

limit : int, optional

The number of scores to look up.

Returns:

high_scores : list[HighScore]

The user’s high scores.

class slider.client.UserEvent(library, display_html, beatmap_id, beatmapset_id, date, epic_factor)

Recent events for a user.

Parameters:

library : Library

The library used to store the Beatmap object.

display_html : str

The html to display on the osu! site.

beatmap_id : int

The beatmap_id of the event.

beatmapset_id : int

The beatmapset_id of the event.

date : datetime.date

The date of the event.

epic_factor : int

How epic was this event.

beatmap(*, save=False)

Lookup the associated beatmap object.

Parameters:

save : bool

If the beatmap is not in the library, should it be saved?

Returns:

beatmap : Beatmap

The associated beatmap object.

class slider.client.HighScore(client, beatmap_id, score, max_combo, count_300, count_100, count_50, count_miss, count_katu, count_geki, perfect, mods, user_id, date, rank, pp, _user=None)

A high score for a user or beatmap.

Parameters:

client : Client

The client used to make further requests.

beatmap_id : int

The beatmap_id of the map this is a score for.

score : int

The score earned in this high score.

max_combo : int

The max combo.

count_300 : int

The number of 300s in the high score.

count_100 : int

The number of 100s in the high score.

count_50 : int

The number of 50s in the high score.

count_miss : int

The number of misses in the high score.

count_katu : int

The number of katu in the high score.

count_geki : int

The number of geki in the high score.

perfect : bool

Did the user fc the map?

mods : set[Mod]

The mods used.

user_id : int

The id of the user who earned this high score.

rank : str

The letter rank earned. A suffix H means hidden or flashlight was used, like a silver S(S).

pp : float

The unweighted PP earned for this high score.

beatmap(*, save=False)

Lookup the associated beatmap object.

Parameters:

save : bool

If the beatmap is not in the library, should it be saved?

Returns:

beatmap : Beatmap

The associated beatmap object.

class slider.client.ApprovedState

The state of a beatmap’s approval.

WIP = -1

approved = 2

graveyard = -2

loved = 4

pending = 0

qualified = 3

ranked = 1

class slider.client.Genre

The genres that appear on the osu! website.

anime = 3

any = 0

electronic = 10

hip_hop = 9

novelty = 7

other = 6

pop = 5

rock = 4

unspecified = 1

video_game = 2

class slider.client.Language

The languages that appear on the osu! website.

any = 0

chinese = 4

english = 2

french = 7

german = 8

instrumental = 5

italian = 11

japanese = 3

korean = 6

other = 1

spanish = 10

swedish = 9

Replay

class slider.replay.Replay(mode, version, beatmap_md5, player_name, replay_md5, count_300, count_100, count_50, count_geki, count_katu, count_miss, score, max_combo, full_combo, no_fail, easy, no_video, hidden, hard_rock, sudden_death, double_time, relax, half_time, nightcore, flashlight, autoplay, spun_out, auto_pilot, perfect, key4, key5, key6, key7, key8, fade_in, random, cinema, target_practice, key9, coop, key1, key3, key2, scoreV2, life_bar_graph, timestamp, actions, beatmap)

An osu! replay.

Parameters:

mode : GameMode

The game mode.

version : int

The version of osu! used to create this replay.

beatmap_md5 : str

The md5 hash of the beatmap played in this replay.

player_name : str

The name of the player who recorded this replay.

replay_md5 : str

The md5 hash of part of the data in this replay.

count_300 : int

The number of 300’s hit in the replay.

count_100 : int

The number of 100’s hit in the replay.

count_50 : int

The number of 50’s hit in the replay.

count_geki : int

The number of geki in the replay. A geki is when the user scores all 300’s for a given color section.

count_katu : int

The number of katu in the replay. A katu is when the user completes a given color section without any 50’s or misses. All 300’s would result in a geki instead of a katu.

count_miss : int

The number of misses in the replay.

score : int

The score earned in this replay. This is the normal score, not performance points.

max_combo : int

The largest combo achieved in this replay.

full_combo : bool

Did the player earn a max combo in this replay?

no_fail : bool

Was the no_fail mod used?

easy : bool

Was the easy mod used?

no_video : bool

Was the no_video mod used?

hidden : bool

Was the hidden mod used?

hard_rock : hard_rock

Was the hard_rock mod used?

sudden_death : bool

Was the sudden_death mod used?

double_time : bool

Was the double_time mod used?

relax : bool

Was the relax mod used?

half_time : bool

Was the half_time mod used?

nightcore : bool

Was the nightcore mod used?

flashlight : bool

Was the flashlight mod used?

autoplay : bool

Was the autoplay mod used?

spun_out : bool

Was the spun_out mod used?

auto_pilot : bool

Was the auto_pilot mod used?

perfect : bool

Was the perfect mod used?

key4 : bool

Was the key4 mod used?

key5 : bool

Was the key5 mod used?

key6 : bool

Was the key6 mod used?

key7 : bool

Was the key7 mod used?

key8 : bool

Was the key8 mod used?

fade_in : bool

Was the fade_in mod used?

random : bool

Was the random mod used?

cinema : bool

Was the cinema mod used?

target_practice : bool

Was the target_practice mod used?

key9 : bool

Was the key9 mod used?

coop : bool

Was the coop mod used?

key1 : bool

Was the key1 mod used?

key3 : bool

Was the key3 mod used?

key2 : bool

Was the key2 mod used?

scoreV2 : bool

Was the scoreV2 mod used?

life_bar_graph : list[timedelta, float]

A list of time points paired with the value of the life bar at that time. These appear in sorted order. The values are in the range [0, 1].

timestamp : datetime

When this replay was created.

actions : list[Action]

A sorted list of all of the actions recorded from the player.

beatmap : Beatmap or None

The beatmap played in this replay if known, otherwise None.

classmethod from_directory(path, *, library=None, client=None, save=False, retrieve_beatmap=True)

Read in a list of Replay objects from a directory of .osr files.

Parameters:

path : str or pathlib.Path

The path to the directory to read from.

library : Library, optional

The library of beatmaps.

client : Client, optional.

The client used to find the beatmap.

save : bool, optional

If the beatmap needs to be downloaded with the client, should it be saved to disk?

retrieve_beatmap : bool, optional

Whether to retrieve the beatmap the replay is for.

Returns:

replays : list[Replay]

The parsed replay objects.

Raises:

ValueError

Raised when any file cannot be parsed as an .osr file.

classmethod from_file(file, *, library=None, client=None, save=False, retrieve_beatmap=True)

Read in a Replay object from an open file object.

Parameters:

file : file-like

The file object to read from.

library : Library, optional

The library of beatmaps.

client : Client, optional.

The client used to find the beatmap.

save : bool, optional

If the beatmap needs to be downloaded with the client, should it be saved to disk?

retrieve_beatmap : bool, optional

Whether to retrieve the beatmap the replay is for.

Returns:

replay : Replay

The parsed replay object.

Raises:

ValueError

Raised when the file cannot be parsed as a .osr file.

classmethod from_path(path, *, library=None, client=None, save=False, retrieve_beatmap=True)

Read in a Replay object from a .osr file on disk.

Parameters:

path : str or pathlib.Path

The path to the file to read from.

library : Library, optional

The library of beatmaps.

client : Client, optional.

The client used to find the beatmap.

save : bool, optional

If the beatmap needs to be downloaded with the client, should it be saved to disk?

retrieve_beatmap : bool, optional

Whether to retrieve the beatmap the replay is for.

Returns:

replay : Replay

The parsed replay object.

Raises:

ValueError

Raised when the file cannot be parsed as an .osr file.

classmethod parse(data, *, library=None, client=None, save=False, retrieve_beatmap=True)

Parse a replay from .osr file data.

Parameters:

data : bytes

The data from an .osr file.

library : Library, optional

The library of beatmaps.

client : Client, optional.

The client used to find the beatmap.

save : bool, optional

If the beatmap needs to be downloaded with the client, should it be saved to disk?

retrieve_beatmap : bool, optional

Whether to retrieve the beatmap the replay is for.

Returns:

replay : Replay

The parsed replay.

Raises:

ValueError

Raised when data is not in the .osr format.

class slider.replay.Action(offset, position, key1, key2, mouse1, mouse2)

A user action.

Parameters:

offset : timedelta

The offset since the beginning of the song.

position : Position

The position of the cursor.

key1 : bool

Is the first keyboard key pressed?

key2 : bool

Is the second keyboard key pressed?

mouse1 : bool

Is the first mouse button pressed?

mouse2 : bool

is the second mouse button pressed?

action_bitmask

Get the action bitmask from an action.

Collection

Game Modes

class slider.game_mode.GameMode

The various game modes in osu!.

ctb = 2

mania = 3

standard = 0

taiko = 1

Mods

class slider.mod.Mod

The mods in osu!

auto_pilot = 8192

autoplay = 2048

cinema = 4194304

coop = 33554432

double_time = 64

easy = 2

fade_in = 1048576

flashlight = 1024

half_time = 256

hard_rock = 16

hidden = 8

key1 = 67108864

key2 = 268435456

key3 = 134217728

key4 = 32768

key5 = 65536

key6 = 131072

key7 = 262144

key8 = 524288

key9 = 16777216

last_mod = 4194304

nightcore = 512

no_fail = 1

no_video = 4

classmethod parse(cs)

Parse a mod mask out of a list of shortened mod names.

Parameters:

cs : str

The mod string.

Returns:

mod_mask : int

The mod mask.

perfect = 16384

random = 2097152

relax = 128

relax2 = 8192

scoreV2 = 536870912

spun_out = 4096

sudden_death = 32

target_practice = 8388608

slider.mod.ar_to_ms(ar)

Convert an approach rate value to milliseconds of time that an element appears on the screen before being hit.

Parameters:

ar : float

The approach rate.

Returns:

milliseconds : float

The number of milliseconds that an element appears on the screen before

being hit at the given approach rate.

See also

slider.mod.ms_to_ar()

slider.mod.ms_to_ar(ms)

Convert milliseconds to hit an element into an approach rate value.

Parameters:

ms : float

The number of milliseconds that an element appears on the screen before being hit.

Returns:

ar : float

The approach rate value that produces the given millisecond value.

See also

slider.mod.ar_to_ms()

slider.mod.circle_radius(cs)

Compute the CS attribute into a circle radius in osu! pixels.

Parameters:

cs : float

The circle size.

Returns:

radius : float

The radius in osu! pixels.

Utilities

slider.utils.accuracy(count_300, count_100, count_50, count_miss)

Calculate osu! standard accuracy from discrete hit counts.

Parameters:

count_300 : int

The number of 300’s hit.

count_100 : int

The number of 100’s hit.

count_50 : int

The number of 50’s hit.

count_miss : int

The number of misses

Returns:

accuracy : float

The accuracy in the range [0, 1]

class slider.position.Position

A position on the osu! screen.

Parameters:

x : int or float

The x coordinate in the range.

y : int or float

The y coordinate in the range.

Notes

The visible region of the osu! standard playfield is [0, 512] by [0, 384]. Positions may fall outside of this range for slider curve control points.

class slider.bit_enum.BitEnum

A type for enums representing bitmask field values.

classmethod pack(**kwargs)

Pack a bitmask from explicit bit values.

Parameters:

kwargs

The names of the fields and their status. Any fields not explicitly passed will be set to False.

Returns:

bitmask : int

The packed bitmask.

classmethod unpack(bitmask)

Unpack a bitmask into a dictionary from field name to field state.

Parameters:

bitmask : int

The bitmask to unpack.

Returns:

status : dict[str, bool]

The mapping from field name to field status.