danser-go turns osu! maps and replays into videos you can render yourself

It reads a map and replays it, then writes video

danser-go is described in the README as a GUI/CLI visualisation tool for osu!standard maps, and it can also record osu! mode replays, both stable and lazer, to mp4. The project description puts it more strongly, a dancing visualizer of osu! standard maps and custom osu! client written in Go, and also a generator for osu! videos.

The three roles overlap, and the video output is the one that differentiates it from a game client. A custom client plays the game for you. A visualiser draws the map and the cursor movement. A video generator produces a file you can upload. danser-go does all three from the same engine, which is why the recording flags sit alongside the map selection flags rather than in a separate tool.

The tool works from files you already have. The map selection arguments look for a .osu file on disk, by artist, title, difficulty name, MD5 hash or BeatmapID, and the replay flag takes a path to an .osr file. Nothing in the CLI list fetches maps from the internet, so the tool is a renderer for your own library rather than a downloader.

The primary language is Go, the module is github.com/wieku/danser-go, and the last push to the repository was on 2026-10-11 with release 0.12.1 tagged the same day, following 0.12.0 on 2026-10-04. The licence field on the repository says Other, a custom licence GitHub cannot classify, with the details in the LICENSE file.

Windows and Linux binaries, and no macOS at all

The distribution story is short, and one platform is missing on purpose.

You can download the newest Windows and Linux 64-bit binaries from the releases page. After unpacking to a directory, you run it through the launcher using the danser executable, or through a command line application or terminal, where the binary is danser-cli.

./danser-cli <arguments>

On Windows cmd the invocation is the same binary without the path prefix.

danser-cli <arguments>

The macOS situation is a hard stop rather than a caveat. The README carries a warning that because of MacOS' poor OpenGL support, danser-go won't run on that platform, and asks you to use dual booted Windows or Linux instead. That is a design decision tied to the rendering backend, and it is worth knowing before you download anything, since a user on a Mac cannot test the tool at all.

There is also a deliberate joke in the interface. If you try to run danser-cli without any arguments, the README says a surprise is waiting for you. The tool is a visual experience first, and the command line is the way to drive it rather than the way to use it.

Map selection has four independent ways to be precise

The argument list is long, and most of it exists to make a render reproducible. The map can be selected by artist, title, difficulty, creator, or overridden entirely by hash or identifier.

<executable> -d="Overdrive" -tag=2
<executable> -t="Brain Power" -d="Overdrive" -tag=2
<executable> -t "Brain Power" -d Overdrive -tag 2
<executable> -t="ain pow" -difficulty="rdrive" -tag=2
<executable> -md5=59f3708114c73b2334ad18f31ef49046 -tag=2
<executable> -id=933228 -tag=2

Those six forms are documented as giving the same result, which is a useful thing to know because it shows the matching is tolerant. A partial title and a partial difficulty name are enough when only one map matches, and the exact identifiers are there for when several do.

The hash form is md5, and it overrides all map selection arguments while attempting to find a .osu file matching that hash. The id form is the BeatmapID, and the README is careful to note it is not the BeatmapSetID, which is the kind of detail that costs an evening if you get it wrong.

Other arguments shape the render rather than the selection. -start and -end take seconds to skip to, -skip skips the map intro like in osu!, -quickstart skips the intro and sets LeadInTime and LeadInHold to 0, and -offset applies a local audio offset in milliseconds to recordings. -nodbcheck skips updating the database with new, changed or deleted maps, and -noupdatecheck skips checking GitHub for a newer version of danser, which matters for reproducible render pipelines.

TAG, mirror collage and knockout are different visual modes

The cursor modes are the part of the CLI that is not a modifier, since each one changes what you are actually looking at.

The tag argument sets the number of cursors in TAG mode, and the cursors argument sets the number of cursors used in a mirror collage. The examples in the README all use -tag=2, and the linked example videos show the results of these modes, including mirror collages and knockout videos between top replays.

Knockout mode has its own flag and its own variant. -knockout enables it, and -knockout2 takes a JSON array of replay paths so that the source replays come from an explicit list rather than from danser's own replays folder. With -knockout2 the Knockout.MaxPlayers and Knockout.ExcludeMods settings are ignored, which is a sensible rule since the list is already explicit.

Speed and pitch are separate controls, and both are expressed as multiples of osu! behaviour. A -speed=1.5 is equal to osu!'s DoubleTime mod, and a -pitch=1.5 is equal to osu!'s Nightcore pitch, so to recreate Nightcore you use pitch 1.5 with speed 1.5. The speed value is ignored in -play mode with speed changing mods, which is the sensible priority order.

Mods can be given in two shapes. -mods takes an acronym string such as HDHR, and adding AT to it triggers cursordance with the replay UI. -mods2 takes a JSON structure using lazer's mod format, so it can carry mod settings such as a speed_change value, and it overrides the mods from a -replay argument.

Recording to mp4 goes through an external FFmpeg

The recording path is a flag plus an external dependency, and the dependency is called out explicitly.

The -record flag records danser's output to a video file, and it needs an accessible FFmpeg installation. The -out flag overrides it and records to a given filename instead of auto generating one, with the file extension set in the settings. When the -ss flag is used, the output filename is set as well.

The -ss flag itself creates a screenshot at the given time in .png format, which is the flag you want for thumbnail stills from a render. -preciseprogress prints record progress in 1 percent increments, which sounds minor and is not, because a long render with no progress output is indistinguishable from a hung process.

A separate set of arguments handles the render, not the file. -play plays through the map in osu!standard mode, -mods2 can carry the Difficulty Adjust mod, and the difficulty overrides -cs, -ar, -od and -hp accept values outside osu!'s normal limits, which are ignored when DA is specified in -mods2.

There is also a configuration patching flag. The -sPatch option takes a JSON string that patches the currently loaded config, and the patch is preserved across config file reloads, which the README points out is useful for third party developers who want small tweaks without parsing and rewriting the settings files.

Building it needs Go, a C toolchain and an OpenGL stack

Building from source is a Go project with a native layer, and the prerequisites list is where the difficulty shows.

You need 64-bit Go, at least version 1.24 according to the README, though go.mod itself declares go 1.27.0 with a toolchain of go1.27.2. You need gcc and g++ on Linux and Unix, and on Windows a WinLibs MSVCRT plus POSIX build of it, with the note that TDM-GCC will not work and mingw-w64 is outdated. The OpenGL library ships with the graphics drivers, and on a Linux server build it is libgl1-mesa-dev, plus xorg-dev and libgtk-3 with libgtk-3-dev.

With those in place, the build is one command from the repository root.

go build

That automatically downloads and builds the needed dependencies, and afterwards you run the resulting binary.

The go.mod tells you what the native layer is made of. Rendering goes through cimgui-go and go-sdl3, with go-gl and mathgl for the OpenGL bindings, and BASS audio libraries shipped in the repository as bass.dll, bass_fx.dll and bassmix.dll alongside SDL3.dll. There is SQLite through go-sqlite3 for the map database, gopsutil for system information, rich-go and tablewriter for terminal output, and rplpa for replay parsing.

The build scripts are in the repository too, with dist-linux.sh and dist-win.sh for packaging, and a launcher/ directory for the wrapper executable.

Where danser-go is the wrong tool

The first limitation is the one the project states most clearly about itself. As danser is in development phase, some things may break, and the README asks that an issue be filled with as much detail as possible if that happens. This is software that expects to be reported on rather than depended on quietly.

The second is the platform gap, and it is not a small one. macOS is excluded outright on the grounds of poor OpenGL support, with dual boot offered as the alternative. For anyone working on a Mac, and for any render farm that is Mac based, that removes the tool from consideration entirely, and the workaround has real cost in time and setup.

The third is scope. This is a visualiser for osu!standard. The CLI takes a .osu file and an .osr file, and there is no sign in the argument list of a way to point it at other beatmap modes or at other games, so a creator working across rhythm games will find no equivalent here.

The fourth is the licence, which is genuinely unresolved from the outside. The licence field on the repository says Other, with a custom licence GitHub cannot classify and a LICENSE file to read. For a tool whose main use is producing videos that will be published, that file deserves reading before you ship anything, and this article does not interpret its terms.

Editorial conclusion

Adopt danser-go if you publish osu! related video and want repeatable rendering instead of screen capture, since the CLI can select a map precisely, replay it and write an mp4 through FFmpeg. Do not adopt it if you are on macOS, because the README states plainly that it will not run there and suggests dual booting Windows or Linux instead, and treat the licence as unresolved, since the licence field on the repository says Other and points to a LICENSE file that GitHub cannot classify. Verify first that an FFmpeg installation is reachable if you intend to use -record, and that the osu! map and replay files you need are already on disk, since the flags select from what is present rather than downloading anything.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Wieku/danser-go on GitHub