Text-to-speech not working on your site: the causes, in order
The player is missing, the audio won't start, or the output is wrong. Three unrelated faults, eleven likely causes, and the order to rule them out in without losing an afternoon.
"Text-to-speech isn't working" covers three faults with nothing in common, and that is the first reason people lose time on it. Before investigating, decide which one you have.
The player does not appear at all on the page. The player appears but the audio will not start. The audio starts but the output is wrong, mispronunciation, truncated text, unexpected voice.
Three separate investigations. Here they are, in the order the causes actually turn up.
Case 1, The player does not appear
The article has no audio yet. The most common cause and the least suspected. Most implementations only render the player once a file exists, which is the correct behaviour, an empty player is worse than no player. Check in your admin that the article is among the processed content. If it was just published, generation may still be running.
The article is not being matched. The player has to associate the page with its audio file, usually by the article's canonical URL. If that URL differs between generation time and display time (http to https, www added or dropped, tracking parameters appended, a staging environment answering on another domain) the match fails silently. This is by far the most common reason a player is missing on staging while everything works in production.
The script is blocked. Open your browser console. A blocking extension, a restrictive Content-Security-Policy, or an aggressive cache can stop it loading. The console will say so explicitly, in one line.
The template does not contain the slot. If the player was added through a theme or plugin, check that the template used by this content type actually includes the call. Sites usually have several article templates and only one got edited.
Case 2, The player appears but nothing plays
The file is protected. If your articles are restricted to registered users or subscribers, the audio file is too, and it is only served through a signed, time-limited link. An expired link, or a signed-out visitor, produces exactly this symptom. Reload while signed in to an account with the right entitlement.
The browser is refusing autoplay. No browser will start sound without a user gesture. If you are testing a playback that fires automatically, that is not a fault, that is the rule.
The format is not supported. Rare now, but real on older browsers and on some in-app browsers. Try the same page in a different browser: if it works elsewhere, you have your answer.
The server does not handle partial requests. Audio is fetched in chunks. Hosting that does not honour Range requests leaves the player stuck at the first byte. The classic symptom is a progress bar that stays at zero with no error message.
Case 3, The audio plays but the output is wrong
Proper nouns are mispronounced. This is not a defect in the voice and it is not fixed by switching voices. It is fixed with a pronunciation lexicon: a list of words and their intended pronunciation, applied at every generation. Once an entry is added it holds for all your articles, past and future.
The text read out does not match the article. A sign that content extraction picked the wrong part of the page: a repeated standfirst, an ad block, an image caption, or conversely an article cut off halfway. That is an extraction setting, not a voice problem.
The audio is from an earlier version. You edited the article but the file predates the edit. Depending on configuration, regeneration on update is either automatic or manual. Find out which, then re-run it.
The voice is not the one you expected. A per-section voice rule, a user-level setting, or a voice withdrawn from the catalogue and replaced by a fallback. Check the section-level setting before the account-level one: it is almost always there.
The method, if you do not know where to start
Three checks rule out half the cases in two minutes.
First, compare an article that works with the one that does not: the difference between them is your cause. Then open the browser console, which names the fault whenever it is technical. Finally, open the audio file's own URL directly in a tab: if it plays there but not in the page, the problem is in the page; if it does not play there either, the problem is upstream.
On our side
WeDispatch runs a continuous health check and publishes the result, so that "is it you or is it me?" is settled at a glance rather than by opening a ticket. The player is rendered server-side on your own domain, which rules out third-party iframe faults from the start, and targeted correction lets you redo one passage without regenerating the whole article.
If you are still at the selection stage, how to evaluate a neural voice covers the criteria that prevent a good share of these problems upstream. And you can try it on one of your own articles with nothing to install.
Give your articles a voice with WeDispatch
This blog is itself voiced by WeDispatch. Curious how it sounds on your content?
Book a demo