Welcome to oshu!
This project was born out of frustration from not being able to play osu! on a little Linux box with no graphics card whatsoever. It's aimed at minimalistic people and probably will never contain a hundredth of the official client's features.
osu! is that PC clone of the osu! Tatakae! Ouendan DS rhythm game, occidentalized as Elite Beat Agents. osu! has got tons of cool beatmaps, and a more or less intuitive text file format described at https://osu.ppy.sh/help/wiki/osu!_File_Formats
The main problem with osu! is that it required Windows and a graphics card. Even with that, it sometimes get slow unless the computer is a beast… Hell, the mania and taiko mode could be played in a terminal!
oshu! is currently mostly targeted at Linux users, but it doesn't have to be that way. All it needs are volunteers to build and test the project on the various operating systems and desktop environments out there.
By the way, the name comes from osu! but with the s pronounced sh, because it's a mini-osu.
The beatmaps are distributed as .osz files, which are disguised ZIP files. You need to extract using unzip or a similar tool. Rename them to .zip if your file archiver can't process it. Once extracted, you'll see one or more .osu files with various difficulty levels.
oshu! is meant to be started from the command-line, so go spawn your terminal
A window will open and you'll see circles appear on the screen. You got to click the crosses when the orange circle reaches the white one. Hold the button pressed for long notes. Most players point with the mouse and press the Z/X keyboard keys instead of clicking.
For more detailed explainations, see: https://www.youtube.com/results?search_query=osu+tutorial
You can use the experimental beatmap collection browser by extracting your
beatmaps to the
~/.oshu/beatmaps/ directory, the running
oshu-library build-index. Point your browser to the path it tells you and
start playing. Note that for your browser to open the beatmaps with oshu!, you
need to make sure the desktop integration is properly set up. See the section
Note: oshu! is still in an early stage of development. Don't expect it to
be amazing. It doesn't even have a menu to select songs, you need to call it
from the command line like
$ oshu my_beatmap.osu.
First of all, make sure you have the required dependencies. These things are so common that I may assure you they're in your distribution's official repositories.
- CMake 3.9,
- a C++14 compiler,
- SDL2 ≥ 2.0.5,
- SDL2_image 2.0.1,
- ffmpeg 3.3.6,
- cairo 1.14.8,
- pango 1.40.14.
Note that the versions specified above are indicative. It is very likely your build will work with older or newer versions. If you need support for a specific version, feel free to ask.
To build oshu!, follow the standard CMake procedure:
mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=~/.local -DOSHU_DEFAULT_SKIN=osu .. make && make install
If you do use the
$HOME/.local prefix, make sure you add
your PATH, or invoke oshu! by specifying the full path like
-DOSHU_DEFAULT_SKIN=osu causes CMake to download the default osu! skin
and make it the default. If you're satisfied with the minimal skin, or if you
can't connect to Internet, you may leave out this option, or write out
If you want to install skins without making them the default, you can list them
The files required for desktop integration are deployed with
but you may need to refresh the cache databases yourself. Note that package
managers are usually good at refreshing them automatically.
You may force the refreshing with:
update-desktop-database $PREFIX/share/applications update-mime-database $PREFIX/share/mime
Let's clarify the goals before we stray too far away from them.
These things are the raison d'être of oshu:
- All the Osu beatmaps should be playable.
- The game should run on the lowest-end millenial computer one can find.
This means if you find an unsupported beatmap or a computer too slow to run oshu, feel free to submit a bug report.
The first versions are going to focus on the regular game mode, and hopefully oshu will support more game modes someday.
Since it's a hobby project, the feature set will be probably be quite limited for a while. For example:
- No health bar.
- No spinner. (I hate those.)
- No network play.
- No video background.
- No fancy visual effects.
But it just means I probably won't have the time to work on these. These limitations are not a design choice. Contributions are welcome!
The user manual's man page is installed in the standard man directory, but you
may view it directly from
For the technical documentation, please look at CONTRIBUTING.md.