QuickImageViewer (qIV)

When qIV is hidden or running in the background, its icon lives in the system tray. Right-click it for the full settings menu — no config files to edit. Double-click to restore the window.

Settings submenu — toggles

Settings submenu — numeric values

Click any numeric label to open an input dialog. Current value is shown in the menu item itself.

Settings file operations

Export and Import moved to the top-level Backup & Export menu, with the log and TCP/IP archives.

Settings › History

Everything about the folder history in one place — what gets recorded, how much of it is shown, and how to tidy it up.

Every action asks first and backs up the file it is about to change, so any of them can be undone with Backup & Export › Restore History & Favorites. Remove Invalid Folders and Remove Duplicates never touch favorites; the three Clear items are the only ones that do, and each names what survives it.

Backup & Export

Every operation that moves qIV's data on and off the disk, in one top-level menu.

The TCP/IP archive holds your allow-list and the stored password hash (PBKDF2, not plaintext) — keep it as private as the configuration itself. The logs archive is the one meant to be handed to somebody else.

Other submenus

Both logs are off by default and survive a restart once switched on — which is the point of them. A screen that misbehaves at four in the morning is exactly the one nobody was watching, so the setting is persisted rather than something you must remember to enable first.

Files land in logs\general\ and logs\network\ beside the EXE, named QuickImageViewer_General_<timestamp>.log and QuickImageViewer_Tcp_IP_<timestamp>.log, rotating every 5000 lines. Switching a log off and on again continues the newest file rather than starting a fresh one.

The format is the standard time [thread] LEVEL message layout, so LogViewPlus, lnav and similar tools parse it with no configuration — and a rotated TCP/IP file opens straight back in the Server Log panel with Ctrl+O. Writing happens on a thread of its own: a slow disk cannot stall the viewer, and with a log switched off the cost at each record point is a single atomic read.

Press F8 for the Dedicated panel. A dedicated screen is a separate copy of qIV with its own settings file beside it — normally parked fullscreen on one monitor running a slideshow. Any number can run at once, alongside the main app, sharing nothing.

How a copy is identified

Everything derives from the executable's own path, so two screens can never resolve to the same settings, mutex or window class — two files cannot share a name in one folder.

D:\Screens\qIV_dedicated_Lobby.exe                  the copy
D:\Screens\qIV_dedicated_Lobby.ini                  its settings
D:\Screens\imageLists_qIV_dedicated_Lobby.qim       image folders
D:\Screens\promotionList_qIV_dedicated_Lobby.qpr    promotion folders

Startup decision

Made from the filesystem before any setting is read:

Inside the .ini, [Instance]Dedicated decides behaviour — 1/true/on/yes or any non-zero number. Set it to 0 and you get a portable ordinary viewer: settings in a file, history and favorites intact, nothing in the registry.

Panel buttons

The panel edits the config only — it never changes the app you are using, and every value starts from the compiled defaults rather than your current settings, so a screen never inherits the authoring machine's preferences.

Test Images / Test Promos count the images actually found per folder and flag folders that are missing or empty. A folder that exists but holds nothing decodable looks identical to a working one until the screen goes blank.

Kiosk lock

Tick Kiosk lock in the panel and the screen ignores every key and every click — nobody walking past can pause the slideshow or open a panel. The tray icon keeps working (its menu runs its own message loop, so the locked window never sees those messages), and Settings › Kiosk Lock there is the only way back in. The main app has the same toggle in its tray menu, and -lock forces it on for a single launch without changing the stored setting.

Always on top

Keeps the screen above every other window so nothing that pops up can cover it. Ctrl+T toggles it live and the setting persists; the panel sets it for a generated screen.

Keep display awake

Blocks the screensaver and display sleep while the window is on screen. Leave it off and Windows eventually blanks the display with nobody there to wake it — and with the kiosk lock on, nobody could. The hold is released automatically when the window hides to the tray, so a viewer sitting in the tray never keeps a machine up.

Isolation

A dedicated screen writes nothing to the registry, keeps no history or favorites, and has its own mutex and window class — so a file opened from Explorer can never land on a slideshow instead of the main window. It auto-starts from a shortcut rather than the Run key.

Promotions

A dedicated screen can interleave a second playlist with its images — never merged into them, and invisible to the image counter and arrow keys.

Both triggers are (from, to) pairs and run independently — set either, or both, and whichever comes due first shows a promotion:

• (0, 0) — off
• (5, 0) — exactly every 5
• (5, 15) — re-rolled between 5 and 15 each time, so it never looks mechanical

One qIV can drive others — a wall of screens from the copy on your desk, or a single display in another room. It is a plain UTF-8 line protocol over TCP, so a script, netcat, a home-automation system or a phone app are all first-class clients.

The phone app has its own section — qIV Remote for Android, which speaks exactly the protocol described here.

F11 and F12 are session-only and always start off — a viewer that came back from a restart already driving machines you had forgotten about would be the worst kind of surprise.

Putting one picture on another screen

Four keys, one question at four depths.

Ctrl+Shift+Enter is Ctrl+Enter widened: it ignores the Control ticks in Ctrl+F11 and pushes to everything connected, for lining a whole wall up at once without first ticking rows you are about to untick again.

Ctrl+Enter asks before it sends. It queries the target: already in the same folder in the same order? Then just the image number — one round trip, no rescan, no flicker, so you can walk a folder and push each picture as you reach it. In a different folder? Then the folder, then the sort order, then — after waiting for that instance's own scan to finish — the number. Sending a position before the scan lands is the race this avoids.

Alt+Enter and Ctrl+Alt+Enter carry the picture's own file bytes, base64 across several protocol lines, and the far end decodes them with its own decoder. That is why they work to a machine that cannot read your disk. The received image is shown once and changes nothing else: no folder, no sort order, no playlist position. A target running a fullscreen slideshow keeps running it and simply continues from the pushed image — the picture never enters its playlist, and both the received file and its cache entry are thrown away afterwards. An advert dropped between two slides is the case it was built for.

The Send Command panel

Every command has one wire name, spelled exactly like its internal enumerator, and the panel's list is built from the same table the parser accepts — so a name shown there cannot come back “unknown command”.

• Browse, don't remember — the list is permanent and filterable; names are shown in two blues, the second marking a command that takes a value
• Descriptions where they belong — what the highlighted command does sits over the list, what its value means sits over the Value box, with units, limits and an example
• Send to — its own box of connected instances with a checkbox each, so an arbitrary command reaches an arbitrary subset without disturbing what F11 drives
• Session log — every line sent and every answer, numbered, newest first, with the instance that answered and its round trip

The protocol describes itself

$ nc 127.0.0.1 7777
OK qIV 2.190.0.235 remote v6 [Monitor2]
OK
help
qIV remote protocol v6
FORMAT CMD <name>|<takesValue 0|1>|<description>|<value description>
CMD NextImage|0|next image in the playlist|
CMD JumpToImage|1|go to a numbered image in the current playlist|image NUMBER, 1-based …
…

help lists everything this build accepts with its descriptions, so a client builds its own command list from one call instead of carrying a copy that goes stale. ping checks liveness, version reports the app and protocol version.

Since protocol v5 exactly one line always follows the banner, so a client never has to guess: AUTH <iterations> <salt> <nonce> when the server wants a password, or a bare OK when it does not — which is the OK on the second line above. A successful AUTH is answered OK as well. Nothing is signalled by silence, so no client needs a timeout to discover what kind of server it reached.

Security

Encryption is decided by the address, and never negotiated. A peer on the same machine (127.0.0.0/8, ::1, localhost) gets plaintext; every other peer — your own LAN included — gets TLS 1.2 / 1.3 from the first byte, before the banner. One listener on 0.0.0.0 serves both. Each end decides from the address independently, so there is no offer on the wire for an attacker to strip and no plaintext fallback to force.

The certificate is self-signed and the client pins it by SHA-256 fingerprint — no CA chain, which is the right answer for a machine no public CA would ever issue for. The fingerprint is shown at the bottom of the F9 panel; read it there and enter it in the client. A client with no pin stored refuses to connect rather than trusting whatever it is handed.

A password is compulsory off loopback — the listener refuses to start without one. It never crosses the wire: the server stores a PBKDF2-HMAC-SHA256 digest (210,000 iterations) and the client answers an HMAC over a fresh per-connection nonce, so every guess costs the guesser a full derivation and the server one HMAC. Failures escalate rather than banning outright — five from one address within ten minutes block it for fifteen minutes, and only five more earn a permanent entry in qivRemoteServerBlacklist.ini. The temporary block lives in memory only, so restarting qIV lifts it: mistyping your own password on a phone should not need a file edited to undo. Each failure is answered a second late, and a peer that connects and then goes quiet is dropped after ten seconds.

AllowList and BlackList take addresses, never domain names — a rule is matched against the address a connection actually arrived from, so DNS never enters the access decision. An empty AllowList denies everyone, by design. Both lists accept:

⚠ The star is a string prefix, not an octet boundary. 192.168.1.* is what it looks like, but 192.168.1* — no trailing dot — also matches 192.168.10.x and 192.168.100.x, and 1* matches most of the internet. Use /24 when the boundary matters. Entries that could never match an address are dropped when you save, and the panel names what it dropped.

File-altering commands — delete, move, paste, save — are structurally unreachable over the wire: a compile-time assertion proves none of them has a row in the command table, and the executor refuses them again at run time.

Exposing it to the internet. Authentication is the only boundary — behind it, a peer can do what someone sitting at the viewer can, including opening a local path and pulling the displayed image back. The AllowList is address-based, so a client on a dynamic IP pushes you toward * and leaves the password as the sole gate. Prefer a VPN (WireGuard, Tailscale) over port-forwarding: every protection above still applies, the AllowList becomes meaningful again with stable addresses, and the listener stops being reachable by anyone who scans the port.

qIV supports extensive CLI arguments for automation, digital signage, slideshows and locked-down kiosk environments.

QuickImageViewer.exe [image_path] [options]

Kiosk example:

QuickImageViewer.exe -dedicated -lock -fullscreen -slideshow -shuffle -slideshowInterval 8 -startFolder "D:\Ads"

A dedicated screen — the form the F8 panel writes into a startup shortcut. Folders and every setting come from the .ini and its .qim / .qpr lists:

qIV_dedicated_Lobby.exe -dedicated -config "D:\Screens\qIV_dedicated_Lobby.ini"

Runs an isolated instance, loops a shuffled slideshow every 8 seconds, and ignores all user mouse/keyboard input — ideal for unattended public displays.

• Renderer — Direct2D + D3D11 with GPU bitmap cache. GDI software fallback. Full ID2D1Effect graph for color operations.
• Decoding — WIC pipeline for OS-native formats. Custom decoders for EXR, HDR, PNM, QOI. SVG via resvg on a background IO thread.
• Threading — Worker thread pool for background decode and preload. Atomic indices prevent stale frames; window messages synchronize back to the UI thread.
• Caching — GPU bitmap cache with configurable size, preloading adjacent images in both directions. Live cache inspector panel.
• DPI — Per-monitor DPI aware V2; pixel-perfect on 4K and mixed-DPI setups.
• Persistence — Registry-backed settings, folder history manager, favorites system.

Third-Party Libraries

Building from Source

Written in C++23. Requires CMake and MSVC (Visual Studio 2022 or CLion).

git clone https://github.com/icyhoty2k/QuickImageViewer.git
cd QuickImageViewer
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

For offline geocoding, generate the GeoNames binary resources before building — download cities1000.txt, admin1CodesASCII.txt, admin2Codes.txt and countryInfo.txt from geonames.org into resources/geoData/, then run python tools/preprocess_cities.py.