Troubleshooting
The first place to look is the speaker log, tmp\speaker.log on the speaker computer. It has every phrase heard, the answer and the timing. Log lines are in Russian; the English meaning is given in brackets below.
| What you see | What to check |
|---|---|
| The speaker doesn't respond at all | Is the speaker task running in Task Scheduler? Is the last log line «слушаю; скажи…» (listening; say…)? If it's «микрофон 5 с не даёт звука — выхожу» (no sound from the mic for 5 s, exiting), the task has no repeat trigger |
| «speaches недоступен — резерв» (speaches unavailable, fallback) | Are Docker Desktop and the speaches container running, does the address in settings match? The Check button in the speech card |
| The speaker mixes up words | The recognition model: faster-whisper-large-v3-turbo is much more accurate than small ones. Move the microphone closer. In an English home, check that recognition is English: Parakeet on Homer Node or whisper on your own speaches |
| The speaker doesn't react to “Homer” in an English home | Is the English Vosk model in place? Homer Node downloads it for the speaker and sets HOMER_VOSK_EN; without a node, it's tmp\speaker-models\vosk-model-small-en-us-0.15. Without it, the Russian model stays, and the log says so |
| The speaker doesn't hear you while the TV is on | Say the name and the request in one phrase, closer to the microphone. If the film plays from this computer, turn on Cancel computer audio in Speaker microphones. A TV with its own app can't be cancelled this way: with ReSpeaker, set the mode Noisy — TV, people talking. Under background noise the log says «рядом фоновая речь (телевизор?) — пока только по имени» (background speech nearby (TV?), name only for now) |
| It listens to the wrong microphone | Speaker microphones → Which microphone to use: the machine's microphones per instance, Default is the one set at install. Changes within seconds, no restart. Fallback: the input key in settings.json in the brains folder |
| Homer recognizes nobody by voice, or treats everyone as a guest | Are the models in speaker-home\voiceid? Without them the log has no «голос: …» (voice) lines. Guest restrictions apply only when at least one household voice is confirmed in Household voices; a request becomes a household voice after Confirm |
| «Голова не отвечает» (the brain isn't answering) | The Claude Code sign-in on the speaker computer: claude in a terminal under the same user. Subscription limits. If claude hung, the watchdog kills it after 60 s («голова молчит 60 с — перезапускаю», brain silent for 60 s, restarting), and the next phrase starts a new one. You still get an answer if the fallback brain works: a cloud with a key or LM Studio |
| «ответила запасная голова: LocalBrain» (fallback brain answered) in the log | The main brain didn't answer, so the local model without tools answers. Fix the main one as in the row above. If that doesn't answer either, is the LM Studio server running on :18234? |
| Smartbox in the living room is silent | Where is it connected: the line «сетевая колонка подключилась» (network speaker connected) in tmp\speaker-smartbox.log on the computer or on the GPD. Not there at all: is the homer-speaker-smartbox task running? Quiet phrases without the name (below 28 dB) are dropped on purpose |
| The speakers on the GPD stopped by themselves | Overheating: in C:\Users\mail\homer-events.log, the line «ПЕРЕГРЕВ: колонка остановлена до 65 °C» (overheat: speaker stopped until 65 °C). The homer-thermlog watchdog brings them back after cooling. Is the GPD fan on? |
| “Music didn't work: no sign-in” | Is the Yandex Station integration connected in Home Assistant, do you have Plus? |
| You can't hear the music | The default Windows output device, the volume (music_control volume) |
| “Nobody joined in 120 s” | Was the device reset, is it far from the coordinator, is the bridge alive (diag)? |
| “Still busy with the previous one” | Another Opus task is running; wait for the result or check the log |
| “Didn't finish in 15 minutes” | The log shows the step where Opus got stuck. Split the task into parts |
| The log doesn't arrive in Telegram | Is the group linked to the home (Settings → Notifications → Telegram)? |
| “Connect to Claude Code” returns an error | The speaker must run as the same user as Claude Code. Check: claude mcp get homer |
| A tool is “not allowed” | It is off at this level in Settings → Speaker → Homer brains |
Where things are
| Path | What it is |
|---|---|
tools/speaker/speaker.py | The speaker: microphone, name, recognition, brains, voice, HTTP port :8790 |
tools/speaker/agent.py | Music, timers, Opus tasks, log, connecting to Claude Code |
tools/speaker/homer_mcp.py | The homer MCP server with the tools |
tools/speaker/homer_i18n.py | The speaker's language: Russian or English, from the home language |
tools/speaker/homer_voiceid.py | Voice print: who is speaking, the album on the Homer server |
settings.json in the brains folder | The speaker's microphone (input) and output device (output) without the app |
tools/respeaker/ | ReSpeaker on the computer through WSL: the udp:8799 bridge, modes, ring |
tmp/speaker.log | Speaker log |
tmp/speaker-smartbox.log | Smartbox log, on the computer and on the GPD |
secrets/local-llm-key.txt | LM Studio token for the fallback brain |
tools/gpd/thermlog.ps1 | GPD overheat watchdog (the homer-thermlog task) |
secrets/ha-credentials.txt | Home Assistant token for the tools (token=…) |
secrets/alice-skill-key.txt | The speaker key to the Homer server: settings, log, music token |
secrets/yandex-music-token.txt | Optional own Yandex Music token |
~/.claude/skills/homer-* | Skills in Claude Code after connecting |
Brains folder (C:\Apps\HomerSpeaker) | The working folder of the speaker's and tasks' claude, files mcp-voice.json and opus/mcp-opus.json |