====== SAPI.SpVoice ======

As documented on [[https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ms723602(v=vs.85)|MSDN]].

The SAPI.SpVoice object (referred to as "SpVoice ") can be used to convert text to speech, either for immediate playback, or as a media file. SpVoice can use any system text-to-speech voices installed from language packs (although it requires some tweaking on modern windows). 

===== Basic Usage =====

<code autohotkey>
SpVoice := ComObjCreate("SAPI.SpVoice") ; Note: You can save this object, you shouldn't create a new one each time you want to use it
SpVoice.Volume := 100
SpVoice.Speak("Hello world!")
</code>

==== Note ==== 

By default, ''SpVoice.Speak()'' expects XML formatted text, with extra commands for the text-to-speech engine embedded. This means that you need to pass it valid XML and that it will throw an exception when you pass invalid XML, which probably isn't what you want. To disable this (or enable other behavior), the ''Flags'' second parameter of ''SpVoice.Speak()'' can be any of the following values bitwise-OR'd together (''|'' operator):

^ Flag Name ^ Flag Value ^ Meaning ^
| ''SVSFlagsAsync'' | ''1'' | Return instantly, don't wait to finish speaking |
| ''SVSFPurgeBeforeSpeak'' | ''2'' | Cancel any previous speaking that might still be going |
| ''SVSFIsFilename'' | ''4'' | The "text" to speak is actually the name of a file whose contents should be spoken |
| ''SVSFIsXML'' | ''8'' | The "text" to speak is XML, and contains extra commands for the text-to-speech engine |
| ''SVSFPersistXML'' | ''16'' | Any XML commands in the text which modify state will persist through all following ''SpVoice.Speak()'' calls |

===== Examples =====

==== List all available voices ====

<code autohotkey>
SpVoice := ComObjCreate("SAPI.SpVoice")

Voices := SpVoice.GetVoices()
VoicesText := ""

loop, % Voices.Count() {
	VoicesText .= Voices.Item(A_Index - 1).GetDescription() "`n"
}

MsgBox, % VoicesText
</code>

==== Speak using a different voice ====

<code autohotkey>
SpVoice := ComObjCreate("SAPI.SpVoice")

Voice := ... ; Either loop over SpVoice.GetVoices() to pick a voice, or use an index into that list

SpVoice.Voice := Voice

MsgBox, % VoicesText
</code>

===== Using all installed voices on modern windows =====

In newer windows versions after installing language packs the voices might not be available through this COM object. However, you can use the following trick to "enable" them.

Simply copy the registry keys for each new voice from ''HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Speech_OneCore\Voices\Tokens'' to ''HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Speech\Voices\Tokens'' (for 64 bit applications), and to ''HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\SPEECH\Voices\Tokens'' (for 32 bit applications).