Discover Overlay and the Linux Discord overlay built on GTK3

An overlay that shows who is talking and what is written

Discover Overlay is a GTK3 overlay written in Python3, and the project describes itself without irony as yet another Discord overlay for Linux. Two display modes are supported. It can be configured to show who is currently talking on Discord, which is the classic voice activity indicator, or it can be set to display text and images from a preconfigured channel, which turns it into a chat feed that floats over your game or your desktop.

The overlay can be positioned anywhere on the screen, and the README states that it is fully customisable. It supports X11 and wlroots based environments, and a compositor is strongly advised, with compatibility for X11 sessions that have no compositor at all.

The reason the project exists is stated plainly: the author felt the need to make it because of the shortcomings in Linux support of the official Discord client. The README also positions it against the other community overlay, discord-overlay, claiming to be considerably lighter on system resources and less hack-and-slash in its approach. That comparison is the author's own, and no measurements are published, so treat it as a design intention rather than a benchmark.

The repository layout matches a desktop application rather than a library. There is a discover_overlay/ package, two desktop entry files, icons in PNG and SVG form for the overlay and the tray, a configuration window, a docs/ directory and a setup.py.

One binary, a dozen flags, and a running process you keep alive

The command line interface is where most of the behaviour lives, and the README documents it flag by flag. Starting the overlay is done by running discover-overlay, and doing so closes out any overlay already running for that user, so there is never more than one. Closing it is discover-overlay --close, with -x as the short form, and the README notes that any control commands sent afterwards do nothing, because the process that handled them is gone.

The show and hide pair is the interesting one. discover-overlay --hide does not stop the process, it only hides what is currently shown, which means later control commands keep working and the --show call is much quicker than starting the overlay from scratch. The counterpart, --show, is documented with a caveat: if the running process has stopped or crashed, it does nothing at all. That is the failure mode to keep in mind, a hidden overlay that never comes back because the process behind it died.

The rest of the flags act on Discord itself. discover-overlay --mute and --unmute toggle your microphone, --deaf and --undeaf toggle your deafen state, and --leave, with -l available, attempts to leave the current voice channel. discover-overlay --moveto=X takes a room ID from Discord in place of X and attempts to join that voice channel.

Two flags deal with guild and channel lists. discover-overlay --refresh-guilds requests the list of guilds and writes them to the channel RPC file at ~/.config/discover-overlay/channels.rpc as a JSON object, while discover-overlay --guild-request=X takes a server ID and writes that guild's text and voice channels to the same file. The file is the bridge between the overlay and the channel listing that the configuration window needs.

For debugging, discover-overlay --debug, or -d, redirects all debug output to the file ~/.config/discover-overlay/output.txt, and the README links a wiki page on debugging for the rest of the story. The version is available through discover-overlay --version, and discover-overlay --configure, or -c, opens the configuration window.

Four installation routes and one explicit warning about them

The README offers a Flatpak install first, pointing at the Flathub page for the app id io.github.trigg.discover_overlay:

flatpak install io.github.trigg.discover_overlay

For a stable release from PyPI, pipx is the route:

python3 -m pipx install discover-overlay

The testing version is installed from a clone of the repository:

git clone https://github.com/trigg/Discover.git
cd Discover
python3 -m pipx install .

The package name is discover-overlay and the console entry point is discover-overlay, while the project and repository are called Discover, so a search for one name does not always find the other.

Beyond the first-party routes, the README lists Arch AUR packages for the stable and latest versions, a Fedora COPR, and a Gentoo overlay, with the install commands for the last two:

sudo yum copr enable mavit/discover-overlay
sudo yum install discover-overlay

sudo eselect repository enable guru
sudo emaint -r guru sync
sudo emerge net-voip/discover-overlay

Those external packages come with an explicit caveat in the README: the version provided is unknown and often untested by the maintainers, and bugs found in them should be reported to their own projects. For a Flatpak, that also means the overlay runs in a sandbox, so anything it needs to draw on top of your session has to work inside that sandbox.

System libraries that pip cannot install for you

Most requirements are handled by pip, but the desktop integration is not one of them. The package metadata lists PyGObject, websocket-client, pyxdg, requests, pillow, python-xlib, setuptools and pulsectl-asyncio as install requirements, and the GTK binding is the piece that needs the distribution's help. The README advises installing python-gobject from the system's own package manager.

On Debian and Ubuntu the commands are `apt install python3-gi python3-gi-cairo libappindicator3-dev`, with Wayland support added by installing gtk-layer-shell and libgtk-layer-shell-dev. The README notes that libappindicator might conflict with other installed packages, but that it is optional, which is worth knowing before running the command on a machine with an existing indicator stack.

The Arch equivalent installs python-gobject and libappindicator-gtk3, with gtk-layer-shell for Wayland support, via `pacman -S python-gobject libappindicator-gtk3`.

Fedora needs a longer list covering pip, gobject, gtk3-devel, cairo and the python headers, installed with `dnf install python3-pip python3-gobject gtk3-devel python3-cairo python-devel python-gobject python-gobject-devel`.

The dependency shape tells you what the overlay is doing under the hood. python-xlib and gtk-layer-shell are the drawing and compositing layers, pulsectl-asyncio handles the PulseAudio stream that carries your microphone state, websocket-client is the transport to Discord, and pillow handles the images you can display from a channel.

Installation also drops desktop shortcuts into share/applications and icons into the hicolor icon directories, which is why the application menu entries appear without any manual step.

Gamescope testing mode and the seams of the project

One flag exists purely for testing: discover-overlay --steamos forces the overlay to start as if it had been launched in a Gamescope and SteamOS session, so it can be exercised against Gamescope while still nested inside a normal desktop. The README then explains how to use it, by taking the DISPLAY variable of the running Gamescope instance and running `env -u WAYLAND_DISPLAY DISPLAY=:X discover-overlay --steamos`.

Unsetting WAYLAND_DISPLAY is what stops the overlay drawing on the outer desktop and makes it connect to Gamescope instead. This is a small command, but it is the clearest statement of the project's real dependency: it wants to sit in the display pipeline, and the way it does that differs between X11, a plain Wayland compositor and a Gamescope session.

The larger seam is Discord itself. The author spells out the terminology the code uses internally, where guild and server mean the same thing and channel, room and chat mean the same thing, which tells you the implementation is built on Discord's internal vocabulary rather than a documented public API. That vocabulary shifts, and the README's own attitude is unusually blunt about it: the author writes that they feel they should not have to make Discord overlays at all, that until an official one exists they might create a new one every few months, and that a Rust and Vulkan version might come. The project also labels itself Beta in its package classifiers and classifies itself for X11 GTK applications on POSIX Linux.

For a user, that means the overlay may stop working when Discord changes, and the fix is a new release rather than a configuration change.

Licence, translations and the gap since the last tag

Discover Overlay is released under the GNU General Public License version 3 or later, and the package classifiers record it as OSI Approved GPLv3+. For a desktop utility that reads from Discord and draws on the screen, that licence matters most if you plan to bundle it into a commercial product or a closed distribution, since GPL obligations attach to derivative works. Reading the LICENSE file and having it reviewed is the appropriate step; this is not legal advice.

The project supports translations, with the README linking separate wiki pages for developers and for translators, and a script in the repository, remake_base_pot.sh, for regenerating the base template. The maintainer asks for patience on translation gaps and says outright that they do not have the resources to get it all right, which is an honest signal about the quality of non-English locales.

On release cadence, the picture is uneven. The tagged versions are v0.7.9 on 2025-09-01, v0.7.8 on 2024-08-16 and v0.7.7 on 2024-08-16, and the version string in setup.py reads 0.7.9, so the packaging metadata still tracks the newest tag. The last push to the repository was on 2026-08-06, which means work continued after that tag without a new numbered release being cut. The repository is not archived.

For a Linux desktop tool, that is a workable arrangement if you install from source or from the Flathub page, and a poor one if your environment needs a pinned, signed release with a changelog. There is no release notes file in the repository to fall back on.

Editorial conclusion

Adopt Discover if you want a voice activity indicator on Linux without a compositor and accept that it talks to Discord through an interface nobody guarantees, since the author says the official client still does not cover the platform. Skip it if your desktop is Wayland without wlroots, if you need a maintained project with a release cadence, or if the GPL-3.0 licence does not fit your distribution plan. Verify first that discover-overlay --configure opens and that your session is X11 or wlroots, and pin the flatpak or pipx version you tested, because the last tagged release was v0.7.9 on 2025-09-01 while the last push was on 2026-08-06.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. trigg/Discover on GitHub