Introduction¶

The default interface background in DSH is static. To place a few personal images or a video loop in the development workspace, you typically have to manually edit theme files and CSS, and there is nowhere to adjust the order, interval, or opacity. dsh-bg-carousel turns this into a standard plugin: drop media files into a directory, and the interface background will automatically rotate; the directory, order, interval, and opacity are all configurable in the panel.

Below is an introduction to the plugin’s positioning, core features, installation steps, and typical usage.

What is this¶

dsh-bg-carousel is a standard dsh bundle plugin, maintained by Jonah-Wu23, with the current version v0.3.0, npm package name @jonahwu/dsh-bg-carousel, and the code uses the MIT License. One-sentence positioning: Automatic rotation of images and videos for the DeepSeek Harness interface background.

It adapts to the web interface of dsh v0.1.2-rc.1, with an architecture split into two ends:

• The Host side scans the media directory and provides media routes and APIs via webServer;
• The Client side registers a “Background” entry at the bottom of the sidebar, responsible for the control panel and background rendering.

Core Features¶

Image and Video Backgrounds¶

Images support JPEG, PNG, WebP, SVG, and GIF, rendered as the body background with a dimming overlay layer, automatically taking values based on light/dark themes. Videos support MP4, WebM, MOV, HLS, and FLV, with muted autoplay and a cover fit to fill the viewport.

Format compatibility varies by environment: HLS is natively supported by Safari; FLV requires MSE extensions (such as flv.js); in Chromium environments, files of these two types are automatically skipped, and rotation continues. Whether MOV can play depends on the encoding within the container; H.264 is usually playable.

Mixed Rotation¶

Images and videos rotate in the same queue. The advancement rules are as follows:

1. Interval is shorter than the video duration: Truncate the current video and switch to the next;
2. Interval is longer than the video duration: Switch immediately after the video finishes;
3. Video stalls: Fallback to timer-based advancement.

If autoplay is restricted by the environment, the video stops at the first frame, while the timer progresses normally. Undecodable files are automatically skipped and the reason is logged in the browser console. If all media fails, the rotation is paused and an alert is shown in the panel.

Order and Opacity¶

Thumbnails support drag-and-drop sorting. The order takes effect immediately and persists to server-side settings, with new files appended at the end alphabetically. The “Panel Opacity” slider adjusts the interface token opacity in real-time and applies to both images and videos.

Directory and Thumbnails¶

The media directory can be manually typed in the panel or clicked with the “Select” button to trigger the host’s native directory picker (Windows system folder dialog), supporting both absolute paths and workspace relative paths. “Open Folder” opens the current media directory in the host system file manager and does not rely on browser file:// links. If the directory is unavailable, it falls back to the default directory (workspace backgrounds) with an alert, and rotation continues.

Large images generate 320px JPEG thumbnails on the host (Windows uses PowerShell System.Drawing); the cache directory is ~/.dsh/bg-carousel/thumbs/. Thumbnails use lazy loading + asynchronous decoding, so the panel remains smooth even with hundreds of high-definition images.

Installation and Enablement¶

The plugin requires webServer and client UI. It is recommended to install it to the web profile (or any profile containing @deepseek-ai/dsh-web-app). If installed to other profiles, the plugin remains silent and does not affect startup. “Select Directory” and “Open Folder” depend on the directoryPicker / openWorkspacePath capabilities of the dsh v0.1.2-rc.1 combination. The plugin is not compatible with dsh versions earlier than v0.1.2-alpha.1 and v0.1.1-rc2; confirm the dsh version before installing.

The following installation commands require pnpm to be in the PATH. Choose any one of the three methods and execute only one command at a time.

Git source installation:

dsh plugin --profile web add github:Jonah-Wu23/dsh-bg-carousel

Or install directly from the tgz in the GitHub Release:

dsh plugin --profile web add https://github.com/Jonah-Wu23/dsh-bg-carousel/releases/download/v0.3.0/jonahwu-dsh-bg-carousel-0.3.0.tgz

You can also use a local path; fill in the tgz file path or plugin directory path at <...>:

dsh plugin --profile web add <local tgz or directory path>

Restart dsh after installation to apply the changes. To uninstall, run:

dsh plugin --profile web remove @jonahwu/dsh-bg-carousel

To build from source, you need a checkout of the dsh source code, bash, and Node.js in PATH, then run:

DSH_CHECKOUT=<dsh source checkout> bash scripts/build.sh

The script uses tsc to compile the host side and tsdown to pack the client. Zero new runtime dependencies: the client only requires the platform seed module react and does not introduce hls.js or flv.js; unsupported formats are automatically skipped.

Typical Usage¶

1. Copy images and videos to the media directory. The default is the workspace’s backgrounds directory, which can be modified in the panel. Note the size limits: images are capped at 64 MiB, videos at 256 MiB.

2. After restarting dsh, click the “Background” entry at the bottom of the sidebar to open the control panel. The panel will automatically load the media list of the current directory.

3. Click the thumbnail to switch the background; drag the thumbnail to reorder; check “Auto Rotate” to loop at the set interval (intervalMs takes values from 1500 to 120000 milliseconds); drag the “Panel Opacity” slider to adjust the interface transparency (panelOpacity takes values from 0.1 to 0.95).

Server-side API¶

For secondary development or troubleshooting, the host mounts these media routes and APIs under {workspaceRoot}:

media is {name, kind: 'image' | 'video'}[], sorted by order; dirError being non-empty indicates the configured directory is unavailable and has fallen back to the default directory.

Use Cases and Notes¶

Suitable for: Developers who want a personalized background in the DSH workspace without manually editing theme files; people with a batch of wallpapers who want to rotate them in order or at fixed intervals; people who want to put a looping video in the background.

Pre-use notes:

• The plugin runs with the permissions of the current dsh process and will read the media directory, write thumbnail caches, and update server-side settings. It is recommended to check the source code and license (MIT) before installing to ensure it is correct;
• The plugin was developed based on dsh v0.1.2-rc.1. “Select Directory” and “Open Folder” are not available on older versions of dsh and may fail to install normally;
• The playability of video formats depends on the browser environment. Chromium will automatically skip HLS and FLV.

Conclusion¶

dsh-bg-carousel connects the replacement of the DSH interface background, mixed image/video rotation, sorting, and transparency with a media directory and a control panel. The handling of rotation progression and format compatibility is quite detailed. Once the plugin is installed and files are copied into the directory, it is ready to use.

• Community Plugin Directory (Independent site): https://www.skillhub.cn/plugins/Jonah-Wu23/dsh-bg-carousel
• GitHub Repository: https://github.com/Jonah-Wu23/dsh-bg-carousel