osu-2-json

osu-2-json is a tool to parse and convert .osu beatmap files into JSON format for easy processing.

Install and Run

To install the dependencies, run:

npm install

You can use the CLI to convert an osu! file to JSON format. Run the following command:

npm run cli -- -f <PATH_TO_OSU_FILE>

Replace <PATH_TO_OSU_FILE> with the path to the .osu file you want to convert.

Example:

npm run cli -- -f osu-files/The\ Quick\ Brown\ Fox\ -\ The\ Big\ Black\ \(Blue\ Dragon\)\ \[WHO'S\ AFRAID\ OF\ THE\ BIG\ BLACK\].osu

This will output the parsed JSON data to the console.

Sample Output

{
  "General": {
    "AudioFilename": "audio.mp3",
    "AudioLeadIn": 0,
    "PreviewTime": 0,
    "Countdown": 0,
    "SampleSet": "Normal",
    "StackLeniency": 0.7,
    "Mode": 0,
    "LetterboxInBreaks": 0
  },
  "Metadata": {
    "Title": "Sample Title",
    "Artist": "Sample Artist",
    "Creator": "Sample Creator",
    "Version": "Sample Version",
    "Source": "",
    "Tags": ["sample", "tags"]
  },
  "Difficulty": {
    "HPDrainRate": 5,
    "CircleSize": 4,
    "OverallDifficulty": 7,
    "ApproachRate": 9,
    "SliderMultiplier": 1.4,
    "SliderTickRate": 1
  },
  "HitObjects": [
    {
      "x": 256,
      "y": 192,
      "time": 1000,
      "type": 1,
      "hitSound": 0
    },
    {
      "x": 128,
      "y": 64,
      "time": 2000,
      "type": 1,
      "hitSound": 0
    }
  ]
}

Project Structure

osu-2-json/
├── src/
│   ├── cli.ts          # The CLI entry point
│   ├── lib/
│   │   ├── @types/
│   │   │   └── osu-2-json.d.ts  # Type definitions for the osu! file structure
│   │   ├── index.ts    # Exports the functions from osu-2-json.ts
│   │   └── osu-2-json.ts  # The main logic for converting osu! files to JSON
└── package.json        # Project metadata and dependencies

Additional Documentation

For more detailed information about the .osu file format, please refer to the official osu! wiki:

osu! File Formats - .osu (file format)

License

This project is licensed under the ISC License. See the LICENSE file for details.