# Wallpaper Companion — Quick Start

> Illustrated edition: real application widgets with isolated demo data. All screenshots show the Chinese app. Displayed paths and rule values are examples; no live wallpaper, personal settings, speech API, or payment was used. Keep the `images` folder beside this Markdown file when viewing or exporting to PDF. Download the illustrated ZIP to obtain all files.


Baseline: v0.8.1, Windows 10/11 x64. English control descriptions correspond to the current Chinese app labels.

Goal: press F8 on the desktop to play one existing voice clip. No AI model, Python, or TTS service is required for this path.

## 1. Install

1. Open https://github.com/Abs0lutely/wallpaper-companion/releases/latest .
2. Download `*-setup.exe`, or fully extract `*-portable.zip`.
3. Keep `_internal` and `portable.flag` for the portable edition; run `WallpaperCompanion.exe`.
4. GitHub's Source code ZIP is not the packaged application.

## 2. Bind a wallpaper

![Figure 1 · Home: choose a profile before testing playback](images/01-home.png)

*Figure 1 · Home: choose a profile before testing playback*

**Look at the picture, then follow these controls**

| Location in the screenshot | What to do |
|---|---|
| Left profile list | Choose the intended profile; use 配置管理 → 新建配置 for an unbound test profile. |
| Center 正在编辑 selector | Verify the editing profile; it is not necessarily the playing profile. |
| 声音设置 tab | Adjust voice/music levels and cooldowns. |
| Bottom 随机试听语音 and 保存配置 | Save and preview first, then return to the desktop for automatic input triggers. |

> Success check: you can identify the profile, preview button, and save button.



1. Apply a wallpaper in Wallpaper Engine.
2. In Companion, choose Detect now (立即检测), then Bind current wallpaper (绑定当前壁纸).
3. Verify the name/path, enable the profile, and save.
4. If detection is unavailable, create an unbound profile and use manual mode to test.

## 3. Supply real audio

![Figure 2 · Resources: bind the folder that actually contains audio](images/02-resources.png)

*Figure 2 · Resources: bind the folder that actually contains audio*

**Look at the picture, then follow these controls**

| Location in the screenshot | What to do |
|---|---|
| 资源与绑定 tab | Open from Home. |
| 语音文件夹 and 浏览… | Choose a directory containing real WAV/MP3 clips. |
| BGM 文件夹 and 浏览… | Choose a music folder, or leave it empty if unused. |
| 资源根目录 / 共用台词文件 | Check shared paths. D:/WallpaperCompanion is an example, not a required location. |
| Bottom-right 保存配置 | Save, then use the bottom-left voice preview. |

> Success check: a real clip plays, rather than merely a path being entered.



1. Prepare a playable WAV or MP3.
2. Put it in adjacent `shared/voice`, or select its folder in Resources and bindings (资源与绑定).
3. Save and use Random voice preview (随机试听语音).
4. If preview is silent, resolve the file, path, output device, or volume before creating complex rules.

```text
shared/
  voice/
    hello.wav
  bgm/
    music.mp3
```

## 4. Make an F8 rule

![Figure 3 · Complete F8 keyboard-rule example](images/05-rule-keyboard.png)

*Figure 3 · Complete F8 keyboard-rule example*

**Look at the picture, then follow these controls**

| Location in the screenshot | What to do |
|---|---|
| ① 触发分类 | Select 按事件触发 (event). |
| 事件分类 / 键盘方式 | Choose keyboard and a specific key/combination. |
| 录制按键 beside 绑定按键 | Record F8; the screenshot shows the finished binding. |
| ② 播放什么 | Start with random playback from the voice root, with no filename filter. |
| 更多设置 → 规则冷却 | The shown 5 seconds is a test example; the global cooldown also applies. |
| Bottom-right 保存规则 | Then save the profile/rules and test F8 on the desktop. |

> Success check: F8 plays one clip on the desktop; wait for both cooldowns before retrying.



1. Open Interaction rules (互动规则) and add an enabled test rule.
2. Select event → keyboard → specific key/combination.
3. Record F8.
4. Select random playback from the voice root; leave keyword filtering empty.
5. Set suitable cooldowns and save both the rule and profile.
6. Return to the desktop, ensure Companion is not paused, and press F8.

## 5. Add more

- Music: bind a BGM folder, enable folder BGM, save, and check manual/conflict pauses.
- Fixed greeting: create a daily time rule a few minutes ahead for testing. The app must be running during that minute.
- Random greeting: set a time window and min/max intervals; wait for the initial interval.
- Dialogue text: importing text does not produce sound; generate or import audio first.

## Completion checklist

- [ ] Random voice preview works.
- [ ] The intended profile is currently playing.
- [ ] The rule and profile are saved.
- [ ] F8 plays a clip after returning to the desktop.
- [ ] Both cooldowns have passed before retrying.
- [ ] You know that closing the window leaves the app in the tray; use tray Exit to quit.

See `Wallpaper-Companion-Manual-en.md` for details and `FAQ-en.md` for troubleshooting.