speechSynthesis.speak() Not Working on iOS Safari When Triggered Programmatically

[Arham-12336]

Bug Description
I'm building a voice-enabled chatbot using Easy Speech for text-to-speech functionality. While it works correctly on Windows and Android devices, the speech output fails on iOS devices. After investigation, I discovered that Safari on iOS blocks autoplay of speech unless it is initiated through a user interaction. This behavior prevents Easy Speech from functioning as expected.

Steps to Reproduce

1. Import and initialize Easy Speech.
2. Attempt to trigger speech output from a text input (e.g., after an API response or in useEffect) without a direct user action.

Expected Behavior
Speech should play automatically without requiring explicit user interaction, consistent with behavior on Windows and Android browsers.

Device Information

• Devices: iPhone, iPad
• Browser: Safari, Chrome

[jankapunkt]

Hi @Arham-12336 thank you for reporting. How do you propose this should be solved on the side of easy speech?

From what I see the interaction requirement is deep implemented on the OS side, which is why I personally don't see a valid solution that does not involve user interactions. However, I'm not super deep into iOS and maybe you see an approach I currently don't see.

[Arham-12336]

The issue I'm encountering is that I receive a response string from a language model (LLM) and pass it to the speak method. However, the speech doesn't play, and no error is thrown. Interestingly, when the same speak call is triggered within a user interaction (e.g., onClick or similar event), it works as expected.

[jankapunkt]

This is indeed a problem and I wonder whether the iOS devs have ever thought about such use cases...

[Arham-12336]

The issue on iOS devices is likely due to WebKit's autoplay restrictions on speech synthesis. Safari blocks speechSynthesis.speak() when it's not triggered by a direct user interaction, such as a button click. If invoked from an asynchronous source like an API response — especially within a useEffect — it fails because there's no associated user gesture.

Workaround:
To bypass this restriction, initiate a minimal call to speechSynthesis.speak() during an actual user interaction (e.g., clicking a button or sending the first message). Use a dummy utterance like this:

await EasySpeech.speak({
  text: " ",     // whitespace
  volume: 0,     // muted
  rate: 10       // very fast
});

This creates a "trusted session" in Safari. Once this is done:

Subsequent calls to .speak() will work programmatically, even without user interaction.

[jankapunkt]

Hey @Arham-12336 this is awesome you found out a workaround I will add this to the wiki troubleshooting section

[jankapunkt]

@Arham-12336 would you mind doing a quick review on this one?

#368