How to use MuseScore 3 in headless mode in Ubuntu 20.04

There a lot of applications that aren't mean to be used on a desktop environment as they are basically command line applications. There are as well some applications that are developed to be used with a graphic user interface, however, they offer as well a very useful command-line interface that can be used to embed in our own applications. That's the case of MuseScore, although not everyone that uses this tool knows about this feature and it's not like they would need it, as a developer, you will love this tool.

In a previous tutorial, I described how to install MuseScore in Ubuntu 20.04 and it does work in both environments Desktop and Server. However, in the server environment, if you try to use the MuseScore binary (mscore3) from the command line in the server, you will find the following exception:

qt.qpa.xcb: could not connect to display localhost:10.0
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

Aborted (core dumped)

As you may suspect, the error is caused because you are launching the application as a graphical application, so of course, it would be necessary to have a display. But, as we are on the server, we obviously don't have such a tool at disposition. You shouldn't work like this in the server, instead you should work only with the command line options available (headless mode). In this article, i will explain you easily how to do it in your Ubuntu 18.04 or 20.04 server.

1. Configure the QT Platform to run offscreen

The solution for this problem is to simply specify before using the binary, specify the offscreen value for the QT_QPA_PLATFORM environment variable. With this parameter, you are specifying the framebuffer device that should be used to launch the application, in this case, none. Simply run the following instruction in the terminal before launching mscore3:

export QT_QPA_PLATFORM=offscreen

2. Testing headless MuseScore 3

Then, you should be able to use the headless features of MuseScore, for example to print the version that you are currently using, the following command should do the trick:

mscore3 -v

This would output something like:

QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-root'
MuseScore3 3.2.3

Alternatively, you can convert a Guitar Pro File to a midi file using MuseScore:

mscore3 input_guitarprotab.gp4 -o output_midi.mid

The transcoding would generate the following output:

QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-root'
convert <./input_guitarprotab.gp4>...
measures 145 bars.size 145
        to <output_midi.mid>
Had to fall back to defaults to render measure
... success!

And that's it, with the previous command there should be a new midi file generated from the Guitar Pro Tab file. For more information about the command-line options that MuseScore has, please visit their official documentation about the CLI here.

Happy coding ❤️!