# Graph Wallpaper

English | [한국어](README.ko.md)

Show Obsidian's graph view as your desktop wallpaper. It is the real, live graph: new notes and links appear as you write, and the graph can slowly rotate, drift and "breathe".

## Features

- **Live desktop wallpaper**: the graph opens in its own window that sits behind all other windows, on every workspace, and out of the taskbar, dock and Alt+Tab. Showing the desktop (Win+D or Super+D) keeps it visible.
- **Live motion**: slow rotation around the graph's center, gentle drift and zoom. It pauses for a few seconds after you pan or zoom, then continues from your new view.
- **Graph only**: hides the tab bar and view header; graph controls appear on hover.
- **Choose the graph**: the core Graph view, or the Advanced Graph View community plugin if you have it installed (shown without motion).
- **Survives restarts**: Obsidian restores the wallpaper window and the plugin pins it again.

## Usage

1. Enable the plugin. The wallpaper opens automatically (turn off **Open on startup** in the settings to change this).
2. Use the ribbon icon or the command **Graph Wallpaper: Toggle wallpaper** to show or hide it.
3. Adjust motion, speed and frames per second in the plugin settings. Lower frames per second use less CPU and GPU; 10 to 15 already looks smooth.

## Platform support

| Platform | Status |
| --- | --- |
| Linux, X11 session | Supported. Needs `python3` (installed by default on most distributions). |
| Windows 10 and 11 | Supported, experimental. Uses the built-in Windows PowerShell. The wallpaper is display-only, because the desktop icons layer receives the mouse. |
| Linux, Wayland session | Not supported: Wayland does not let apps place their windows on the desktop layer. |
| macOS | Not supported. |

Windows support is new. If the wallpaper does not appear or looks wrong, please [open an issue](https://github.com/kbeom9307/obsidian-graph-wallpaper/issues) with your Windows version.

## How it works

Obsidian plugins cannot change how the operating system stacks windows, so the plugin starts a small helper process for the wallpaper window:

- **Linux (X11)**: a Python script (`wallpaper-helper.py`) marks the window as a desktop window through the standard EWMH window-manager hints, using `libX11` directly.
- **Windows**: a PowerShell script (`wallpaper-helper.ps1`) moves the window into the desktop window behind the icons, the same technique other live-wallpaper tools use.

The helper source code is part of this repository (`src/helpers`). It is bundled in `main.js` and written to the plugin folder (`.obsidian/plugins/graph-wallpaper/`) when the wallpaper starts. The helper stops when you turn the wallpaper off or quit Obsidian, and the window returns to normal.

Live motion drives the core graph view's renderer, which is not part of Obsidian's public API. If a future Obsidian version changes it, the motion stops while the wallpaper itself keeps working.

## Disclosures

- **No network use** and no telemetry.
- **Runs local helper processes** (`python3` on Linux, `powershell.exe` on Windows) to change the wallpaper window's properties, as described above.
- **Files**: only writes the helper script into its own plugin folder inside your vault. It does not access files outside your vault.

## Manual installation

Download `main.js`, `manifest.json` and `styles.css` from the [latest release](https://github.com/kbeom9307/obsidian-graph-wallpaper/releases/latest) into `<vault>/.obsidian/plugins/graph-wallpaper/`, then restart Obsidian and enable the plugin in **Settings → Community plugins**.

## Development

```bash
npm install
npm run dev     # Rebuild main.js on change.
npm run build   # Type-check and build main.js for release.
```

## License

[MIT](LICENSE)