Skip to content
Homelab Infrastructure

Assist Recorder

Overview

Section titled “Overview”

Assist Recorder is a Python-based proxy that sits between Home Assistant’s Wyoming STT client and the Faster-Whisper STT server. It intercepts audio data flowing through the voice pipeline, normalizes it, and saves recordings to a public HTTP-accessible directory for debugging transcription quality.

The service is defined in modules/nixos/services/assist-recorder.nix and the proxy script in modules/nixos/services/assist-recorder.py.

Architecture

Section titled “Architecture”
graph LR
    HA[Home Assistant] -->|Wyoming STT| REC[Assist Recorder :10301]
    REC -->|forward STT| WHIS[Faster-Whisper :10300]
    REC -->|save audio| DISK[/var/lib/assist-recorder/public/]
    DISK -->|HTTP| WEB[http://assist-home.javiersc.com/audio/]

The recorder listens on port 10301, forwards audio to Faster-Whisper on port 10300, and simultaneously writes .wav files and metadata (json) to its public directory.

Ports

Section titled “Ports”
ServicePortProtocolDescription
Wyoming proxy10301TCPIntercepted STT endpoint
Public HTTP10302HTTPServes recorded audio and metadata

External Access

Section titled “External Access”
Access MethodURL
Local networkhttp://<homelab.ip>:10302
Cloudflare Tunnelhttps://assist-home.javiersc.com

Recording Format

Section titled “Recording Format”

Recordings are stored in /var/lib/assist-recorder/public/ with two subdirectories:

  • audio/ — .wav files with normalized audio data.
  • meta/ — .json files with session metadata including timing metrics (start/end timestamps, duration, audio normalization factors).

[!NOTE] Recordings are ephemeral and intentionally excluded from Restic backups. They are debug artifacts, not persistent state.

Audio Data Handling

Section titled “Audio Data Handling”

The proxy performs audio normalization on incoming data before forwarding to Whisper. This ensures consistent volume levels across different microphone inputs and prevents clipping or under-amplification. Timing metrics are logged per session to help evaluate STT latency.

Troubleshooting

Section titled “Troubleshooting”

Checking Logs

Section titled “Checking Logs”
Terminal window
sudo journalctl -u assist-recorder -f

Viewing Recordings

Section titled “Viewing Recordings”

Browse to https://assist-home.javiersc.com/audio/ to list and download recent recordings. Metadata files are at https://assist-home.javiersc.com/meta/.

Restarting the service

Section titled “Restarting the service”
Terminal window
sudo systemctl restart assist-recorder