Aurora's own desktop
The shell written in Python and GTK 4: top bar, dock, Spotlight, notifications, Quick Look and more.
Language: Python 3 (PyGObject)
- Alternatives: C, Vala, Rust (gtk-rs), JavaScript (GJS, AGS/Astal), Qt/QML.
- Why: Python makes the desktop small (about 10,000 lines), readable and easy to contribute to. Every part is a plain
.pyfile you can change and restart. The expensive work happens in C libraries (GTK, GLib, wlroots), so Python is not the bottleneck. Rust or C would be faster to run but much slower to write and change. JS shell frameworks (AGS/Astal) are elegant but not packaged in Debian.
Toolkit: GTK 4 + libadwaita
- Alternatives: Qt 6/QML, Iced, Flutter, web technology (Electron/Tauri).
- Why: GTK 4 is GPU-accelerated and accessible, and it supports Wayland first. libadwaita adds modern widgets (adaptive layouts, toasts, dialogs), dark mode and accent colors. Most of the preinstalled apps already use it, so the whole system looks like one product. Web technology would cost hundreds of megabytes of RAM for a panel.
Desktop surfaces: gtk4-layer-shell
- Why: it turns ordinary GTK windows into Wayland layer surfaces (panels, docks, overlays, the background) through the standard
wlr-layer-shellprotocol.
Window list: pywayland + wlr-foreign-toplevel-management
- Why: GTK can't see other apps' windows. The dock and the menu bar open a second Wayland connection with pywayland and use this protocol to list, focus, minimize and close windows. Bindings are generated from the protocol XML at build time.
- Lesson learned (tests caught it): keep the registry and every handle referenced, or Python's garbage collector frees them.
One process, many surfaces
- Choice: wallpaper, menu bar, dock, Spotlight/Launchpad, notifications, OSD, tray and Control Center all live in one
aurora-shellprocess. Commands such asaurora-shell launcheroraurora-shell volume upreach it through GApplication's single-instance D-Bus mechanism, which is how keybindings talk to it. - Why: one Python interpreter instead of eight saves memory and keeps state (window list, settings) in one place.
Notifications: Aurora's own server
- Alternatives: mako, dunst, SwayNotificationCenter.
- Why: our own implementation of the freedesktop spec (actions, markup, urgency, replace, history) integrates with the menu bar, the calendar popover and Do Not Disturb. Its markup sanitizer is unit-tested. SwayNotificationCenter isn't in Debian.
System tray: our own StatusNotifierItem host
- Why: modern tray icons (Discord, Slack, Steam, Nextcloudโฆ) use StatusNotifierItem and dbusmenu over D-Bus. Aurora provides the watcher and draws items and menus natively.
- Lesson learned: PyGObject's
bus_watch_namecan report spurious "vanished" events, so we listen toNameOwnerChangeddirectly.
- Lesson learned: PyGObject's
Search: Spotlight-style providers in Python
- Why: apps, settings pages (by keywords), recent files, a safe calculator (an AST walker, never
eval), commands (> โฆ) and web search. They are simple, fast and all covered by tests. - Conversions (
aurora/convert.py): length, mass, volume, time, speed, data (SI and binary), area, energy and temperature, offline. Currencies use the European Central Bank's daily reference rates: a public XML file with no key or account, fetched only when you type a currency conversion and cached for 12 hours. Commercial APIs need keys and track usage. - Emoji (
:prefix): the names come from Python's own Unicode database, so there is no extra data file to ship or update. - Projects: git repositories up to two levels inside
~/Projects,~/src,~/code,~/git,~/dev,~/workand similar, with the current branch. Enter opens the project in VS Code, VSCodium, Zed or Sublime if installed, otherwise a terminal there. - Clipboard history (
clip:prefix, <kbd>Super</kbd>+<kbd>V</kbd>): see below.
Clipboard history: wl-paste --watch + a tiny store
- Alternatives: cliphist, clipman, CopyQ, GPaste.
- Why: Wayland only shows the clipboard to the focused app, but the
wlr-data-controlprotocol lets a helper watch it. The shell runswl-paste --type text --watch aurora-clipboard store, andaurora/clipboard.pykeeps the last 100 text entries (up to 64 KB each) in~/.local/share/aurora/clipboard.json, readable only by you. Password managers mark their copies as sensitive and wl-paste passes that on, so passwords are never stored. cliphist would work too, but it adds a Go binary for what is about 60 lines of Python, and it doesn't skip sensitive entries. CopyQ and GPaste bring their own UIs; ours are Spotlight, for the quick look, and the Clipboard window (aurora/clipboardapp.py,aurora-clipboard show, <kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd>) for the whole history: search, ages, line counts, monospace for code, pins, delete, and the pictureswl-paste --type image/pngstored alongside the text. Copying from it runswl-copy, which keeps serving the selection after the window closes โ a Wayland client owns its selection only while it lives, and this window exists to be closed. Settings โ Privacy has the same history: the switch, Clear, and a button that opens this window rather than a second small list of its own.
Quick Look: GTK widgets per file type
- Alternatives: GNOME Sushi (needs Nautilus and GJS), opening the default app.
- Why: a small GTK 4 window (
aurora/quicklook.py) with the right widget for each type:Gtk.Picturefor images;Gtk.Video(GStreamer,libgtk-4-media-gstreamer) for video and audio;- Poppler for the first pages of a PDF;
- GtkSourceView 5 for text and code, with syntax highlighting in the light or dark scheme;
- a folder summary, and for anything else a card with its thumbnail and details.
- Files opens it with <kbd>Space</kbd>; arrow keys move the selection in Files and the preview follows.
aurora-quicklook FILEโฆworks from anywhere.
Sun position without a location service (aurora/sun.py)
- Alternatives: GeoClue (Wi-Fi-based location through an online service), asking the user for a city, fixed hours.
- Why: the dynamic wallpaper, automatic dark style and Night Light only need sunrise and sunset. The time zone you picked in the installer already says roughly where you are: tzdata's
zone1970.tabgives coordinates for every zone. The NOAA solar formulas then give the sun's elevation within a few minutes. Nothing leaves the computer and nothing asks for permission. Unit tests compare against known sunrise and sunset times.
Dynamic wallpaper and automatic dark style (shell/daycycle.py)
- Alternatives: GNOME's XML slideshows (fixed clock times), HEIC dynamic wallpapers (macOS).
- Why: three series of four pictures of the same landscape (dawn, day, dusk, night) live in
branding/wallpapers/SERIES/; Settings โ Appearance picks the series. Once a minute the shell checks the sun's elevation: night below โ6ยฐ, dawn and dusk up to 8ยฐ, day above. On a change, the new picture fades in over 2.5 seconds. Following the sun rather than the clock means winter evenings get dark when it's actually dark. The shell keeps~/.cache/aurora/wallpaperpointing at the current picture for the lock screen, and the login screen computes the same phase. "Auto" dark style flips the system color scheme at sunset and sunrise. Choosing Dark Style by hand in the Control Center turns Auto off.
The pictures that come with it
- What: three series of four (Starfall, Veil, Horizon โ dawn, day, dusk and night, the ones the dynamic background moves between), and six single pictures: Northern Lights, Wave, Nebula, Milky Way, Sunrise and Ringed Planet. All of them are in
branding/wallpapers/; the series go toaurora-SERIES-PHASE.pngand the single ones toaurora-NAME.png, and Settings gives each a readable name rather than its file name.
Animated video wallpapers
- What: Settings โ Appearance โ Background โ Animated wallpaper offers the bundled Full HD and 4K clips: auroras, nature, planets, space and abstract loops. Selecting a thumbnail starts the video on the desktop and in the preview. Static image shows the included still images directly, in the same inline searchable picker; choosing one leaves it still. Visible type buttons and a short explanation distinguish the modes. Daylight series changes pictures at dawn, day, dusk and night. Load a Fileโฆ imports a personal image, MP4, WebM, M4V or MOV; Play animation switches playback off to show its static poster.
- How:
shell/livingwallpaper.pyuses GTK's GStreamer media backend for silent, continuous playback. Bundled videos use H.264 at 30 fps, retaining 3840ร2160 when the available 4K export fits the 48 MiB per-file limit; larger videos are exported at 1920ร1080, preserving their playback duration. The importer enforces this limit andtests/static.shchecks all bundled videos, keeping them below GitHub's recommended 50 MB and hard 100 MB limits. Thumbnails use PNG posters, so the grid opens only the selected video's decoder. The lock screen and wallpaper-derived accent use the poster too. - Power: playback pauses while a maximized or fullscreen window covers the desktop, or the active power profile is power-saver. Minimized windows allow it to resume. Unmapping a preview or monitor surface closes its decoder and signal subscriptions.
- Sources: the downloaded works and their posters retain their source licenses.
branding/wallpapers/animated/CREDITS.txtlists authors, source pages, licenses and adaptations, and ships with the artwork package. The importer intools/import-wallpaper-videos.pyconverts source clips without their audio; clips are slowed with frame blending; excerpts use a short dissolve across the loop boundary. The source catalog keeps the downloaded candidates available for selecting the final collection. - Validation:
make test-wallpapersselects all bundled Settings buttons, checks decoding and pause/resume, verifies the lock-screen poster, measures actual changing desktop pixels, and checks that Still stops movement.
Icons: one generator, five styles
- Alternatives: shipping a drawn icon set, or using Papirus as-is.
- Why: every icon Aurora draws โ apps, folders, file types, devices โ is written by
branding/icons/generate.pyon a 128 px grid, so the set stays consistent by construction instead of by discipline. The app icons are one plate plus one glyph, which means the plate can be swapped: Settings โ Appearance โ Icon style picks between Galaxy (the default: a deep sky with a lit core and stars), Aurora ribbon, Glass, Clay and Lightning, and every app icon in the system changes at once. Each style is a whole icon theme with a dark twin; the four beside the default hold only their app icons and inherit Aurora for folders, file types and devices, so a style costs about 230 KB. The stars of a galaxy icon and the filaments of a lightning one are computed from the icon's place in the set, never from a random number, so a given icon is the same picture on every machine and in every build. Aurora's own four marks used to be hand-drawn SVGs on a different plate from everything else; they are generated like the rest now, and also written intohicolorfor anything not using an Aurora theme.
Overview and hot corners
- Alternatives: labwc's built-in window switcher only, a GNOME-style overview with live thumbnails.
- Why: the overview (
shell/overview.py) is a full-screen layer with a card per window from the foreign-toplevel list, over a blurred screenshot of the desktop (grim at half scale, shrunk and scaled back up: a cheap blur with no GPU code). A card shows the window itself: no protocol here hands one client another client's window (wlr-screencopy copies a whole output and per-window capture arrived in wlroots after the version Debian 13 carries), soshell/previews.pykeeps a picture of each window, cropped out of the screen with grim while that window was in front โ which is when its pixels really are on screen โ and shows it later, as the big desktops do. Wayfire says where the focused window is (window-rules/get-focused-view); the compatibility session has no such interface, so there the cards keep their app icons, as they always did. The same pictures appear in the dock's window lists and in Snap Assist, and Settings โ Desktop & Dock โ Windows โ Window previews turns them off. Hot corners (shell/hotcorners.py) are 2ร2-pixel transparent layer surfaces in the corners. The pointer must rest there for 120 ms, which avoids triggers on fast passes, and there is a short cooldown afterwards. - Quarters and thirds are labwc snap regions defined in
rc.xml, so they work with keyboard shortcuts and by holding a modifier while dragging.
Weather in the calendar: Open-Meteo
- Alternatives: libgweather/GNOME Weather's providers (MET Norway), OpenWeatherMap (needs an API key).
- Why: Open-Meteo is free, open data and needs no key or account. The shell asks for the weather at your time zone's main city (never an exact position), at most every 30 minutes, only when you open the calendar. Fahrenheit is used where it is the local convention. Settings โ Privacy turns it off.
Desktop widgets (shell/widgets.py, shell/devwidgets.py)
- Alternatives: separate layer-shell windows per widget, a web view (as KDE's or macOS's widgets are closer to), conky.
- Why: each widget is a GTK widget on the wallpaper surface, under the windows, so twenty-three of them cost one surface. Positions are saved as fractions of the screen and sizes follow its height, so a resolution change keeps the layout. Dragging is handled by the desktop surface, not by the widget: a gesture on a moving widget shifts its own coordinates at every step and makes it jump. A widget is a small slot that measures itself (a
Gtk.Boxcan't: its layout manager ignoresmeasure), holding the visible card. Anything that runs a program (git, podman, nvidia-smi, ss) runs in a thread. In Wayfire, floating windows are scaled into the new work area after a resolution change through its IPC (shell/refit.py); labwc moves them back on screen itself.
Session sounds: synthesized, not sampled
- Alternatives: freedesktop's sound theme, recorded samples, no sounds (Fedora, Debian).
- Why: the startup and shutdown sounds are generated by
branding/sounds/generate.pywith numpy, like the rest of the artwork. They aim for the warm, organic feel of Ubuntu's sounds without copying them. A synthesized marimba (modal synthesis of a wooden bar: tuned partials at 1 : 3.93 : 9.2 that fade at different rates, plus the soft click of the mallet) plays a short motif in D major over a round bass note.- Startup rises and resolves on a chord held by a soft felt pad.
- Shutdown walks back down and fades.
- A short room reverb adds space. There are no samples and no licensing questions, and the sounds can be changed by editing code. They play with
pw-play(PipeWire). The shell waits 1.8 s for the shutdown sound before powering off, restarting or logging out. Both are on by default and switch off together in Settings โ Sound.