Making Style-Bert-VITS2 Speak in Home Assistant, a Work Log

This article was generated by feeding my work log to Gemini 3. I’ve taken care to keep it accurate, but it may contain factual errors or inappropriate wording. Thanks for your understanding.

I wanted Home Assistant’s (HA from here on) text-to-speech (TTS) to sound more human and more emotional. So I set up “Style-Bert-VITS2”, a speech synthesis engine highly regarded in the local LLM scene (Docker image: litagin02/Style-Bert-VITS2), and hooked it up to HA. This is the record of that trial and error.

The existing integration didn’t work as-is, and I ran into a wall with long texts, but in the end I wrote a dedicated custom component on the HA side, which got everything working perfectly without modifying the Docker container at all.

Target Setup#

TTS server: litagin02/Style-Bert-VITS2 (Docker)
- API endpoint: http://<YOUR_SBV2_IP>:5000/voice
Client: Home Assistant (OS/Container)
Requirements:
- Fully local operation, no internet needed.
- Recognized as a standard HA TTS (so it’s easy to use in automations).
- Reads out long texts of more than 100 characters without errors.

Problems I Hit and How I Solved Them#

1. The Existing VOICEVOX Integration Doesn’t Work#

Most Style-Bert-VITS2 implementations have a VOICEVOX-compatible API, so at first I wondered whether I could just plug it into the ha-voicevox integration available through HACS. But when I tried to connect, I got an error.

Cause: The litagin02 container I used mainly runs a simple API (/voice) meant for use from a browser. The behavior of its endpoints differs in places from the strict API spec the upstream VOICEVOX integration requires (a two-step flow: generate a query with /audio_query, then synthesize with /synthesis), or perhaps the responses just didn’t match what the integration expects.

2. The GET Request Length Limit (the 100-Character Wall)#

I gave up on the existing integration and decided to write my own custom component that hits the simple API (/voice) directly. But then a new problem showed up. A short greeting like “Hello” works fine, but as soon as I send a long text of more than 100 characters, the request fails.

Suspected cause: The simple API takes its parameters through a GET request. GET requests generally have a URL length limit, but failing at a mere 100 characters or so suggests a bottleneck somewhere, either in the server’s spec (the Style-Bert-VITS2 container) or in the encoding between Python’s requests library and the API server.
Constraint: Modifying the server code to support POST would probably fix it, but I want to run the distributed Docker image as-is (to keep maintenance costs down when updating), so I decided not to touch the server side.

Note added after the work: Specifically, it looks like the maximum request length is capped at 100 characters right here. Overriding the config might solve the 100-character problem. But apparently “BERT’s attention mechanism scales quadratically with sequence length,” so allowing overly long text might cause its own problems.

Style-Bert-VITS2/config.py at c093d558ee2fe83f99952aad6c4f9cd450d096fd · RedRayz/Style-Bert-VITS2

Style-Bert-VITS2: Bert-VITS2 with more controllable voice styles. - RedRayz/Style-Bert-VITS2

github.com

3. The Final Fix: Splitting on the Client Side#

To work around the server-side limit, I decided to implement the following logic in the HA component: “split the long text at punctuation, send the pieces as short requests one after another, and join the returned audio.”

Implementation Steps (Full Version)#

These steps install my own custom component, sbv2_simple.

Step 1: Create the Directory#

Create the following folder structure inside Home Assistant’s /config directory.

1
/config
2
  └ custom_components
3
      └ sbv2_simple

Step 2: Create the Manifest File#

Create /config/custom_components/sbv2_simple/manifest.json.

1
{
2
  "domain": "sbv2_simple",
3
  "name": "Style-Bert-VITS2 Simple",
4
  "documentation": "https://github.com/litagin02/Style-Bert-VITS2",
5
  "dependencies": [],
6
  "codeowners": [],
7
  "requirements": ["requests"],
8
  "version": "1.0.0",
9
  "iot_class": "local_push"
10
}

Step 3: Implement the Program#

Create /config/custom_components/sbv2_simple/tts.py and put the following code in it.

This code includes the following features:

Automatic splitting: Splits text at punctuation (。、！？).
Safety margin: Limits each chunk to 75 characters, safely staying under the 100-character wall.
WAV merging: Strips the headers from the received WAV binaries, concatenates the PCM data, and recalculates and attaches a correct WAV header.

1
import logging
2
import requests
3
import io
4
import struct
5
import re
6
import voluptuous as vol
7

8
from homeassistant.components.tts import Provider, PLATFORM_SCHEMA, CONF_LANG
9
from homeassistant.const import CONF_HOST, CONF_PORT
10
import homeassistant.helpers.config_validation as cv
11

12
_LOGGER = logging.getLogger(__name__)
13

14
# --- Settings ---
15
# Set the server's IP address and port (change to match your environment)
16
DEFAULT_HOST = "192.168.x.x"
17
DEFAULT_PORT = 5000
18
DEFAULT_LANG = "ja-JP"
19

20
# Maximum number of characters sent in a single request
21
# Requests fail above 100 characters, so this is set to 75 to leave a safety margin
22
MAX_CHARS_PER_REQUEST = 75
23

24
CONF_MODEL_ID = "model_id"
25
CONF_STYLE = "style"
26
CONF_SDP_RATIO = "sdp_ratio"
27
CONF_NOISE = "noise"
28
CONF_LENGTH = "length"
29

30
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
31
    vol.Optional(CONF_HOST, default=DEFAULT_HOST): cv.string,
32
    vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
33
    vol.Optional(CONF_MODEL_ID, default=0): cv.positive_int,
34
    vol.Optional(CONF_STYLE, default="Neutral"): cv.string,
35
    vol.Optional(CONF_SDP_RATIO, default=0.2): vol.Coerce(float),
36
    vol.Optional(CONF_NOISE, default=0.6): vol.Coerce(float),
37
    vol.Optional(CONF_LENGTH, default=1.0): vol.Coerce(float),
38
    vol.Optional(CONF_LANG, default=DEFAULT_LANG): cv.string,
39
})
40

41
def get_engine(hass, config, discovery_info=None):
42
    return SBV2Provider(config)
43

44
class SBV2Provider(Provider):
45
    """Style-Bert-VITS2 Provider with Long Text Support"""
46

47
    def __init__(self, config):
48
        self._host = config[CONF_HOST]
49
        self._port = config[CONF_PORT]
50
        self._model_id = config[CONF_MODEL_ID]
51
        self._style = config[CONF_STYLE]
52
        self._sdp_ratio = config[CONF_SDP_RATIO]
53
        self._noise = config[CONF_NOISE]
54
        self._length = config[CONF_LENGTH]
55
        self._lang = config[CONF_LANG]
56
        self.name = "Style-Bert-VITS2"
57

58
    @property
59
    def default_language(self):
60
        return self._lang
61

62
    @property
63
    def supported_languages(self):
64
        return [self._lang]
65

66
    def get_tts_audio(self, message, language, options=None):
67
        """Generate audio (long text support version)"""
68

69
        # 1. Split the text
70
        chunks = self._split_text(message, MAX_CHARS_PER_REQUEST)
71
        wav_parts = []
72

73
        # 2. Send a request to the server for each chunk
74
        for i, chunk in enumerate(chunks):
75
            _LOGGER.debug(f"Requesting chunk {i+1}/{len(chunks)}: {chunk}")
76
            wav_data = self._request_wav(chunk)
77
            if wav_data:
78
                wav_parts.append(wav_data)
79
            else:
80
                _LOGGER.error(f"Failed to generate audio for chunk: {chunk}")
81
                return None, None
82

83
        if not wav_parts:
84
            return None, None
85

86
        # 3. Combine the multiple WAV data into one
87
        combined_wav = self._combine_wavs(wav_parts)
88
        return "wav", combined_wav
89

90
    def _request_wav(self, text):
91
        """Internal function that sends a request to the server"""
92
        url = f"http://{self._host}:{self._port}/voice"
93
        params = {
94
            "text": text,
95
            "model_id": self._model_id,
96
            "style": self._style,
97
            "sdp_ratio": self._sdp_ratio,
98
            "noise": self._noise,
99
            "length": self._length,
100
            "language": "JP"
101
        }
102
        try:
103
            # Set the timeout to 20 seconds
104
            response = requests.get(url, params=params, timeout=20)
105
            if response.status_code == 200:
106
                return response.content
107
            return None
108
        except Exception as e:
109
            _LOGGER.error(f"Connection Error: {e}")
110
            return None
111

112
    def _split_text(self, text, max_len):
113
        """Split the text, taking punctuation into account"""
114
        parts = re.split(r'([。、！？\n]+)', text)
115
        chunks = []
116
        current_chunk = ""
117

118
        for part in parts:
119
            if len(current_chunk) + len(part) <= max_len:
120
                current_chunk += part
121
            else:
122
                if current_chunk:
123
                    chunks.append(current_chunk)
124

125
                if len(part) > max_len:
126
                    for i in range(0, len(part), max_len):
127
                        chunks.append(part[i:i+max_len])
128
                    current_chunk = ""
129
                else:
130
                    current_chunk = part
131

132
        if current_chunk:
133
            chunks.append(current_chunk)
134

135
        return [c for c in chunks if c.strip()]
136

137
    def _combine_wavs(self, wav_bytes_list):
138
        """
139
        Combine multiple WAV binaries into one
140
        (not a simple concatenation: strip the headers, join the PCM data, and recalculate the header)
141
        """
142
        if len(wav_bytes_list) == 1:
143
            return wav_bytes_list[0]
144

145
        data_chunks = []
146
        fmt_chunk = None
147

148
        for wav_bytes in wav_bytes_list:
149
            try:
150
                data_marker_index = wav_bytes.find(b'data')
151
                if data_marker_index == -1: continue
152

153
                data_size = int.from_bytes(wav_bytes[data_marker_index+4 : data_marker_index+8], 'little')
154
                raw_data = wav_bytes[data_marker_index+8 : data_marker_index+8+data_size]
155

156
                data_chunks.append(raw_data)
157

158
                if fmt_chunk is None:
159
                    fmt_chunk = wav_bytes[:data_marker_index]
160
            except Exception:
161
                continue
162

163
        if fmt_chunk is None or not data_chunks:
164
            return wav_bytes_list[0]
165

166
        combined_data = b''.join(data_chunks)
167
        total_data_len = len(combined_data)
168

169
        file_size = len(fmt_chunk) + 8 + total_data_len
170
        riff_size_bytes = (file_size - 8).to_bytes(4, 'little')
171
        new_header = fmt_chunk[:4] + riff_size_bytes + fmt_chunk[8:]
172

173
        final_wav = new_header + b'data' + total_data_len.to_bytes(4, 'little') + combined_data
174
        return final_wav

Step 4: Enable the Configuration#

Add the following to configuration.yaml. * Change the IP address to match your own environment.

1
tts:
2
  - platform: sbv2_simple
3
    host: 192.168.x.x  # The server's IP address
4
    port: 5000
5
    model_id: 0
6
    style: "Neutral"   # Change to "Happy", "Sad", etc. as needed

Step 5: Done#

Restart Home Assistant. Style-Bert-VITS2 will show up under “Settings” > “Voice assistants” > “Text-to-speech” and can be selected.

Results in Practice#

Sound quality: Very natural. It produces voices warmer than Google’s TTS and the like, locally.
Long text: Even when I had it read a news article of 300+ characters, it gets split into requests at appropriate points (at each punctuation mark), so it runs through to the end without errors.

I was able to build a robust system purely through tweaks on the HA side, without modifying the container. I hope this helps anyone struggling with a similar setup.