🌈 Obsidian DTB

Build Your Own Wallpaper Library in Obsidian!

Make every note-taking experience visually inspiring

🇺🇸 English ｜ 🇨🇳 中文版

---

Introduction

Obsidian Dynamic Theme Background is a highly customizable and intelligent wallpaper management plugin for Obsidian. By integrating multiple popular wallpaper sources (Unsplash, Pixabay, Pexels, Wallhaven, Qihoo 360 Wallpaper) and supporting custom APIs, you can easily build a personalized wallpaper library. The plugin supports both local and remote images, and allows automatic switching based on time periods, creating different atmospheres for work and rest.

Core Goal: Let every Obsidian user enjoy an ultimate wallpaper experience, making knowledge management more beautiful and inspiring.

✨ Key Features

• 🖼️ Powerful Wallpaper Sources for a Personalized Library

  • 🌐 Multi-source Wallpaper Library: Integrates Unsplash, Pixabay, Pexels, Wallhaven, Qihoo 360 Wallpaper, and custom APIs to build your own Obsidian wallpaper library
  • 📁 Local & Remote Image Management: Freely add local or online images for flexible collection and management

• 🎨 Excellent Visual Experience & Theme Compatibility

  • 🎚️ Customizable Wallpaper Properties: Adjust blur, brightness, saturation, and color to fit any theme style
  • 🧩 Ultimate Theme Compatibility: All styles use Obsidian CSS variables, perfectly blending with any theme, supporting both dark and light modes

• ⚡ Highly Customizable Wallpaper Switching Rules

  • ⏰ Smart Time-based Switching: Automatically change wallpapers based on set time periods, creating different work/rest atmospheres
  • 🔄 Interval Switching: Automatically switch wallpapers at set intervals for a fresh visual experience
  • 🎲 One-click Random/Manual Switching: Quickly switch wallpapers via command palette for instant inspiration

• 🤝 Outstanding User Experience & Intuitive Operations

  • 🚀 Performance Optimization: Asynchronous loading and caching for smooth experience
  • 🖼️ Rich Default Wallpapers & API Examples: Get started quickly with built-in resources
  • 🏷️ Type Badges & Preview Animations: Each wallpaper item features type badges and preview animations for rich visual feedback
  • 🗂️ Batch Operations & Quick Commands: Efficiently add, delete, and switch wallpapers in bulk

• 📦 Richer Background Experience (Planned)

  • 🌦️ Real-time Data Integration: Planned support for automatic background changes based on weather, time, etc.
  • 🎭 Theme Packs & Marketplace: Share and download custom theme configurations
  • 🎬 Dynamic Backgrounds: Support for video, GIF, and other multimedia backgrounds
  • 🎵 Audio Backgrounds: Add ambient sounds for immersive focus
  • 🤖 AI-generated Backgrounds: Integrate AI to create unique wallpapers
  • 📱 Responsive & Mobile Adaptation: Elegant layouts and smooth interactions on both desktop and mobile
  • 🚧 More Innovative Features: Continuous iteration, stay tuned!

🖼️ Preview

⬇️ Installation

🛒 Method 1: Install via Obsidian Plugin Marketplace

TODO: Pending approval in Obsidian Plugin Marketplace

pull request: obsidianmd/obsidian-releases#7359

🛠️ Method 2: Install via BRAT Plugin

1. Install the BRAT plugin
2. In BRAT, Add beta plugin -> enter this repo URL https://github.com/sean2077/obsidian-dynamic-theme-background and install
3. Enable the plugin in Obsidian

📦 Method 3: Manual Installation

1. Download the latest main.js, manifest.json, and styles.css files
2. Create the folder .obsidian/plugins/dynamic-theme-background/ in your Obsidian vault
3. Place the downloaded files into this folder
4. Restart Obsidian and enable the plugin in settings

🚀 Usage

⚡ Quick Start

1. Enable the plugin: Enable Dynamic Theme Background in Obsidian settings
2. Add wallpapers: Add your favorite wallpapers (local images, online images, or API wallpapers) in the plugin settings page
3. Configure rules: Set time-based or interval switching rules
4. Enjoy the experience: Use the command palette to quickly switch, or let the plugin automatically change wallpapers for you

💡 Commands

Type dtb in the command palette (Ctrl/Cmd + P) to find all related commands.

💡 Tip: Use the command to open the settings page in a new tab for preview and adjustment.

❓ FAQ

• Wallpapers appear blurry or unclear?
  • Adjust the blur parameter in settings, or choose higher resolution images.
• How to add local images as wallpapers?
  • Click "Add Wallpaper" in the settings page, select "Image" type, and enter the path relative to the vault root.
• API fails to fetch wallpapers?
  • Check your network connection, ensure the API key is configured correctly, and check the status indicator in plugin settings.
• API activation fails?
  • When enabling an API, the plugin will try to fetch wallpapers from the source. If it fails, an error message will be shown and the API will be disabled.
• Plugin is not compatible with my theme?
  • The plugin uses standard Obsidian CSS variables and should be compatible with most themes. If you encounter issues, please submit an issue on GitHub.

📝 Notes

1. Dark and Light Theme: The plugin is optimized for dark themes. You may need to adjust parameters for light themes.
2. Theme Compatibility: The plugin uses standard Obsidian CSS variables and should be compatible with most themes. If you encounter issues, please submit an issue on GitHub. If your theme supports defining backgrounds, please choose between enabling theme custom backgrounds and DTB backgrounds, as this may cause style conflicts.
3. Style Override Notice: The plugin uses the following CSS variables to achieve background effects. Be aware of possible impacts on existing topics:

/* Workspace Background */
.dtb-enabled :not(.modal):not(.modal *) {
    --background-primary: var(--dtb-bg-color) !important;
    --background-primary-alt: var(--dtb-bg-color) !important;
    --background-secondary: var(--dtb-bg-color) !important;
    --background-secondary-alt: var(--dtb-bg-color) !important;
}
.dtb-enabled .workspace::before {
    background-image: var(--dtb-bg-image);
    background-size: var(--dtb-bg-size);
    background-repeat: no-repeat;
    background-position: center;
    filter: blur(var(--dtb-blur-depth)) brightness(var(--dtb-brightness)) saturate(var(--dtb-saturate));
    content: "";
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    z-index: -1;
}

/* Changes to other parts of the workspace */
.dtb-enabled .workspace-tab-header-container,
.dtb-enabled .workspace-tab-header-container .workspace-tab-header.tappable.is-active,
.dtb-enabled .workspace-tab-header.tappable.is-active,
.dtb-enabled .workspace-split.mod-vertical.mod-root,
.dtb-enabled .workspace-split.mod-horizontal.mod-sidedock.mod-left-split,
.dtb-enabled .workspace-split.mod-horizontal.mod-sidedock.mod-right-split,
.dtb-enabled .titlebar-button-container.mod-right,
.dtb-enabled .status-bar,
.dtb-enabled .workspace-ribbon::before,
.dtb-enabled .workspace-ribbon {
    background-color: var(--dtb-bg-color) !important;
}

📄 License

See LICENSE file.

🤝 Contributing & Support

We welcome all forms of contribution!

🛠️ Contribute Code

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

💡 Feedback & Suggestions

• 🐛 Report Bug
• 💡 Feature Request

✨ Support the Project

If this plugin helps you, you can:

• Star the project on GitHub ⭐
• Share with other Obsidian users 📢
• Join discussions and suggest improvements 💬

👥 Contributors

Thanks goes to these wonderful people:

sean2077 💻 📖 ⚠️ 🚧

Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!