noctalia

noctalia/plugins/wallcards/README.md

@@ -0,0 +1,135 @@
+# Wallcards
+
+A `lively` wallpaper selector for images and videos with live preview.
+
+> [!NOTE]
+> Heavily inspired by other work — see Credits for details.
+
+https://github.com/user-attachments/assets/9ffbc83d-95e5-4dcd-a834-7bd224211b55
+
+## Features
+
+- Browse image and video wallpapers as a scrollable card stack
+- Live preview — applies the wallpaper and updates the colorscheme as you navigate
+- Filter by type or by dominant color
+- Keyboard and partial mouse navigation
+- Full settings panel with layout and behavior options
+
+## Dependencies
+
+```sh
+pacman -S ffmpeg mpvpaper imagemagick
+```
+
+## IPC Commands
+
+Control the plugin from the command line:
+
+```sh
+qs -c noctalia-shell ipc call plugin:wallcards toggle
+```
+
+## Keybinding Examples
+
+Add to your compositor configuration:
+
+### Hyprland
+
+```conf
+bind = SUPER, A, exec, qs -c noctalia-shell ipc call plugin:wallcards toggle
+```
+
+### Keybinds
+
+#### Navigation
+
+| Key | Action |
+| --- | --- |
+| `J` / `←` | Previous wallpaper |
+| `K` / `→` | Next wallpaper |
+| `H` | Scroll page back |
+| `L` | Scroll page forward |
+| `R` | Shuffle |
+
+#### Actions
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Apply wallpaper and close |
+| `Space` / `↓` | Apply wallpaper |
+| `Esc` / `Q` | Close |
+
+#### Filters
+
+| Key | Action |
+| --- | --- |
+| `A` | Show all |
+| `I` | Filter images |
+| `V` | Filter videos |
+| `F` | Toggle color filter (based on current card) |
+
+#### View
+
+| Key | Action |
+| --- | --- |
+| `T` | Toggle top bar |
+| `P` | Toggle live preview |
+| `?` | Toggle shortcut panel |
+
+#### Layout
+
+| Key | Action |
+| --- | --- |
+| `Shift + H / L` | Adjust card height |
+| `Shift + J / K` | Adjust center card width |
+| `Shift + N / P` | Adjust number of visible cards |
+| `Ctrl + J / K` | Adjust card spacing |
+| `Ctrl + H / L` | Adjust side strip width |
+
+#### Save
+
+| Key | Action |
+| --- | --- |
+| `Ctrl + S` | Save current layout and view settings |
+
+Scroll wheel also works for navigation.
+
+## Configuration
+
+All settings are available through the plugin settings panel in Noctalia. They can also be edited directly in `settings.json` in the plugin directory `~/.config/noctalia/plugins/wallcards`.
+
+| Setting | Description |
+| --- | --- |
+| `animation_cards_duration` | Duration of card transition animations in ms |
+| `animation_window_duration` | Duration of open/close animations in ms |
+| `animate_window` | Enable or disable open/close animations |
+| `background_color` | Color of the dimmed backdrop |
+| `background_opacity` | Opacity of the dimmed backdrop |
+| `cards_shown` | Number of visible cards in the stack |
+| `card_height` | Height of the card area in pixels |
+| `card_spacing` | Gap between cards in pixels |
+| `card_strip_width` | Width of non-center cards |
+| `card_radius` | Border radius of the cards |
+| `center_width_ratio` | Width of the center card as a ratio of the screen |
+| `image_filter` | File extensions treated as images |
+| `video_filter` | File extensions treated as videos |
+| `hide_help` | Hide the keyboard shortcuts panel |
+| `hide_top_bar` | Hide the toolbar above the cards |
+| `live_preview` | Apply wallpaper while navigating |
+| `selected_filter` | Default filter on open (`all`, `images`, `videos`) |
+| `shear_factor` | Shearing applied to the card stack |
+| `top_bar_height` | Height of the toolbar |
+
+## Known Issues
+
+- When a video card is played, the following warning is spamed ` WARN: vaExportSurfaceHandle failed`. Please contact me, if you have a solution for this.
+- Performance for going left or right differs. It is also affected by the total number of cards (is on my todo list)
+
+## License
+
+MIT License - see repository for details.
+
+## Credits
+
+- Inspired by [ilyamiro](https://github.com/ilyamiro/nixos-configuration) and [liixini](https://github.com/liixini/skwd)
+- Built for [Noctalia Shell](https://github.com/noctalia-dev/noctalia-shell)