node package manager


converts osu files into javascript objects


Build Status

A parser for Nodejs that converts osu files into javascript objects. Feel free to give it a try and post issues to help me improve it ;)


npm install osu-parser


  var parser = require('osu-parser');
  parser.parseFile('path/to/map.osu', function (err, beatmap) {

The resulting object

Simple key/value entries like this...

PreviewTime: 42860

...are directly reachable as properties :

// prints 42860

Additionnal beatmap properties :

name type description
fileFormatStringosu file format (v7, v12...).
nbCirclesIntegernumber of circles.
nbSlidersIntegernumber of sliders.
nbSpinnersIntegernumber of spinners.
bpmMinIntegerminimum bpm.
bpmMaxIntegermaximum bpm.
maxComboIntegermaximum combo.
totalTimeIntegertotal time in seconds.
drainingTimeIntegerdraining time in seconds.
tagsArrayArraytags splitted into an array, for convenience.
breakTimesArraylist of all break times. Each has startTime and endTime properties.
timingPointsArraylist of all timing points. See TimingPoint below.
hitObjectsArraylist of all hitobjects. See HitObject below.

TimingPoint properties

name type description
offsetIntegeroffset in milliseconds.
beatLengthFloatlength of a single beat in milliseconds. Inherited from previous timing point if negative.
bpmFloatnumber of beats per minute. Inherited from previous timing point if beatLength is negative.
velocityFloatvelocity multiplicator.
timingSignatureInteger3 = simple triple, 4 = simple quadruple (used in editor).
sampleSetIdIntegersound samples. None = 0, Normal = 1, Soft = 2.
customSampleIndexIntegerindex of the custom sound samples. (0 if none)
sampleVolumeIntegervolume of the samples.
timingChangeBooleanis there a beatLength change ?
kiaiTimeActiveBooleanis it a kiai section ?

HitObject properties

name type description
objectNameStringcircle, slider, spinner or unknown.
positionArray[Integer]object position : [x,y]
startTimeIntegerstart offset.
newComboBooleanis it a new combo ?
soundTypesArraylist of sound effects. Those can be : normal, whistle, finish, clap.
additionsObject hitobject specific additions. It can have those properties :
-sample: object specific sample. It can be : soft, normal, drum.
-additionalSample: a sample to add along with the current one. It can be : soft, normal, drum.
-customSampleIndex: index of the custom sample to use (ex: normal-2).
-hitsoundVolume: specific volume for this object (require hitsound to be an existing file).
-hitsound: a file to use as hitsound. It disables all other hitsounds.
Slider specific properties
name type description
repeatCountIntegernumber of repeats, starts at 1 for a single-way slider.
pixelLengthIntegerlength in osu-relative pixels.
durationIntegerduration in milliseconds, rounded to the upper integer.
endTimeIntegerend offset.
curveTypeStringcan be catmull, bezier, linear or pass-through.
pointsArraylist of all points including the very first. Each point is an array of coordinates [x,y].
endPositionArraycoordinates of the slider end ([x,y]). (not calculated for catmull)
edgesArray list of edges. The number of edges is repeatCount + 1. Each one has two properties :
-soundTypes: list of sound effects. Those can be : normal, whistle, finish, clap.
-additions: edge additions. Same as hitobject additions, but can only have sample and additionalSample.
Spinner specific properties
name type description
endTimeIntegerend offset.


parseFile(filepath, callback)

Parse the given file. The callback returns (error, beatmap).

  var parser = require('osu-parser');
  parser.parseFile('path/to/map.osu', function (err, beatmap) {

parseStream(stream, callback)

Parse a stream containing a file content. The callback returns (error, beatmap).

  var parser = require('osu-parser');
  var fs     = require('fs');
  var stream = fs.createReadStream('path/to/map.osu');
  parser.parseStream(stream, function (err, beatmap) {


Parse the content of a file as a string or a buffer.

  var parser  = require('osu-parser');
  var fs      = require('fs');
  var content = fs.readFileSync('path/to/map.osu');
  var beatmap = parser.parseContent(content);


  • translate the samplesetId of timing points
  • parse events
  • make tests more reliable
  • add a synchronous version of parseFile
  • make it usable in a browser ? (not sure that would be useful)
  • ...