sekai-sus2img

A standalone SUS (Sliding Universal Score) to SVG/PNG rendering library for Project Sekai, extracted from Uni-PJSK-Viewer.

This project is a TypeScript rewrite of the python SUS rendering engine from pjsekai/scores.

Features

• Parses .sus files into typed Score models
• Supports custom timing rebase rules (rebase.json)
• Renders standard notes (Taps, Flicks, Directionals) and complex Slide paths
• Cross-platform: Uses DOM Canvas in Browser for PNG, and raw SVG string parsing
• Generates SVG vector and static PNG outputs.

Usage

import { renderSusToPng, renderSusToSvg } from 'sekai-sus2img';

const result = await renderSusToPng(
    {
        sus: '...sus file content...',
        difficulty: 'MASTER',
        playlevel: '33',
        title: 'Example',
        // Optional pixel height per second, affects the length of the score
        pixel: 240, 
    },
    {
        // Optional: Provide the base origin URL where static note assets are stored
        // The library expects to find `logo.png` and `static/notes_new/custom01/` folder inside this path.
        // If omitted, it will default to the current root `/`.
        assetOrigin: 'https://example.com' 
    }
);

console.log(result.url); // A blob: URL to display the generated PNG image

About assetOrigin

The assetOrigin option is crucial for loading note asset images (e.g. Taps, Flicks, Long notes) during the rendering process. You must host the required Project Sekai note assets on a web server because the canvas needs to fetch them via HTTP.

• Structure: Host the assets such that [assetOrigin]/static/notes_new/custom01/ contains the sliced note images (note_normal.png, note_flick.png, etc.).
• Default Behavior: If you do NOT provide assetOrigin, the library falls back to loading from / (the root of the host where the script is running), meaning it will look for /static/notes_new/....
• CORS Notice: If your assetOrigin points to a different domain, ensure the server has proper Cross-Origin Resource Sharing (CORS) headers, otherwise the SVG/Canvas will fail to fetch and embed the images.

Example Ready-to-use Asset Origins:

• You can directly use the viewer's asset origin if you don't want to host your own:

  assetOrigin: 'https://viewer.unipjsk.com'

• Or you can refer to the folder structure from the original repository and host it on your own CDN: 👉 watagashi-uni/Uni-PJSK-Viewer - public/static/notes_new

Setup & Dev

npm install
npm run build

License

MIT