Repository files navigation

Transparent click-through web browser overlay ("HUD") over yourwhole desktop, usingWebKit.

If you know web development, you can use Hudkit to make thecoolest statusbarin existence, orSVG desktop fireworks, or whatever else you can think ofusing a fullscreen transparent web view for.

• Works with multiple monitors, and connecting/disconnecting them.
• Has aJavaScript API, so scripts on the page can querymonitor layout and change which areas of the overlay are clickable, forexample.
• Small executable. Uses native GTK and WebKit libraries.
• Supports modern web APIs like WebSockets, WebAudio, WebGL, etc.

Platforms:  ✔️ Linux (X11) ✔️❔Linux (Wayland)  🚫Windows  🚫OS X

cd /tmpgit clone https://github.com/anko/hudkit.gitcd hudkitmake./example/run.sh

Ifmake complains, checkdependencies.

You should see something like this, if you have 2 monitors:

The code for what you see there is in theexample/ directory. Itcontains some explanatory comments, so it might make a good starting point foryour experiments. If you come up with a (fairly compact) example of your own,please PR.

To open Web Inspector targeting the example page,./example/run.sh --inspect.

USAGE: ./hudkit <URL> [--help] [--webkit-settings option1=value1,...]    <URL>        Universal Resource Locator to be loaded on the overlay web view.        For example, to load a local file, you'd pass something like:            file:///home/mary/test.html        or to load from a local web server at port 4000:            http://localhost:4000    --inspect        Open the Web Inspector (dev tools) on start.    --webkit-settings <settings>        The <settings> should be a comma-separated list of settings.        Boolean settings can look like            option-name            option-name=TRUE            option-name=FALSE        String, integer, and enum options look like            option-name=foo            option-name=42        To see settings available on your system's WebKit version, their        valid values, and default values, pass '--webkit-settings help'.        To see explanations of the settings, see        https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html    --help        Print this help text, then exit.    All of the standard GTK debug options and env variables are also    supported.  You probably won't need them, but you can find a list here:    https://developer.gnome.org/gtk3/stable/gtk-running.html

JavaScript on the web page context has aHudkit object, with these properties:

Return: an Array of{name, x, y, width, height} objects, representing yourmonitors' device names and dimensions.

Example:

constmonitors=awaitHudkit.getMonitorLayout()monitors.forEach((m)=>{console.log(`${m.name} pos:${m.x},${m.y} size:${m.width},${m.height}`)})

Registers the givenlistener function to be called on events by the stringnameeventName.

Currently listenable events:

• monitors-changed: fired when a monitor is logically connected ordisconnected, such as throughxrandr.

  No arguments are passed to thelistener. CallHudkit.getMonitorLayoutto get the updated layout.

• composited-changed: fired when the ability of your desktop environment torender transparency changes; typically when your compositor is killed orrestarted.

  The main reason this exists is so if you accidentally kill your compositor,you won't be stuck with the now fully opaque overlay window blocking yourwhole desktop, as long as your page listens for this event and callswindow.close() in response.

  Arguments passed to listener:

  • haveTransparency (Boolean). True if compositing is now supported, falseotherwise.

De-registers the givenlistener from the giveneventName, so it will nolonger be called.

Sets which areas of the overlay window are clickable. By default, it is notclickable. The given area replaces the previous.

Parameters:

• rectangles: Array of objects with propertiesx,y,width, andheight. Other properties are ignored, and missing properties are treatedas 0. Can be an empty Array, to make everything non-clickable.

  The area of the desktop represented by the union of the given rectanglesbecome input-opaque (able to receive mouse events). All other areas becomeinput-transparent.

Return:undefined

Example:

// Make a tall narrow strip of the overlay window clickable, in the top left// corner of the screen. The dimensions are in pixels.Hudkit.setClickableAreas([{x:0,y:0,width:200,height:1000}],err=>console.error(err))

Notes:

• If the Web Inspector is attached to the overlay window, the area it occupiesis automatically kept clickable, independently of calls to this function.

• When monitors are connected or disconnected, your clickable areas are resetto nothing being clickable, because their positioning would beunpredictable. Subscribe to the'monitors-changed' event(Hudkit.on('monitors-changed', () => { ... })) and update your clickableareas accordingly!

Opens the Web Inspector (also known as Developer Tools), for debugging the pageloaded in the web view.

Parameters:

• attached: Boolean. Iftrue, starts the inspector attached to theoverlay window. Iffalse, start the inspector in its own window.(Optional. Default:false.)

Return:undefined

ℹ️ You can also start the inspector with the--inspectflag. That's usually better, because it works even if your JS crashes beforecalling this function.

• window.closeexits Hudkit.

In the root directory of this project,

make

If you're missing any dependencies, the error should tell you which.

You'll need—

• StandardC compilation tools:make,pkg-config, and any C compiler ofyour choice (gcc orclang, probably).

  Any Linux distro has these; many have them installed by default. If not,consult your distro's documentation on how to install them. (Many distroshave a single package containing all the C tools, for convenience, likeArch'sbase-develpackage.)

• GTK 3, and a correspondingwebkit2gtk.

  OnArch, the packages are calledgtk3 andwebkit2gtk.

  OnVoid, they aregtk+3-devel andwebkit2gtk-devel.

  OnUbuntu, they arelibgtk-3-dev andlibwebkit2gtk-4.0-devel.

  OnMint, they arelibgtk-3-dev andlibwebkit2gtk-4.0.

  If you build on another distro, I'm interested in how it went.

Probably.Report them.

Is it safe to direct Hudkit at some random untrusted web page on theinternet?

No. Hudkit is built on a web browser engine, but is not intended for use as ageneral-purpose web browser. Thewindow.Hudkit object and other backgroundstuff are exposed to every page Hudkit loads. Although I've tried my best tomitigate possible attacks, the API simply is not designed to be exposed to thefull badness of the wider internet.

Please point Hudkit only at a locally hosted web pages, unless you really knowwhat you're doing.

How can I ensure my HUD doesn't accidentally load remote resources?

Define aContent-Security-Policy(CSP), like you'd do when developing any other web page. Hudkit supports thosethrough WebKit.

I recommend the following: Add this meta tag inside your document's<head>:

<metahttp-equiv="Content-Security-Policy"content="default-src 'self' 'unsafe-inline'">

This makes that page only able to load resources from the same host it wasloaded from (your local computer). All requests to anywhere else are blocked.The'unsafe-inline' part allows inline<script> and<style> tags, whichare innocuous if you're never loading remote resources anyway.

You can test this by e.g. adding a<img src="http://example.com/"> tag toyour page. You'll see a log entry like this when it gets blocked:

CONSOLE SECURITY ERROR Refused to load http://example.com/ because it appearsin neither the img-src directive nor the default-src directive of the ContentSecurity Policy.

For further documentation on CSP, consultMDN WebDocsorcontent-security-policy.com.

Hudkit says my screen doesn't support transparency. What does this mean?

You're probably running a plain window manager (like i3, XMonad, or awesomewm),which doesn't have abuilt-incompositor. Soyou'll need to install and run a standalone compositor. I recommendcompton, orpicom.

I can't type anything into the Web Inspector while it's attached to theoverlay window!

Yep, it's a known problem. You can work around it by detaching the webinspector into its own window, with one of the buttons in the top-left corner.It works normally when detached.

This bug is hard to fix for complex technical reasons: In short, we have toset X11'soverride-redirect flag on the overlay window, to guarantee thatwindow managers cannot reposition it, reparent it, or otherwise mess with it.A side-effect of doing this is that the window does cannot receive input focus,which is fine for mouse events (since they aren't dependent on input focus),but it means no keyboard events. Unless you grab the keyboard device, whichhas its own problems.

My currently running Hudkit instance's page is in a weird state that I wantto debug, but I forgot to pass the--inspect flag, and restarting it wouldlose its current state. What do?

You can send the Hudkit process aSIGUSR1 signal to open the Web Inspector.For example,killall hudkit --signal SIGUSR1.

Why am I getting aSyntaxError when I try toawait a Hudkit function?

Probably because you're trying to useawait at the top-level of yourJavaScript file. This wart in the JavaScript standard is unfortunate, and thewording of WebKit's error message for it even more so.

The fix is to create an async function at the top-level, and immediately callit, doing all of your async stuff inside it:

(asyncfunction(){// You can use `await` here})()

This will improve in the near future: There is aTC39 proposal for top-levelawait, which isbacked byWebKit developers, andimplementation is inprogress.

Why is Xvfb complaining aboutextension "GLX" missing on display ":99" if Irun the automated test?

Probably because you're running an Nvidia proprietary driver which arekind ofgarbage. The test starts abackground instance of X11 so your desktop's settings don't interfere with it,but inside that context OpenGL is randomly bricked on some versions of theproprietary NV driver, and on some versions it works. The actual programshould work just fine either way though. Try theexample/.

• Electron. I've heard it's possible to make Electronclick-through and fullscreen. I have not gotten it to work, but maybe youcan? Let me know if you do.

  Possible starting point: Startelectron with--enable-transparent-visuals --disable-gpu. Callwin.setIgnoreMouseEvents, setall the possible "please dear WM, do not touch this window"-flags, call thescreen API for monitorarrangements and position your window accordingly. Sacrifice 55 paperclipsto Eris of Discordia, kneel and pray.

• dnode makes it possible to make remote procedure calls from JS inthe web page to JS on a web server.
• SockJS lets is a simple abstraction over WebSockets, fortransferring data otherwise.
• D3 is a great data visualisation library.

• xkbcat can capture keystrokes everywhere in X11, for making akeyboard visualiser for livestreaming, or for triggering eye candy.
• sxhkd is a fairly minimal X11 keyboard shortcut daemon. Can use it to runarbitrary commands in response to key combinations, such as throwing datainto a named pipe read by a locally running web server that's in contactwith hudkit by WebSocket.
• mpv with the--input-ipc-server flag can be queried for the currentlyplaying music track. Various other music players can do this too if yougoogle around.
• sensors can show hardware temperatures and fan data.

ISC.