Dial

An NVDA add-on that turns a volume dial into a launcher.

Turn the dial to move through your own categories of websites, folders, applications, internet radio stations, workspaces and text snippets, press to launch what you landed on.

No dial? Dial mode puts the whole add-on on the arrow keys.

Dial's page at slightperception.com has a four part audio guide and the download.

Dial is free software under the GNU General Public License, version 2. See LICENSE.

What it does

• Categories and items. Your own lists, in your own order. Websites, folders, files, applications, text snippets, world clocks, NVDA's own commands, internet radio stations, and workspaces that open several things at once.
• NVDA commands on the dial. Any command NVDA has can go on an item, so the ones you never got round to binding are a turn away.
• Internet radio. A curated catalogue of over 250 stations from 11 countries, a sleep timer, a separate output device so a station can play on your speakers while NVDA keeps talking in your headphones, and speech that ducks the music instead of fighting it.
• Clipboard history. The last things you copied, reachable on Control and the dial without leaving what you are typing, with copies from password managers ignored. Held in memory and forgotten when NVDA closes, or kept between sessions if you ask for it, in a file only your Windows account can read.
• World clocks that read out the time as you turn onto them.
• Most used. A generated category that keeps what you reach for most at the front.
• Import and export, so a set-up can be moved between machines.
• A built-in help guide, reachable from the dial itself.

Requirements

• NVDA 2021.1 or later.
• Windows, whatever version your NVDA runs on. Internet radio needs no particular version, bringing its own player rather than using the system's. The one thing that varies: the station list offers your own country first on Windows 10 1709 and later, and falls back to the region in your locale below that.
• A volume dial or media keys. Anything that sends volume up, volume down, and either mute or play/pause will do. A keyboard with none of those still works through Dial mode.

Installing

Download the .nvda-addon file from the latest release and open it. NVDA offers to install it, then restarts.

Your categories live in NVDA's own configuration, not in the add-on folder, so reinstalling or updating never touches them.

Using it

Each modifier owns one level, so once you know which key you are holding you know what the dial is moving through.

• Next or previous category: NVDA + turn the dial
• Announce the current category: NVDA + press the dial
• Turn the radio off, from anywhere: NVDA + press twice quickly
• Next or previous item: Shift + turn the dial
• Launch the item: Shift + press the dial
• The item's second action, where it has one: Shift + press twice quickly
• Move through clipboard history: Control + turn the dial
• Copy that entry back to the clipboard: Control + press the dial
• Paste it where the cursor is: Control + press twice quickly
• Dial mode on or off: NVDA + Applications

The press works whichever key your dial sends. Mute and play/pause are both bound, under every modifier, so there is nothing to detect and nothing to tell Dial about your hardware. A press with no modifier is left alone, so the key still mutes or pauses as it always did.

A second press means something different per item type. A website copies its address, a folder reads out what is in it, a file gives its size and when it changed, a snippet pastes, a station arms or cancels the sleep timer, a workspace reads out its members, a clock copies its reading. An application, a help page and an NVDA command have no second action, and nothing opens or runs on two presses anywhere in the add-on.

Dial mode is the same levels from the keyboard: up and down choose the row, left and right turn, Enter acts, Space is the second action, Escape leaves. The rows are Categories, Items, and Clipboard history when that is switched on. Any other key leaves too and then does its own job, so it cannot trap you, and nothing waits for a second press because Enter and Space each mean one thing.

Two more commands ship unassigned, so they take no key from you unless you want them to: turning the radio off, and adding 15 minutes to the sleep timer. Both are under the Dial heading in NVDA's Input Gestures.

Under Dial's settings you can choose the dial and the keyboard together (the default), the dial only, or the keyboard only, which leaves your volume and media keys completely alone.

Categories and items are edited in NVDA's settings, under Dial. The full guide is the add-on's own Help category, eleven pages reachable from the dial itself, and the same pages are in Project\globalPlugins\dial\help\. Project/doc/en/readme.md is the changelog.

Building from source

Project\ IS the package contents. To build:

.\ProjectBuilds\build.ps1

That writes ProjectBuilds\dial-V<version>.nvda-addon, taking the version from Project\manifest.ini so the filename cannot drift from the manifest. Bump the version in the manifest first: the script deletes its own output before writing, so building twice at one version replaces the package silently.

The offline test harnesses in DevTools\ need no NVDA and take about two minutes between them. Run them after any refactor.

Repository layout

• Project\ - the add-on source. This IS the package contents: manifest.ini and doc\ at its root, the code under globalPlugins\dial\, and the bundled libVLC payload under vlc\.
• ProjectBuilds\ - build.ps1 to make a package, install.ps1 to unpack one over the installed copy for testing.
• DevTools\ - test harnesses that run without NVDA, an in-process self test that runs inside it, and the tools that build and verify the station catalogue.

More

Dial's page at slightperception.com/nvda/dial has a four part audio guide walking through it, and is where the other projects live too.

Credits

Internet radio plays through libVLC, part of VLC media player, by the VideoLAN project. Only the audio parts are included, unmodified, from the official VLC 3.0.21 Windows builds. VLC is licensed under the GNU General Public License version 2 or later, and its own licence text ships alongside it in the add-on's vlc folder.