vibrio

Top-level imports and types; see Lazer and LazerAsync.

class vibrio.HitStatistics(count_300: int, count_100: int, count_50: int, count_miss: int, combo: int)

Dataclass representing an osu! play in terms of individual hit statistics.

combo: int

count_100: int

count_300: int

count_50: int

count_miss: int

class vibrio.Lazer(*, port: int | None = None, self_hosted: bool = False, log_level: logging._Level = 0)

Context manager for interfacing with osu!lazer functionality (synchronously).

See also

LazerAsync

asynchronous implementation of the same functionality

Notes

This class can be used traditionally instead of as a context manager, in which case the use of start() and stop() are left up to the user. Only do this if you know what you are doing; failing to call stop() appropriately may leave an instance of the server dangling. start() will attempt to create a callback that culls any server instances on program shutdown, but proceed with caution and call stop() as necessary to avoid any possible memory leaks.

Examples

>>> from vibrio import HitStatistics, Lazer, OsuMod
>>> with Lazer() as lazer:
...     attributes = lazer.calculate_performance(
...         beatmap_id=1001682,
...         mods=[OsuMod.HIDDEN, OsuMod.DOUBLE_TIME],
...         hitstats=HitStatistics(
...             count_300=2019, count_100=104, count_50=0, count_miss=3, combo=3141
...         ),
...     )
...     attributes.total
1304.35

Attributes:

connectedbool

Whether the class instance is currently connected to a server.

Methods

calculate_difficulty(*[, beatmap_id, ...])	Calculates the difficulty parameters for a beatmap and optional mod combination.
calculate_performance(*[, beatmap_id, ...])	Calculates the performance values for a given play on a provided beatmap.
clear_cache()	Clears beatmap cache (if applicable).
get_beatmap(beatmap_id)	Returns a file stream for the given beatmap.
has_beatmap(beatmap_id)	Returns true if the given beatmap is currently stored locally.
start()	Launches and connects to vibrio server executable.
stop()	Cleans up server executable and related periphery.

calculate_difficulty(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None) → OsuDifficultyAttributes

Calculates the difficulty parameters for a beatmap and optional mod combination.

beatmap_id and beatmap specify the beatmap to be queried; exactly one of the two must be set during difficulty calculation.

Parameters:

beatmap_idint, optional

beatmapbinary file stream, optional

modslist of OsuMod enums, optional

Returns:

OsuDifficultyAttributes

Dataclass encoding the difficulty attributes of the requested map.

calculate_performance(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None, difficulty: OsuDifficultyAttributes | None = None, hit_stats: HitStatistics | None = None, replay: BinaryIO | None = None) → OsuPerformanceAttributes

Calculates the performance values for a given play on a provided beatmap.

Each query essentially requires a method of specifying the beatmap the play was made on (through exactly one of beatmap_id, beatmap or difficulty) and a method of describing the play itself (through exactly one of hit_stats and replay). However, processing a replay is not possible with difficulty attributes alone, so using difficulty requires the use of hit_stats.

Parameters:

beatmap_idint, optional

beatmapbinary file stream, optional

modslist of OsuMod enums, optional

For use with either beatmap or beatmap_id.

difficultyOsuDifficultyAttributes, optional

Difficulty attribute instance, as returned by calculate_difficulty().

hit_statsHitStatistics, optional

replaybinary file stream, optional

Returns:

OsuPerformanceAttributes

Dataclass encoding the performance values of the requested play.

clear_cache() → None

Clears beatmap cache (if applicable).

get_beatmap(beatmap_id: int) → BinaryIO

Returns a file stream for the given beatmap.

has_beatmap(beatmap_id: int) → bool

Returns true if the given beatmap is currently stored locally.

property process: Popen[bytes]

Executable process; errors if unset.

property session: BaseUrlSession

Request session; errors if unset.

start() → None

Launches and connects to vibrio server executable.

stop() → None

Cleans up server executable and related periphery.

class vibrio.LazerAsync(*, port: int | None = None, self_hosted: bool = False, log_level: logging._Level = 0)

Context manager for interfacing with osu!lazer functionality asynchronously.

See also

Lazer

synchronous implementation of the same functionality

Notes

This class can be used traditionally instead of as a context manager, in which case the use of start() and stop() are left up to the user. Only do this if you know what you are doing; failing to call stop() appropriately may leave an instance of the server dangling. start() will attempt to create a callback that culls any server instances on program shutdown, but proceed with caution and call stop() as necessary to avoid any possible memory leaks.

Examples

Note: the following example would not execute in a REPL environment as async statements must occur within async functions, but the principle still holds.

>>> from vibrio import HitStatistics, Lazer, OsuMod
>>> async with Lazer() as lazer:
...     attributes = await lazer.calculate_performance(
...         beatmap_id=1001682,
...         mods=[OsuMod.HIDDEN, OsuMod.DOUBLE_TIME],
...         hitstats=HitStatistics(
...             count_300=2019, count_100=104, count_50=0, count_miss=3, combo=3141
...         ),
...     )
...     attributes.total
1304.35

Attributes:

connectedbool

Whether the class instance is currently connected to a server.

Methods

calculate_difficulty(*[, beatmap_id, ...])	Calculates the difficulty parameters for a beatmap and optional mod combination.
calculate_performance(*[, beatmap_id, ...])	Calculates the performance values for a given play on a provided beatmap.
clear_cache()	Clears beatmap cache (if applicable).
get_beatmap(beatmap_id)	Returns a file stream for the given beatmap.
has_beatmap(beatmap_id)	Returns true if the given beatmap is currently stored locally.
start()	Launches and connects to vibrio server executable.
stop()	Cleans up server executable and related periphery.

async calculate_difficulty(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None) → OsuDifficultyAttributes

Calculates the difficulty parameters for a beatmap and optional mod combination.

beatmap_id and beatmap specify the beatmap to be queried; exactly one of the two must be set during difficulty calculation.

Parameters:

beatmap_idint, optional

beatmapbinary file stream, optional

modslist of OsuMod enums, optional

Returns:

OsuDifficultyAttributes

Dataclass encoding the difficulty attributes of the requested map.

async calculate_performance(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None, difficulty: OsuDifficultyAttributes | None = None, hit_stats: HitStatistics | None = None, replay: BinaryIO | None = None) → OsuPerformanceAttributes

Calculates the performance values for a given play on a provided beatmap.

Each query essentially requires a method of specifying the beatmap the play was made on (through exactly one of beatmap_id, beatmap or difficulty) and a method of describing the play itself (through exactly one of hit_stats and replay). However, processing a replay is not possible with difficulty attributes alone, so using difficulty requires the use of hit_stats.

Parameters:

beatmap_idint, optional

beatmapbinary file stream, optional

modslist of OsuMod enums, optional

For use with either beatmap or beatmap_id.

difficultyOsuDifficultyAttributes, optional

Difficulty attribute instance, as returned by calculate_difficulty().

hit_statsHitStatistics, optional

replaybinary file stream, optional

Returns:

OsuPerformanceAttributes

Dataclass encoding the performance values of the requested play.

async clear_cache() → None

Clears beatmap cache (if applicable).

async get_beatmap(beatmap_id: int) → BinaryIO

Returns a file stream for the given beatmap.

async has_beatmap(beatmap_id: int) → bool

Returns true if the given beatmap is currently stored locally.

property process: Process

Executable process; errors if unset.

property session: ClientSession

Request session; errors if unset.

async start() → None

Launches and connects to vibrio server executable.

async stop() → None

Cleans up server executable and related periphery.

class vibrio.OsuDifficultyAttributes(mods: list[OsuMod], star_rating: float, max_combo: int, aim_difficulty: float, speed_difficulty: float, speed_note_count: float, flashlight_difficulty: float, slider_factor: float, approach_rate: float, overall_difficulty: float, drain_rate: float, hit_circle_count: int, slider_count: int, spinner_count: int)

osu!standard difficulty attributes, as produced by osu!lazer’s internal difficulty calculation.

See also

Lazer.calculate_difficulty

LazerAsync.calculate_difficulty

aim_difficulty: float

approach_rate: float

drain_rate: float

flashlight_difficulty: float

hit_circle_count: int

max_combo: int

mods: list[OsuMod]

overall_difficulty: float

slider_count: int

slider_factor: float

speed_difficulty: float

speed_note_count: float

spinner_count: int

star_rating: float

class vibrio.OsuMod(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum representing the osu!standard mods as two-letter string codes.

AUTOPILOT = 'AP'

AUTOPLAY = 'AT'

DOUBLE_TIME = 'DT'

EASY = 'EZ'

FLASHLIGHT = 'FL'

HALF_TIME = 'HT'

HARD_ROCK = 'HR'

HIDDEN = 'HD'

NIGHTCORE = 'NC'

NO_FAIL = 'NF'

PERFECT = 'PF'

RELAX = 'RX'

SPUN_OUT = 'SO'

SUDDEN_DEATH = 'SD'

TOUCH_DEVICE = 'TD'

class vibrio.OsuPerformanceAttributes(total: float, aim: float, speed: float, accuracy: float, flashlight: float, effective_miss_count: float)

osu!standard performance attributes, as produced by osu!lazer’s internal performance calculation.

See also

Lazer.calculate_difficulty

LazerAsync.calculate_difficulty

accuracy: float

aim: float

effective_miss_count: float

flashlight: float

speed: float

total: float

The play’s total pp amount.