maimai Session Report

Session reports, rating progress, and practice targets.

Turn a maimai DX session into a report you can keep as a single HTML file. See what improved, how your Old 35 / New 15 pools changed, and which charts are close to the next rating gain. Four interactive views cover your scorecard, scores, rating pools and practice targets, with search, score details and a mobile layout.

Start with the fictional offline demo below. For your own scores, the CLI reads Kamaitachi personal bests and recent plays, requests one already-configured MYT import, waits over server-sent events, and reads the results once. Sync happens only when you explicitly request it.

Reports contain personal play history. Keep your output and any runner repository private. Default reports have embedded data, CSS and JavaScript, with no browser network requests on load, analytics, remote fonts or account requirement to open the file. The optional developer-support checkout contacts Buy Me a Coffee only after you click its button; report data stays in the report.

See the report

All names, songs and scores in these browser screenshots are fictional demo data. Cover tiles marked DEMO are original fictional artwork. Rating badges use the original game frames sourced through Tomomai, including all 12 tiers; their ownership is separate from the software license. Artwork provenance.

See the phone layout

See the detailed Scores view

See the Rating pools view

The pool lists continue below the screenshot; all 50 counted charts are included in the sample report.

See the practice Targets view

Try the interactive sample HTML report: save the raw file as sample-report.html, then open it in your browser. All four views work offline. No account, installation or hosted demo site is needed. Or generate the same file yourself with the five commands below.

Choose how far you want to go

I want to…	Start here	Accounts needed
Try the report	Five commands below	None
Generate my report locally	Local setup	Your configured Kamaitachi/MYT account
Run manually in GitHub Actions and download a report	Private artifact workflow	A private copy and a Kamaitachi secret
Keep a protected site and session history	Hosted installation	A private runner, Cloudflare and your own protected hostname

The local path is a complete product. Hosting, history, B50 image export, song jackets and a support footer are optional. You do not need Node.js, Cloudflare, Docker or a database to generate the normal report.

Five-command offline demo

Install Python 3.11 or newer and Git first. Only cloning needs the network; the remaining commands use no credentials or external packages.

Windows PowerShell

git clone https://github.com/arussin/maimai-session-report.git
py -3 -m venv .\maimai-session-report\.venv
& .\maimai-session-report\.venv\Scripts\python.exe -m pip install --no-index --no-deps .\maimai-session-report
& .\maimai-session-report\.venv\Scripts\maimai-report.exe demo --output .\maimai-session-report\output\demo-report.html
& .\maimai-session-report\.venv\Scripts\maimai-report.exe serve --file .\maimai-session-report\output\demo-report.html

macOS / Linux

git clone https://github.com/arussin/maimai-session-report.git
python3 -m venv maimai-session-report/.venv
maimai-session-report/.venv/bin/python -m pip install --no-index --no-deps ./maimai-session-report
maimai-session-report/.venv/bin/maimai-report demo --output maimai-session-report/output/demo-report.html
maimai-session-report/.venv/bin/maimai-report serve --file maimai-session-report/output/demo-report.html

Open the printed localhost address; Ctrl+C stops the server. You can also open output/demo-report.html directly. On Linux, install your distribution's Python venv package if creating the environment reports that ensurepip is missing. Check that your selected Python is at least 3.11.

All demo songs and scores are fictional. To inspect empty or incomplete pools, add --scenario empty or --scenario incomplete to the demo command.

Make it yours

From the cloned directory, activate the virtual environment and copy config.example.toml to config.toml. Edit just the username, display name, timezone and current-version names to start. Leave publishing disabled.

Follow the token setup to place your own token in KAMAITACHI_API_TOKEN for the current shell. Tokens are never command-line arguments or TOML values.

maimai-report doctor
maimai-report sync-and-render --output output/report.html
maimai-report serve --file output/report.html

That sync command saves the HTML and private JSON inputs under output/. You can render the saved inputs again without another import:

maimai-report render --report-input output/report-input.json --after-pbs output/after-pbs.json --output output/report.html

Every command also supports python -m maimai_report. Full local instructions and troubleshooting cover shell setup, tokens, timezones, output cleanup, API/SSE failures and all commands.

Account and MYT prerequisites

Use a Kamaitachi account with the MYT integration already working in Kamaitachi. Set it up in that service's own UI; this project neither supplies account access nor collects integration codes. It calls only the publicly exposed Kamaitachi importer. Public upstream references and scope explain that boundary without documenting service internals.

Current maimai version

Set report.current_version_display_names to the exact chart.data.displayVersion strings used by Kamaitachi for the current release. Check those names when the game changes version. There is no hard-coded current release, and a live sync fails before network access if the list is empty. See configuration.

Optional extras

• Rating artwork packs: all original tier frames are included; export and customize a local pack, or select the CSS-only plain alternative.
• Song jackets: fetched from public artwork sources at build time and embedded; ordinary local rendering remains offline.
• Protected hosting and history: a seven-file private runner uses shared code pinned to a full commit. This needs Cloudflare setup; choose it when you want an ongoing website, not merely to view one report.
• B50 image export: powered by shedaniel/Tomomai, with its own AGPL license and build dependencies.
• Developer support: a removable footer is included by default. Clicking it opens an isolated in-page checkout; nothing loads in the background.

The HTML also works on an ordinary static host. An unprotected host can expose the whole report, regardless of whether search engines index it.

Support development

If maimai Session Report is useful to you, buy the developer a maimai credit. Reports include the same optional checkout, with no payment setup needed. To hide it, set enabled = false under [support] or generate with --no-support.

Upgrading an installation

Existing installations stay on their current full-commit pins until you choose to upgrade. Updating this repository does not update your private runner. Do not rerun bootstrap or recreate storage just to adopt this repository.

The Python distribution is maimai-session-report; the command stays maimai-report and the module stays maimai_report. The root, render/, archive/, history/ and installation/ action interfaces are preserved. For an intentional upgrade, follow migration.

Development and project notes

See contributing for the tested development setup, architecture for the data flow, and security for reporting issues using synthetic examples.

Independent community software, not affiliated with the game or integration providers. Core code uses the MIT license; the optional Tomomai adapter uses AGPLv3. Third-party artwork retains its own rights. See third-party notices and artwork provenance for credits and license details.