osu-parser

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 ;)

• Installation
• Usage
• The resulting object
• Methods
  • parseFile(filepath, callback)
  • parseStream(stream, callback)
  • parseContent(content)
• TODO
• Changelog

Installation

npm install osu-parser

Usage

  var parser = require('osu-parser');

  parser.parseFile('path/to/map.osu', function (err, beatmap) {
    console.log(beatmap);
  });

The resulting object

Simple key/value entries like this...

...
PreviewTime: 42860
...

...are directly reachable as properties :

console.log(beatmap['PreviewTime']);
// prints 42860

Additionnal beatmap properties :

name	type	description
fileFormat	String	osu file format (v7, v12...).
bgFilename	String	name of the background image.
nbCircles	Integer	number of circles.
nbSliders	Integer	number of sliders.
nbSpinners	Integer	number of spinners.
bpmMin	Integer	minimum bpm.
bpmMax	Integer	maximum bpm.
maxCombo	Integer	maximum combo.
totalTime	Integer	total time in seconds.
drainingTime	Integer	draining time in seconds.
tagsArray	Array	tags splitted into an array, for convenience.
breakTimes	Array	list of all break times. Each has startTime and endTime properties.
timingPoints	Array	list of all timing points. See TimingPoint below.
hitObjects	Array	list of all hitobjects. See HitObject below.

TimingPoint properties

name	type	description
offset	Integer	offset in milliseconds.
beatLength	Float	length of a single beat in milliseconds. Inherited from previous timing point if negative.
bpm	Float	number of beats per minute. Inherited from previous timing point if beatLength is negative.
velocity	Float	velocity multiplicator.
timingSignature	Integer	3 = simple triple, 4 = simple quadruple (used in editor).
sampleSetId	Integer	sound samples. None = 0, Normal = 1, Soft = 2.
customSampleIndex	Integer	index of the custom sound samples. (0 if none)
sampleVolume	Integer	volume of the samples.
timingChange	Boolean	is there a beatLength change ?
kiaiTimeActive	Boolean	is it a kiai section ?

HitObject properties

name	type	description
objectName	String	circle, slider, spinner or unknown.
position	Array[Integer]	object position : [x,y]
startTime	Integer	start offset.
newCombo	Boolean	is it a new combo ?
soundTypes	Array	list of sound effects. Those can be : normal, whistle, finish, clap.
additions	Object	hitobject specific additions. It can have those properties : -sample: object specific sample. It can be : soft, normal, drum. -additionalSample: the sample to use for additional sounds (finish, whistle, clap). 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
repeatCount	Integer	number of repeats, starts at 1 for a single-way slider.
pixelLength	Integer	length in osu-relative pixels.
duration	Integer	duration in milliseconds, rounded to the upper integer.
endTime	Integer	end offset.
curveType	String	can be catmull, bezier, linear or pass-through.
points	Array	list of all points including the very first. Each point is an array of coordinates [x,y].
endPosition	Array	coordinates of the slider end ([x,y]). (not calculated for catmull)
edges	Array	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
endTime	Integer	end offset.

Methods

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) {
    console.log(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) {
    console.log(beatmap);
  });

parseContent(content)

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);

TODO

• 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)
• ...