# Wallpaper Companion — FAQ and Troubleshooting

> 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.


Documentation baseline: v0.8.1. Diagnose in this order: audio playback → active profile → trigger conditions.

## 1. No voice after pressing F8 or clicking

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

*Figure 1 · 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.



Try Random voice preview (随机试听语音). If silent, check files, folder bindings, Windows output, and volume. If preview works, check the playing profile, enabled/saved rule, desktop foreground, pause/fullscreen state, time window, filters, and both cooldowns. Inspect the runtime log.

## 2. Voice works but BGM does not

![Figure 2 · Resource page, scrolled down: BGM conflict prevention](images/03-audio-policy.png)

*Figure 2 · Resource page, scrolled down: BGM conflict prevention*

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

| Location in the screenshot | What to do |
|---|---|
| Right scrollbar | Scroll to 原壁纸声音与防冲突. |
| 防冲突策略 | The default policy can pause music when wallpaper audio is present or unknown. |
| 手动覆盖检测 | Override only after you have verified that the wallpaper is silent or muted. |
| 保存配置 and bottom player | Save and distinguish a music-only pause from pausing all Companion audio. |

> Success check: identify whether silence comes from a pause, audio policy, folder, or volume.



Check folder BGM enablement, volume, manual pause, conflict prevention, and folder contents. The default policy can pause BGM when wallpaper audio is detected or unknown. If you already muted the wallpaper, set the manual override and save.

## 3. Imported dialogue does not speak

JSON/TXT dialogue contains text. Generate WAV through a configured TTS service or import your own audio. Importing text does not call a service automatically.

## 4. Generated WAV is not found by a rule

Check the actual output against the bound voice directory. Category generation uses subfolders. Filename filters may exclude it. Editing dialogue does not automatically rename or regenerate old audio.

## 5. Fixed-time or random rules do not fire

Fixed-time rules need the app running and eligible during that minute; missed minutes are not replayed. Random rules wait an initial random interval. Check the local clock, time window, pauses, and cooldowns. Overnight windows such as `22:00–06:00` are supported.

## 6. Wallpaper detection is wrong or delayed

Check the WE installation directory, Workshop folder, followed monitor (numbered from 0), and manual profile mode. WE may save its selection with a delay. Try Detect now, or use manual mode temporarily.

## 7. Pause BGM versus Pause Companion

Pause BGM affects music only. Pause Companion affects Companion voice triggers and BGM, not Wallpaper Engine.

## 8. Editing one wallpaper changes another's dialogue

They may share `dialogues.json`. Choose dedicated dialogue resources for the intended profile. Changing the shared root does not migrate existing bindings/files.

## 9. Deleting a profile does not delete its audio

This preserves resources for reuse and shared profiles. Audio-library Move to Recycle Bin operates on real files; check shared usage first.

## 10. Cloud connection check passes but generation fails

The check validates address format, not working authentication. Verify endpoint, credentials, quota, supported model/voice, and WAV response format. Compatible TTS needs a complete `/audio/speech` endpoint; remote endpoints require HTTPS. Test a short line.

## 11. GPT-SoVITS fails to start or synthesize

Check the directory containing `api_v2.py`, Python environment, compatible `.ckpt`/`.pth`, versions, reference audio/exact transcript, languages, port, and GPU memory. Read `sovits-api.log` in the data folder. Scanned candidates are not compatibility guarantees.

## 12. What belongs in the reference transcript?

The exact words spoken in the reference clip, not the new text you want generated. Model, reference clip, transcript, and languages must be appropriate together.

## 13. Will Companion stop an external GPT-SoVITS API?

It stops its own managed API on exit, not an externally started service. Permitted model switching on an external API changes global state. Avoid disrupting other clients; use an independent port when possible.

## 14. It still runs after closing / does startup load AI?

Closing usually leaves it in the tray. Use tray Exit to quit. Login startup defaults to off and does not preload GPT-SoVITS. Actual generation starts it when needed.

## 15. What should I back up before updating?

Installed configuration: `%LOCALAPPDATA%\WallpaperCompanion`. Portable configuration: adjacent `data`. Also preserve installation-directory `shared`, custom external audio/dialogue folders, and personal plugins. Save and quit from the tray first. Interaction JSON omits audio and keys.

## 16. Offline use / changes to WE

Existing local audio and rules can work offline. Cloud TTS and downloads need network access. Companion runs independently without modifying WE or downloaded wallpapers.

## 17. Why is there no EXE in the source archive?

Choose `*-setup.exe` or `*-portable.zip` in Release Assets. The automatic Source code archives require a development environment.

## 18. How do I report a problem?

![Figure 3 · Runtime log: locate the failing stage](images/11-runtime-log.png)

*Figure 3 · Runtime log: locate the failing stage*

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

| Location in the screenshot | What to do |
|---|---|
| Left 运行记录 | Inspect actual trigger, selection, generation, or error messages. |
| Right text area | The screenshot is clearly marked as tutorial text, not successful live execution. |
| When reporting an issue | Include relevant real messages, version, steps, and preview results; redact private data. |

> Success check: distinguish no trigger, no matching audio, and playback failure.



Open https://github.com/Abs0lutely/wallpaper-companion/issues . Include app/Windows versions, installer or portable edition, reproduction steps, runtime messages, and preview results. Redact keys and private information. See `Wallpaper-Companion-Manual-en.md` for the full workflow.