Skip to content

ownself/wewa

Repository files navigation

wewa

Display web content as desktop wallpaper on Windows, Linux and macOS.

A cross-platform Rust CLI tool that renders web pages (URLs or local HTML files) as fullscreen desktop wallpaper with multi-monitor support. Especially support ShaderToy page as dynamic wallpaper out of box, and also Ships with 37 built-in ShaderToy shaders — just run wewa -b <name> and enjoy.

跨平台 Rust CLI 工具,将网页内容渲染为全屏桌面壁纸,支持多显示器。特别支持了ShaderToy站点的支持(传入地址即可设置为壁纸),并且内置 37 款 ShaderToy 着色器作为动态壁纸,运行 wewa -b <名称> 即可开箱即用。


English | 中文


Preview / 预览

Built-in wallpapers are all dynamic wallpapers and optimized with GPU performance, you can check out demonstraition from clicking preview screenshots as below to link to ShaderToy page.

内建的着色器壁纸均为动态壁纸,并且已优化了GPU性能,可以通过点击下方的预览图至ShaderToy站点来预览效果。


2dclouds
by drift

accretion
by Xor

ascend
by bug

auroras
by nimitz

chillywave
by Tornax07

chillywave2
by Tornax07

classic4colors
by zosxavius

clouds
by iq

crumpledwave
by nasana

darktransit
by diatribes

forknixietubeclock
by picoplanetdev

hexagonalgrid
by iq

hexneonlove
by tutmann

hieroglyphs
by nayk

iceandfire
by mattz

linuxwallpaper
by movAX13h

mandelbrot
by JennySchub

montereywannabe
by mrange

patternminimax
by PAEz

pinkvoid
by iVader

plasma
by Xor

plasmawaves
by scarletshark

polyhedrons
by yli110

proteanclouds
by nimitz

ps3xmb
by llmciv

seventymelt
by tomorrowevening

singularity
by Xor

spiralgalaxy
by mrange

starnest
by Kali

starshipreentry
by negentrope

synthwavecanyon
by mrange

tilewarppt3
by byt3_m3chanic

tumblerock
by diatribes

undulatingurchin
by ChunderFPV

voronoigradient
by gls9102

wadongmo759
by dongmo

waveymc
by feresr

All shaders are sourced from ShaderToy. Thanks to all the talented shader artists!

所有着色器均来自 ShaderToy,感谢所有才华横溢的着色器艺术家!


English

Features

  • Cross-Platform — Windows, Linux (Wayland: Hyprland, Sway, KDE 6+, GNOME) and macOS
  • Multi-Monitor — Apply to all displays or target specific ones
  • Local File Support — Built-in HTTP server for local HTML/JS/CSS projects
  • ShaderToy Integration — Automatically converts ShaderToy URLs to fullscreen embed format. (Caution : native resolution may cause performance issues.)
  • Local .shader Support — Wrap single-pass ShaderToy snippets into a fullscreen WebGL runtime (Better performance with --scale parameter)
  • iChannel Textures — Supply 2D textures (.png/.jpg) and 3D volume textures (.bin) for ShaderToy shaders that use iChannel0iChannel3
  • 37 Built-in Shaders — Curated collection of ShaderToy shaders with pre-tuned parameters, ready to use with -b <name>
  • IPC Control — Stop wallpapers remotely via named pipes (Windows) or Unix domain sockets (Linux/macOS)
  • Graceful Shutdown — Ctrl+C handling with platform-specific cleanup

Platform Details

Platform Technique WebView Backend
Windows WorkerW desktop embedding WebView2 (Edge)
Linux (Hyprland, Sway, KDE 6+) GTK layer-shell background surface WebKitGTK
Linux (GNOME) GTK window + companion GNOME Shell extension WebKitGTK
macOS NSWindow desktop-level ordering WKWebView

Requirements

  • Windows — Windows 10 (April 2018+) or Windows 11; WebView2 Runtime (usually pre-installed)
  • Linux (Hyprland / Sway / KDE 6+) — Wayland session with layer-shell support; GTK 3, WebKitGTK, gtk-layer-shell
  • Linux (GNOME) — GNOME Shell 45+; GTK 3, WebKitGTK. A companion GNOME Shell extension is automatically installed on first run. A one-time log-out/log-in is required to activate the extension.
  • macOS — macOS 10.10+; no additional dependencies (WKWebView is a system framework)

Installation

Package Managers

# Homebrew
brew tap ownself/app-distribution https://github.com/ownself/app-distribution
brew install wewa

# Scoop
scoop bucket add ownself-app-distribution https://github.com/ownself/app-distribution
scoop install wewa

# AUR
yay -S wewa-bin

Build from Source

git clone https://github.com/ownself/wewa.git
cd wewa

# Linux dependencies (Debian/Ubuntu)
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libgtk-layer-shell-dev

cargo build --release
# Binary: target/release/wewa(.exe)

Usage

# URL as wallpaper (all monitors)
wewa https://example.com/wallpaper.html

# Target a specific monitor (0-based index)
wewa https://example.com --display 0

# ShaderToy (auto-converted to fullscreen embed)
wewa "https://www.shadertoy.com/view/tlVGDt"

# Local ShaderToy-style shader with default full-resolution rendering
wewa ./octagrams.shader

# Lower shader render scale for better performance
wewa ./octagrams.shader --scale 0.5

# Slow down shader animation without changing shader source
wewa ./octagrams.shader --time-scale 0.5

# Speed up shader animation for comparison or debugging
wewa ./octagrams.shader --time-scale 2.0

# Shader with iChannel textures (2D png/jpg or 3D .bin volume)
wewa ./clouds.shader --channel0 textures/noise_rgba.png --channel1 textures/noise_grey.png --channel2 textures/noise_volume.bin

# Short aliases for channel and time-scale options
wewa ./clouds.shader --c0 textures/noise_rgba.png --c1 textures/noise_grey.png --ts 0.5

# Use a built-in shader (no files needed)
wewa -b starnest

# List all available built-in shaders
wewa -b list

# Pick a random built-in shader
wewa -r

# Override built-in defaults
wewa -b clouds -s 1.0 --ts 0.5

# Local HTML file
wewa ./my-wallpaper/index.html

# Directory containing index.html
wewa ./my-wallpaper/

# Custom HTTP server port
wewa ./wallpaper.html --port 9000

# Stop wallpaper on display 0
wewa --stop 0

# Stop all wallpapers
wewa --stopall
wewa --sa

# Verbose output
wewa --verbose https://example.com

Command Line Options

Option Short Description
--builtin <NAME> -b Use a built-in shader by name (use list to see all)
--random -r Use a random built-in shader
--display <N> -d Target specific display (0-based index)
--stop <N> Stop wallpaper on display N
--stopall --sa Stop all running wallpapers
--port <PORT> -p HTTP server port for local files (default: 8080)
--scale <FACTOR> -s Shader render scale (default: 1.0, or per-shader default with -b)
--time-scale <FACTOR> --ts Shader animation time scale (default: 1.0, or per-shader default with -b)
--channel0 <FILE> --c0 Texture file for iChannel0 (2D image or 3D .bin volume)
--channel1 <FILE> --c1 Texture file for iChannel1
--channel2 <FILE> --c2 Texture file for iChannel2
--channel3 <FILE> --c3 Texture file for iChannel3
--verbose -v Enable verbose output
--help -h Show help message
--version -V Show version

Shader Tuning

  • --scale changes render resolution for local .shader inputs. Lower values usually improve performance at the cost of sharpness.
  • --time-scale changes the speed of the injected iTime and iTimeDelta values for local .shader inputs.
  • Use --time-scale 1.0 for original speed, values below 1.0 to slow animation down, values above 1.0 to speed it up, and 0 to freeze time for debugging.
  • --time-scale avoids editing shader source when you only want to compare animation pacing across different shaders.

iChannel Textures

Many ShaderToy shaders read from iChannel0iChannel3 for noise, photos, or other data. You can supply these textures from local files:

  • 2D textures — any image format (.png, .jpg, etc.) → declared as sampler2D
  • 3D volume textures — ShaderToy .bin format (header: 4-byte signature + width/height/depth/channels, followed by raw uint8 data) → declared as sampler3D

The file extension determines the type: .bin = 3D volume, anything else = 2D texture.

Channels that are not provided are automatically declared. If the shader fails to compile with sampler2D, the engine retries with sampler3D — so most shaders work without any --channel flags, albeit with blank (black) texture reads.

To find a ShaderToy shader's iChannel configuration, open the shader page in a browser and run this in DevTools (F12) Console:

JSON.stringify(gShaderToy.mEffect.mPasses.map((pass, pi) => ({
  pass: pi, type: pass.mType,
  inputs: pass.mInputs.map((inp, i) => inp ? {
    channel: i, type: inp.mInfo.mType, src: inp.mInfo.mSrc
  } : null).filter(x => x)
})), null, 2)

Then download the textures from https://www.shadertoy.com<src_path> in your browser.

Built-in Shaders

The binary ships with 37 curated shaders and their required textures — no external files needed:

wewa -b list        # see all available names
wewa -b starnest    # use it

Each built-in shader has pre-tuned scale and time_scale defaults (configured in builtins.json) optimized for desktop wallpaper use. You can override any default with CLI flags:

wewa -b clouds -s 1.0 --ts 0.5

Credits

The built-in shaders are sourced from ShaderToy. We are grateful to the talented shader artists who created and shared these works:

Shader Author ShaderToy
2dclouds drift 4tdSWr
accretion Xor WcKXDV
ascend bug 33KBDm
auroras nimitz XtGGRt
chillywave Tornax07 3XSBDW
chillywave2 Tornax07 NflGRM
classic4colors zosxavius W3K3zy
clouds iq XslGRr
crumpledwave nasana 3ttSzr
darktransit diatribes WcdczB
forknixietubeclock picoplanetdev Dds3WB
hexagonalgrid iq WtSfWK
hexneonlove tutmann 3tKSWV
hieroglyphs nayk Nff3Ds
iceandfire mattz MdfBzl
linuxwallpaper movAX13h 4dcGRn
mandelbrot JennySchub NlcSRj
montereywannabe mrange NdVfzK
patternminimax PAEz sfS3Dz
pinkvoid iVader ddKXWh
plasma Xor WfS3Dd
plasmawaves scarletshark ltXczj
polyhedrons yli110 sc2GzW
proteanclouds nimitz 3l23Rh
ps3xmb llmciv fcf3Dn
seventymelt tomorrowevening XsX3zl
singularity Xor 3csSWB
spiralgalaxy mrange wsBBWD
starnest Kali XlfGRj
starshipreentry negentrope XX3fDH
synthwavecanyon mrange slcXW8
tilewarppt3 byt3_m3chanic sff3RB
tumblerock diatribes NcjGDh
undulatingurchin ChunderFPV 332XWd
voronoigradient gls9102 WdlyRS
wadongmo759 dongmo fd3fD2
waveymc feresr NtKGWw

Troubleshooting

  • WebView2 not available (Windows) — Install from Microsoft
  • Layer-shell not available (Linux) — Ensure you are on a Wayland session with a layer-shell compositor (e.g. Hyprland, Sway, KDE 6+), and install libgtk-3-dev libwebkit2gtk-4.1-dev libgtk-layer-shell-dev
  • GNOME: "please log out and log back in" — On first run, wewa automatically installs its companion GNOME Shell extension. GNOME Shell must be restarted to load new extensions, and on Wayland the only way is to log out and log back in. Subsequent runs will work without restart.
  • Port already in use — Use --port 9000 to pick a different port
  • Shader performance is poor — Use --scale 0.5 or --scale 0.75 for .shader inputs
  • Finding display numbers — Run with --verbose to list detected displays

Architecture

src/
├── main.rs           # Entry point, CLI dispatch, URL transformation
├── builtin.rs        # 37 embedded shaders & textures, built-in shader extraction
├── cli.rs            # Argument parsing (clap)
├── config.rs         # Configuration and instance tracking
├── shader.rs         # Shader file support, iChannel textures, WebGL runtime generation
├── server.rs         # Local HTTP server (tiny_http)
├── ipc.rs            # IPC (named pipes / Unix sockets)
├── display.rs        # Shared monitor data model
├── wallpaper.rs      # Shared wallpaper config / errors
└── platform/
    ├── windows/      # WorkerW technique + WebView2
    ├── linux/        # GTK layer-shell + WebKitGTK
    └── macos/        # NSWindow desktop-level + WKWebView

License

MIT


中文

功能特性

  • 跨平台 — 支持 Windows、Linux(Wayland:Hyprland、Sway、KDE 6+、GNOME)和 macOS
  • 多显示器 — 应用到所有显示器或指定特定显示器
  • 本地文件支持 — 内置 HTTP 服务器,支持本地 HTML/JS/CSS 项目
  • ShaderToy 集成 — 自动将 ShaderToy URL 转换为全屏嵌入格式(警告:原生分辨率可能会导致性能问题)
  • 本地 .shader 支持 — 将单文件 ShaderToy 片段包装成全屏 WebGL 运行时(使用--scale参数使得性能更友好)
  • iChannel 纹理 — 为使用 iChannel0iChannel3 的 ShaderToy 着色器提供 2D 纹理(.png/.jpg)和 3D 体积纹理(.bin
  • 37 款内置着色器 — 精选 ShaderToy 着色器合集,预调参数,通过 -b <名称> 即可开箱即用
  • IPC 控制 — 通过命名管道 (Windows) 或 Unix Domain Socket (Linux/macOS) 远程停止壁纸
  • 优雅关闭 — Ctrl+C 处理并执行平台相关清理

平台实现

平台 技术方案 WebView 后端
Windows WorkerW 桌面嵌入 WebView2 (Edge)
Linux (Hyprland, Sway, KDE 6+) GTK layer-shell 背景层 WebKitGTK
Linux (GNOME) GTK 窗口 + GNOME Shell 配套扩展 WebKitGTK
macOS NSWindow 桌面层级窗口 WKWebView

系统要求

  • Windows — Windows 10 (2018年4月更新+) 或 Windows 11;WebView2 运行时(通常已预装)
  • Linux (Hyprland / Sway / KDE 6+) — 支持 layer-shell 的 Wayland 会话;GTK 3、WebKitGTK、gtk-layer-shell
  • Linux (GNOME) — GNOME Shell 45+;GTK 3、WebKitGTK。配套 GNOME Shell 扩展会在首次运行时自动安装,需注销并重新登录一次以激活扩展。
  • macOS — macOS 10.10+;无额外依赖(WKWebView 为系统框架)

安装

包管理器安装

# Homebrew
brew tap ownself/app-distribution https://github.com/ownself/app-distribution
brew install wewa

# Scoop
scoop bucket add ownself-app-distribution https://github.com/ownself/app-distribution
scoop install wewa

# AUR
yay -S wewa-bin

从源码构建

git clone https://github.com/ownself/wewa.git
cd wewa

# Linux 依赖(Debian/Ubuntu 系)
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libgtk-layer-shell-dev

cargo build --release
# 二进制文件:target/release/wewa(.exe)

使用方法

# 将 URL 设为壁纸(所有显示器)
wewa https://example.com/wallpaper.html

# 指定显示器(从 0 开始的索引)
wewa https://example.com --display 0

# ShaderToy(自动转换为全屏嵌入格式)
wewa "https://www.shadertoy.com/view/tlVGDt"

# 本地 ShaderToy 风格着色器
wewa ./octagrams.shader

# 降低渲染缩放以提升性能
wewa ./octagrams.shader --scale 0.5

# 不修改 shader 源码,直接放慢动画速度
wewa ./octagrams.shader --time-scale 0.5

# 加快动画速度,便于对比或调试
wewa ./octagrams.shader --time-scale 2.0

# 带 iChannel 纹理的 Shader(2D png/jpg 或 3D .bin 体积纹理)
wewa ./clouds.shader --channel0 textures/noise_rgba.png --channel1 textures/noise_grey.png --channel2 textures/noise_volume.bin

# 使用简短别名
wewa ./clouds.shader --c0 textures/noise_rgba.png --c1 textures/noise_grey.png --ts 0.5

# 使用内置着色器(无需任何文件)
wewa -b starnest

# 列出所有可用的内置着色器
wewa -b list

# 随机选取一款内置着色器
wewa -r

# 覆盖内置默认参数
wewa -b clouds -s 1.0 --ts 0.5

# 本地 HTML 文件
wewa ./my-wallpaper/index.html

# 包含 index.html 的目录
wewa ./my-wallpaper/

# 自定义 HTTP 服务器端口
wewa ./wallpaper.html --port 9000

# 停止显示器 0 上的壁纸
wewa --stop 0

# 停止所有壁纸
wewa --stopall
wewa --sa

# 详细输出
wewa --verbose https://example.com

命令行选项

选项 简写 描述
--builtin <NAME> -b 使用内置着色器(list 查看全部)
--random -r 随机选取一款内置着色器
--display <N> -d 指定目标显示器(从 0 开始的索引)
--stop <N> 停止显示器 N 上的壁纸
--stopall --sa 停止所有运行中的壁纸
--port <PORT> -p 本地文件 HTTP 服务器端口(默认:8080)
--scale <FACTOR> -s 渲染缩放(默认:1.0,使用 -b 时按内置配置)
--time-scale <FACTOR> --ts 动画时间缩放(默认:1.0,使用 -b 时按内置配置)
--channel0 <FILE> --c0 iChannel0 纹理文件(2D 图片或 3D .bin 体积纹理)
--channel1 <FILE> --c1 iChannel1 纹理文件
--channel2 <FILE> --c2 iChannel2 纹理文件
--channel3 <FILE> --c3 iChannel3 纹理文件
--verbose -v 启用详细输出
--help -h 显示帮助信息
--version -V 显示版本信息

Shader 调节

  • --scale 用于调整本地 .shader 输入的渲染分辨率;值越小通常性能越好,但画面会更模糊。
  • --time-scale 用于调整本地 .shader 输入注入的 iTimeiTimeDelta 速度。
  • --time-scale 1.0 表示原始速度,小于 1.0 表示减速,大于 1.0 表示加速,0 可用于冻结时间以便调试。
  • 当你只是想对比不同 shader 的动画节奏时,--time-scale 可以避免逐个修改 shader 源码。

iChannel 纹理

许多 ShaderToy 着色器通过 iChannel0iChannel3 读取噪声、照片或其他数据。你可以通过本地文件提供这些纹理:

  • 2D 纹理 — 任意图片格式(.png.jpg 等)→ 声明为 sampler2D
  • 3D 体积纹理 — ShaderToy .bin 格式(文件头:4 字节签名 + 宽/高/深/通道数,后接 uint8 原始数据)→ 声明为 sampler3D

文件扩展名决定类型:.bin = 3D 体积纹理,其他 = 2D 纹理。

未提供的通道会自动声明。如果以 sampler2D 编译失败,引擎会自动重试 sampler3D——因此大多数着色器无需任何 --channel 参数即可运行,只是未绑定的纹理读取结果为黑色。

要查看某个 ShaderToy 着色器的 iChannel 配置,在浏览器中打开该着色器页面,在开发者工具(F12)控制台中执行:

JSON.stringify(gShaderToy.mEffect.mPasses.map((pass, pi) => ({
  pass: pi, type: pass.mType,
  inputs: pass.mInputs.map((inp, i) => inp ? {
    channel: i, type: inp.mInfo.mType, src: inp.mInfo.mSrc
  } : null).filter(x => x)
})), null, 2)

然后在浏览器中从 https://www.shadertoy.com<src路径> 下载对应的纹理文件。

内置着色器

程序内嵌了 37 款精选着色器及其所需纹理,无需任何外部文件即可使用:

wewa -b list        # 查看所有可用名称
wewa -b starnest    # 直接使用

每款内置着色器都有预调的 scaletime_scale 默认值(配置在 builtins.json 中),针对桌面壁纸场景优化。你可以通过命令行参数覆盖任意默认值:

wewa -b clouds -s 1.0 --ts 0.5

致谢

内置着色器来源于 ShaderToy。感谢才华横溢的着色器艺术家们创作并分享了这些精彩的作品:

着色器 作者 ShaderToy
2dclouds drift 4tdSWr
accretion Xor WcKXDV
ascend bug 33KBDm
auroras nimitz XtGGRt
chillywave Tornax07 3XSBDW
chillywave2 Tornax07 NflGRM
classic4colors zosxavius W3K3zy
clouds iq XslGRr
crumpledwave nasana 3ttSzr
darktransit diatribes WcdczB
forknixietubeclock picoplanetdev Dds3WB
hexagonalgrid iq WtSfWK
hexneonlove tutmann 3tKSWV
hieroglyphs nayk Nff3Ds
iceandfire mattz MdfBzl
linuxwallpaper movAX13h 4dcGRn
mandelbrot JennySchub NlcSRj
montereywannabe mrange NdVfzK
patternminimax PAEz sfS3Dz
pinkvoid iVader ddKXWh
plasma Xor WfS3Dd
plasmawaves scarletshark ltXczj
polyhedrons yli110 sc2GzW
proteanclouds nimitz 3l23Rh
ps3xmb llmciv fcf3Dn
seventymelt tomorrowevening XsX3zl
singularity Xor 3csSWB
spiralgalaxy mrange wsBBWD
starnest Kali XlfGRj
starshipreentry negentrope XX3fDH
synthwavecanyon mrange slcXW8
tilewarppt3 byt3_m3chanic sff3RB
tumblerock diatribes NcjGDh
undulatingurchin ChunderFPV 332XWd
voronoigradient gls9102 WdlyRS
wadongmo759 dongmo fd3fD2
waveymc feresr NtKGWw

故障排除

  • WebView2 不可用 (Windows) — 从 Microsoft 安装
  • Layer-shell 不可用 (Linux) — 确认在支持 layer-shell 的 Wayland 会话中运行(如 Hyprland、Sway、KDE 6+),并安装 libgtk-3-dev libwebkit2gtk-4.1-dev libgtk-layer-shell-dev
  • GNOME:提示"请注销并重新登录" — 首次运行时 wewa 会自动安装配套的 GNOME Shell 扩展。GNOME Shell 需要重启才能加载新扩展,Wayland 下只能通过注销重新登录来重启。后续运行无需再次重启。
  • 端口被占用 — 使用 --port 9000 指定其他端口
  • Shader 性能较差 — 对 .shader 输入使用 --scale 0.5--scale 0.75
  • 查找显示器编号 — 使用 --verbose 运行以查看检测到的显示器

项目结构

src/
├── main.rs           # 入口点、CLI 分发、URL 转换
├── cli.rs            # 参数解析 (clap)
├── config.rs         # 配置和实例跟踪
├── shader.rs         # Shader 文件支持、iChannel 纹理、WebGL 运行时生成
├── server.rs         # 本地 HTTP 服务器 (tiny_http)
├── ipc.rs            # 进程间通信(命名管道 / Unix Socket)
├── display.rs        # 共享显示器数据模型
├── wallpaper.rs      # 共享壁纸配置与错误类型
└── platform/
    ├── windows/      # WorkerW 技术 + WebView2
    ├── linux/        # GTK layer-shell + WebKitGTK
    └── macos/        # NSWindow 桌面层级 + WKWebView

许可证

MIT

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors