How TranslucentTB works

The parts of the app

The portable zip of 2026.2 contains exactly these files. Two of the DLLs run inside explorer.exe, the rest in TranslucentTB's own process.

The Store package has the same binaries. It also declares an app alias (ttb.exe), a startup task and one capability, runFullTrust, which every desktop app in an MSIX package needs. Resource use: the README describes it as "a few MB of RAM and almost no CPU". We have not measured it ourselves.

Step 1: which taskbar is this?

Every time Explorer starts or restarts, TranslucentTB classifies the main taskbar (TaskbarAttributeWorker::GetTaskbarType):

You can see what TranslucentTB detected: choose Advanced › Dump dynamic state to log in the tray menu and look for Current taskbar type: in the log.

Step 2a: the classic route

SetWindowCompositionAttribute is an undocumented function in user32.dll that Windows itself uses for window effects. With the attribute WCA_ACCENT_POLICY it takes an accent state, flags and a color. TranslucentTB maps its accents like this:

The color is passed as a COLORREF-style value in ABGR byte order; settings.json stores it as #RRGGBBAA and TranslucentTB converts it.

Explorer resets that attribute on its own from time to time. So TranslucentTB installs ExplorerHooks.dll in Explorer with a window hook on the taskbar thread. It uses Microsoft Detours to wrap SetWindowCompositionAttribute inside Explorer: when Explorer tries to set an accent policy, the hook asks TranslucentTB's worker window first (with a 100 ms timeout, so a frozen TranslucentTB can't freeze Explorer) and swallows Explorer's call if TranslucentTB handles it. On Windows 10, ExplorerHooks also watches Task View from inside Explorer.

On the Mixed taskbar the same route is used. The Windows 11 border line (show_line) is handled separately: TranslucentTB hides a WorkerW child window (early 22621) or clips the inner XAML window by one pixel (22000). On the XAML taskbar, ExplorerTAP shows or hides the border element itself.

Step 2b: the Windows 11 route

The Windows 11 XAML taskbar ignores the accent policy: its background is a XAML element with its own brush. To change that brush, code has to run inside Explorer's XAML thread. TranslucentTB does it with the XAML Diagnostics API, the same API Visual Studio's Live Visual Tree uses to inspect running XAML apps. The API calls the injected component a TAP.

1. Copy. Explorer cannot load a DLL from the protected WindowsApps folder, so TranslucentTB first copies ExplorerTAP.dll and ExplorerHooks.dll to the package's TempState folder. The portable version copies them to %TEMP%\TranslucentTB, so you can still eject the drive it runs from. This is what the hidden copy_dlls setting controls (default on).
2. Mark. It writes a 4-byte Detours payload into Explorer. The DLL checks for that marker when it loads, so it only does anything when it is inside the right Explorer.
3. Load. A WH_CALLWNDPROC hook on the taskbar's thread makes Windows load the DLL into Explorer. (This replaced an older injection method in November 2024.)
4. Initialize. Inside Explorer, the DLL calls InitializeXamlDiagnosticsEx from Windows.UI.Xaml.dll. XAML Diagnostics can only be initialized once per thread, so each attempt runs on a fresh thread with a new connection name (VisualDiagConnection1, 2, …), up to 60 attempts 500 ms apart: at most 30 seconds.
5. Watch. XAML Diagnostics hands the DLL a site object. It watches the taskbar's visual tree, finds the background element of each taskbar, remembers its original brush and signals the TTBTAP_Ready event.
6. Connect. TranslucentTB waits up to 35 seconds for that event, fetches the TaskbarAppearanceService COM object and checks its version. 2026.2 expects TAP API version 4.
7. Paint. From then on TranslucentTB calls SetTaskbarAppearance (solid or acrylic brush with your tint), SetTaskbarBlur (a Direct2D Gaussian blur with standard deviation blur_radius ÷ 3, plus your tint) or ReturnTaskbarToDefaultAppearance for normal.

If step 4 or 6 fails, the log gets the critical error Failed to initialize XAML Diagnostics. and TranslucentTB shows its "has encountered a fatal error and cannot continue executing" dialog. Causes and fixes: Troubleshooting.

Why updates sometimes need a restart

InitializeXamlDiagnosticsEx pins the DLL in Explorer for the life of that Explorer process: it can never be unloaded. After TranslucentTB updates, Explorer may still hold the old ExplorerTAP. That is why step 6 checks the version. On a mismatch you get:

Restarting Explorer is enough in practice, because the old DLL lives in Explorer's process. Since 2026.1 ExplorerTAP also listens for the TranslucentTB package being uninstalled, and since 2026.2 for it being updated; when either happens, it ends the Explorer process so the old DLL is released. Windows restarts Explorer straight away, which is why the taskbar briefly disappears during a TranslucentTB update or uninstall.

What happens when TranslucentTB exits or crashes

Right after connecting, TranslucentTB asks ExplorerTAP to watch its process (RestoreAllTaskbarsToDefaultWhenProcessDies). When TranslucentTB exits for any reason, crashes included, ExplorerTAP puts the original brushes back, so you are not left with a stuck transparent taskbar. On a normal exit TranslucentTB also returns every taskbar to its stock look itself, which covers the classic route.

Step 3: knowing what is on screen

The look depends on what is happening: an open window, a maximized one, Start, Search, Task View, battery saver. TranslucentTB learns about each from a different Windows source:

Each time something changes, the worker re-runs one function, GetConfig, for every monitor's taskbar. It walks a fixed priority list and returns the first state that is enabled and true: battery saver, Task View, Aero Peek (desktop look), Start, Search, maximized window, visible window, desktop. See Dynamic modes for the details and an interactive version.

Built-in safety nets

• Explorer crash guard. If Explorer restarts twice within 30 seconds, TranslucentTB assumes something is wrong (often a clash with another shell mod), shows Windows Explorer restarted twice in the last 30 seconds! and exits instead of risking a crash loop. The development branch after 2026.2 adds a hidden setting, disable_explorer_crash_detection, to turn this off.
• No freezing Explorer. The ExplorerHooks call into TranslucentTB times out after 100 ms and aborts if TranslucentTB is hung.
• Reset on demand. Ctrl+Alt+Shift+F1 or Reset dynamic state clears all tracked state, finds the taskbars again and reconnects. See Tray menu.

Process hardening

Before doing anything else, TranslucentTB.exe turns on these Windows protections for its own process (HardenProcess in main.cpp):

These protect TranslucentTB's own process. They do not apply to Explorer, where ExplorerTAP and ExplorerHooks run. What that means for you, along with signatures and antivirus reports: Is TranslucentTB safe?

FAQ

Something wrong or out of date? Email hello@translucenttb.dev and we will fix it.