rssp - Rust Stepmania Simfile Parser

rssp is a high-performance, correctness-first Rust library (with a CLI) for parsing and analyzing StepMania simfiles (.sm, .ssc) and a subset of course files (.crs). It focuses on detailed analysis of dance charts (primarily 4-panel / 8-panel) and is designed to batch-process large song libraries quickly.

It also powers the simfile parser in the DeadSync game engine, where it's included as a Git submodule.

Correctness & Parity

For the fields that rssp parses and computes, the goal is 100% parity with the reference behavior from:

• ITGmania (engine/parser/timing/tech counts)
• Simply Love (hashing/breakdowns)

Golden outputs are generated with itgmania-reference-harness, and the test corpus is stored in rssp-tests (included here as the tests/data submodule).

Inspiration

This project is inspired by Breakdown Buddy and builds upon ideas from simfile-sidekick by Steven Artim (artimst).

Motivation

Why create another simfile parser?

• Focus & Flexibility: While previous tools might have focused on integrating with databases or Discord bots, rssp is primarily designed for direct command-line analysis of individual simfiles. However, its speed makes it trivial to script for processing thousands of files.
• Performance: The previous Python-based tool could take many minutes to process large collections (10k+ files). This Rust implementation achieves significantly better performance and is designed to process large libraries quickly.
• Enhanced Statistics & Features: rssp aims to add features and refine statistics, including:
  • Generating ITGmania-style chart hashes (SHA1-derived, 64-bit).
  • Detection of a wider range of predefined step patterns.
  • An improved algorithm for detecting monotonic (mono) stepping sequences.
  • Parsing of common technical notations embedded in chart metadata.
  • The ability to strip common "tournament tags" from song titles for cleaner output.

Features

• Simfile Parsing: Supports .sm and .ssc formats.
• Course Parsing (partial): Supports .crs with fixed #SONG entries (no RANDOM/BEST/WORST/SONGSELECT yet).
• Metadata Extraction: Retrieves Title, Subtitle, Artist, Transliterations, Offset, BPMs, etc.
• Tag Cleaning: Optionally strips common leading tags (e.g., [Foo], 123- ) from titles.
• Chart Statistics: Calculates comprehensive stats per chart:
  • Total Arrows, Arrow counts per direction (L/D/U/R)
  • Total Steps (lines with at least one arrow)
  • Jumps, Hands, Holds, Rolls, Mines
• Density Analysis:
  • Calculates Notes Per Second (NPS): Median and Peak.
  • Counts measures of different stream densities (16ths, 20ths, 24ths, 32nds) and break measures.
  • Generates Stamina Nation (SN) chart breakdowns in Detailed, Partial, and Simplified formats.
  • Calculates Stream Percentage (raw and adjusted).
  • Computes a "Tier BPM" based on sustained density and BPM.
• Difficulty Rating:
  • Calculates a Matrix Rating by aggregating stream sections and applying a difficulty matrix.
• Pattern Detection (4-panel): Identifies various common and complex step patterns:
  • Candles (Left/Right) & Candle Percentage
  • Mono (Left-Facing/Right-Facing) & Mono Percentage (configurable threshold)
  • Boxes (LR, UD, Corners)
  • Anchors (L, D, U, R)
  • Towers, Triangles, Staircases (Regular, Alt, Double, Inverted)
  • Sweeps (Regular, Candle, Inverted)
  • Copters, Spirals, Turbo Candles, Hip Breakers, Doritos, Luchis (and their inverted variants)
• Technical Notation Parsing: Extracts known technical notations (e.g., STR+, BXF, FS-) from the Credit/Description fields.
• Hashing: Generates ITGmania-style chart hashes (first 8 bytes of SHA1; shown as 16 hex chars):
  • Standard hash (minimized notes + effective BPMs)
  • BPM-neutral hash (minimized notes + 0.000=0.000)
• Multiple Output Formats:
  • Pretty: Human-readable summary (Default).
  • Full: Detailed text output including all patterns and stats.
  • JSON: Machine-readable structured output.
  • CSV: Comma-separated values, one row per chart.
• Density Graph Generation: Optionally creates PNG images visualizing the NPS density over the chart's duration (standard and alternative color schemes available).

Installation

1. Install Rust: If you don't have Rust installed, get it from rustup.rs.
2. Clone the Repository:

   git clone https://github.com/pnn64/rssp.git
   cd rssp
   # Optional: fetch the parity corpus + baselines (large)
   git submodule update --init --recursive
   

3. Build the Project:

   cargo build --release
   

   The executable will be located at target/release/rssp. You can copy this to a directory in your system's PATH for easier access.

Library

The CLI in src/main.rs is a thin wrapper around the public library API.

let sim = rssp::simfile::open("song.ssc")?;
let opts = rssp::AnalysisOptions { mono_threshold: 6, ..Default::default() };
let summary = rssp::analyze(&sim.data, sim.extension, opts)?;

Usage

Common invocations are:

rssp <path/to/simfile_or_folder> [options]
rssp <path/to/course.crs> [course options] [options]
rssp --matrix --bpm <BPM> --measures <MEASURES>

Arguments:

• <path/to/simfile_or_folder>: Required. The path to a simfile (.sm / .ssc), a course (.crs), or a folder containing simfiles.
  • Single File: Analyzes the specified simfile.
  • Folder: Recursively scans the folder for simfiles. When both .sm and .ssc files exist in the same directory, the .ssc file is preferred.
  • Course (.crs): Analyzes a course (fixed #SONG entries only). You may need to pass --songs-dir if Songs/ cannot be located automatically.

Options:

• --full: Output the detailed "Full" report format instead of the default "Pretty" summary.
• --json: Output the report in JSON format.
• --csv: Output the report in CSV format (header row followed by one data row per chart).
• --png: Generate a density graph PNG image for each chart (using the default color scheme). The filename will be <chart_hash>.png.
• --png-alt: Generate a density graph PNG image for each chart (using the alternative color scheme). The filename will be <chart_hash>-alt.png.
• --strip-tags: Clean common prefixes like [TAG] or 123- from the song title before displaying.
• --debug: Print the minimized chart note data to stderr alongside the chosen report.
• --skip-tech: Skip step parity / tech count analysis.
• --skip-slow: Skip slower analysis (--skip-tech plus pattern detection).
• --mono-threshold <N>: Set the minimum number of consecutive steps required to count a segment as "mono" (default: 6). <N> must be a positive integer.
• --custom-pattern <PATTERN>: Count a custom LRUDN pattern (repeatable; e.g. DULDUDLR).
• --matrix: Matrix rating mode (no file input). Requires --bpm (-b) and --measures (-m).

Course options (.crs only):

• --songs-dir <PATH>: Path to Songs/ (used to resolve #SONG entries).
• --course-difficulty <DIFF> / --course-diff <DIFF>: Target course difficulty (default: Medium).
• --steps-type <TYPE> / --stepstype <TYPE>: Steps type to select (default: dance-single).

Examples:

• Show the default pretty report for a .sm file:

  ./rssp "My Songs/Cool Song/Cool Song.sm"
  

• Generate a JSON report for an .ssc file:

  ./rssp "/path/to/itg/packs/Hard Stuff/My Fav/My Fav.ssc" --json
  

• Generate the Full report and a density graph PNG:

  ./rssp song.sm --full --png
  

• Generate a CSV report with a higher mono threshold and stripped title tags:

  ./rssp song.ssc --csv --mono-threshold 8 --strip-tags
  

• Analyze an entire folder recursively:

  ./rssp "C:/Games/ITGmania/Songs" --csv
  

• Analyze a specific pack folder:

  ./rssp "Songs/MyCrazyPack" --json
  

• Save folder analysis results to a file using shell redirection:

  ./rssp "Songs/MyPack" --csv > output.csv
  

• Calculate a matrix rating without analyzing a file, use the --matrix flag with BPM and measure counts:

  ./rssp --matrix --bpm <BPM> --measures <MEASURES>
  

• Analyze a course file:

  ./rssp "Courses/MyCourse.crs" --songs-dir "C:/Games/ITGmania/Songs" --json
  

Output Formats

• Pretty (Default): A human-readable summary focusing on key song details, BPM, NPS, core stats (steps, jumps, hands, etc.), and primary patterns (Candles, Mono, Boxes, Anchors). Includes simplified SN breakdowns if available.
• Full: A comprehensive text output including all song metadata, detailed BPM info, full chart stats, all detected pattern counts (including complex ones like sweeps, spirals, etc.), and the detailed/partial/simplified SN breakdowns.
• JSON: A structured JSON object containing all song and chart information, suitable for programmatic use. Fields are grouped logically (e.g., chart_info, arrow_stats, pattern_counts).
• CSV: A header row followed by one data row per chart. Contains a flattened representation of most song and chart statistics, suitable for spreadsheets or data analysis pipelines.
• PNG / PNG-Alt: Generates density graph