Difference between revisions of "Manual:Text to Speech Functions"

From Mudlet
Jump to navigation Jump to search
(Initial commit)
 
 
(39 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{TOC right}}
+
{{TOC right}}  
−
These functions are used to create audible sound from written words. The feature is available since Mudlet version 3.13. Check out our [[Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.
+
{{#description2:Mudlet API documentation for functions which can make Mudlet talk for you (audible sound from written words).}}
 +
= Text to Speech Functions =
  
−
A few new events have been added for this functionality as well:
+
These functions can make Mudlet talk for you (audible sound from written words). Check out the [[Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.
 +
 
 +
{{MudletVersion|3.17}}
 +
 
 +
Several [[Manual:Event_Engine|Mudlet events]] are available functionality as well:
 
* ttsSpeechStarted
 
* ttsSpeechStarted
 
* ttsSpeechReady
 
* ttsSpeechReady
Line 8: Line 13:
 
* ttsSpeechPaused
 
* ttsSpeechPaused
 
* ttsSpeechError
 
* ttsSpeechError
−
 
+
* ttsPitchChanged
 +
* ttsRateChanged
 +
* ttsVoiceChanged
 +
* ttsVolumeChanged
  
 
==ttsClearQueue==
 
==ttsClearQueue==
 
;ttsClearQueue([index])
 
;ttsClearQueue([index])
 
: This function will help, if you have already queued a few lines of text to speak, and now want to remove some or all of them.
 
: This function will help, if you have already queued a few lines of text to speak, and now want to remove some or all of them.
−
: Returns false, if an invalid index is given.  
+
: Returns false if an invalid index is given.  
  
−
See also:  
+
: See also: [[#ttsGetQueue|ttsGetQueue]], [[#ttsQueue|ttsQueue]]
−
[[Manual:Text to Speech Functions#ttsGetSpeechQueue|ttsGetSpeechQueue]]
 
  
 
;Parameters
 
;Parameters
Line 22: Line 29:
 
: (optional) number. The text at this index position of the queue will be removed. If no number is given, the whole queue is cleared.
 
: (optional) number. The text at this index position of the queue will be removed. If no number is given, the whole queue is cleared.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsQueueSpeech("One")
+
-- queue five words and then remove some, "one, two, four" will be actually said
−
ttsQueueSpeech("Two")
+
ttsQueue("One")
−
ttsQueueSpeech("Three")
+
ttsQueue("Two")
−
ttsQueueSpeech("Four")
+
ttsQueue("Three")
−
ttsQueueSpeech("Five")
+
ttsQueue("Four")
 +
ttsQueue("Five")
 
ttsClearQueue(2)
 
ttsClearQueue(2)
 
ttsClearQueue(3)
 
ttsClearQueue(3)
 +
 +
-- clear the whole queue entirely
 +
ttsClearQueue()
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
  
 
==ttsGetCurrentLine==
 
==ttsGetCurrentLine==
Line 42: Line 52:
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsSpeak|ttsSpeak]],  
+
[[#ttsSpeak|ttsSpeak]],  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
ttsQueue("One")
 +
ttsQueue("Two")
 +
ttsQueue("Three")
 +
ttsQueue("Four")
 +
ttsQueue("Five")
 +
 +
-- print the line currently spoken 1s and 3s after which will be "two" and "five"
 +
tempTimer(1, function()
 +
  echo("Speaking: ".. ttsGetCurrentLine().."\n")
 +
end)
 +
 +
tempTimer(3, function()
 +
  echo("Speaking: ".. ttsGetCurrentLine().."\n")
 +
end)
 +
</syntaxhighlight>
  
 
==ttsGetCurrentVoice==
 
==ttsGetCurrentVoice==
Line 54: Line 81:
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsGetVoices|ttsGetVoices]]
+
[[#ttsGetVoices|ttsGetVoices]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsGetCurrentVoice()
 
 
-- for example returns "Microsoft Zira Desktop" on Windows (US locale)
 
-- for example returns "Microsoft Zira Desktop" on Windows (US locale)
 +
display(ttsGetCurrentVoice())
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==ttsGetPitch==
 +
;ttsGetPitch()
 +
: If you want to analyse the pitch or tone of your current speech.
 +
: Returns the current pitch as a number between 1 (high) and -1 (deep).
 +
 +
See also:
 +
[[#ttsSetPitch|ttsSetPitch]]
 +
 +
{{MudletVersion|3.17}}
 +
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
local pitch = ttsGetPitch()
 +
echo(pitch)
 +
</syntaxhighlight>
  
−
==ttsGetSpeechQueue==
+
==ttsGetQueue==
−
;ttsGetSpeechQueue([index])
+
;ttsGetQueue([index])
 
: This function can be used to show your current queue of texts, or any single text thereof.
 
: This function can be used to show your current queue of texts, or any single text thereof.
 
: Returns a single text or a table of texts, or false. See index parameter for details.
 
: Returns a single text or a table of texts, or false. See index parameter for details.
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
 
;Parameters
 
;Parameters
Line 77: Line 119:
 
: (optional) number. The text at this index position of the queue will be returned. If no index is given, the whole queue will be returned. If the given index does not exist, the function returns false.
 
: (optional) number. The text at this index position of the queue will be returned. If no index is given, the whole queue will be returned. If the given index does not exist, the function returns false.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsQueueSpeech("We begin with some text")
+
ttsQueue("We begin with some text")
−
ttsQueueSpeech("And we continue it without interruption")
+
ttsQueue("And we continue it without interruption")
−
display(ttsGetSpeechQueue())
+
display(ttsGetQueue())
−
-- will show the queued texts as follows:
+
-- will show the queued texts as follows
 +
-- (first line ignored because it's being spoken and is not in queue):
 
-- {
 
-- {
−
--  "And we continue it without interruption",
+
--  "And we continue it without interruption"
−
--  "We begin with some text"
 
 
-- }
 
-- }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==ttsGetRate==
 +
;ttsGetRate()
 +
: If you want to analyse the rate or speed of your current speech.
 +
: Returns the current rate as a number between 1 (fast) and -1 (slow).
 +
 +
See also:
 +
[[#ttsSetRate|ttsSetRate]]
 +
 +
{{MudletVersion|3.17}}
 +
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
local rate = ttsGetRate()
 +
echo(rate)
 +
</syntaxhighlight>
  
 
==ttsGetState==
 
==ttsGetState==
−
;ttsGetSpeechState()
+
;ttsGetState()
 
: With this function you can find the current state of the speech engine.
 
: With this function you can find the current state of the speech engine.
 
: Returns one of: ttsSpeechReady, ttsSpeechPaused, ttsSpeechStarted, ttsSpeechError, ttsUnknownState.  
 
: Returns one of: ttsSpeechReady, ttsSpeechPaused, ttsSpeechStarted, ttsSpeechError, ttsUnknownState.  
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsSpeak|ttsSpeak]],  
+
[[#ttsSpeak|ttsSpeak]],  
−
[[Manual:Text to Speech Functions#ttsPauseSpeech|ttsPauseSpeech]],  
+
[[#ttsPause|ttsPause]],  
−
[[Manual:Text to Speech Functions#ttsResumeSpeech|ttsResumeSpeech]],  
+
[[#ttsResume|ttsResume]],  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsSpeak("This is just a test!")
+
ttsQueue("We begin with some text")
−
display(ttsGetState())
+
ttsQueue("And we continue it without interruption")
 +
echo(ttsGetState())
 
-- ttsSpeechStarted
 
-- ttsSpeechStarted
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
  
 
==ttsGetVoices==
 
==ttsGetVoices==
Line 119: Line 176:
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsGetCurrentVoice|ttsGetCurrentVoice]],  
+
[[#ttsGetCurrentVoice|ttsGetCurrentVoice]],  
−
[[Manual:Text to Speech Functions#ttsSetVoiceByName|ttsSetVoiceByName]],  
+
[[#ttsSetVoiceByName|ttsSetVoiceByName]],  
−
[[Manual:Text to Speech Functions#ttsSetVoiceByIndex|ttsSetVoiceByIndex]]
+
[[#ttsSetVoiceByIndex|ttsSetVoiceByIndex]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
Line 134: Line 191:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==ttsGetVolume==
 +
;ttsGetVolume()
 +
: If you want to analyse the volume of your current speech.
 +
: Returns the current volume as a number between 1 (loud) and 0 (quiet).
 +
 +
See also:
 +
[[#ttsSetVolume|ttsSetVolume]]
 +
 +
{{MudletVersion|3.17}}
 +
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
local volume = ttsGetVolume()
 +
echo(volume)
 +
</syntaxhighlight>
  
−
==ttsPauseSpeech==
+
==ttsPause==
−
;ttsPauseSpeech()
+
;ttsPause()
−
: Pauses the speech which is currently spoken, if any.
+
: Pauses the speech which is currently spoken, if any. Engines on different OS's (Windows/macOS/Linux) behave differently - pause may not work at all, it may take several seconds before it takes effect, or it may pause instantly. Some engines will look for a break that they can later resume from, such as a sentence end.
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsResumeSpeech|ttsResumeSpeech]],  
+
[[#ttsResume|ttsResume]],  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
-- set some text to be spoken, pause it 2s later, and unpause 4s later
 +
ttsSpeak("Sir David Frederick Attenborough is an English broadcaster and naturalist. He is best known for writing and presenting, in conjunction with the BBC Natural History Unit, the nine natural history documentary series that form the Life collection, which form a comprehensive survey of animal and plant life on Earth. Source: Wikipedia")
 +
tempTimer(2, function() ttsPause() end)
  
−
==ttsQueueSpeech==
+
tempTimer(2, function() ttsResume() end)
−
;ttsQueueSpeech(text to queue, [index])
+
</syntaxhighlight>
 +
 
 +
==ttsQueue==
 +
;ttsQueue(text to queue, [index])
 
: This function will add the given text to your speech queue. Text from the queue will be spoken one after the other. This is opposed to ttsSpeak which will interrupt any spoken text immediately. The queue can be reviewed and modified, while their content has not been spoken.
 
: This function will add the given text to your speech queue. Text from the queue will be spoken one after the other. This is opposed to ttsSpeak which will interrupt any spoken text immediately. The queue can be reviewed and modified, while their content has not been spoken.
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsGetSpeechQueue|ttsGetSpeechQueue]],  
+
[[#ttsGetQueue|ttsGetQueue]],  
−
[[Manual:Text to Speech Functions#ttsPauseSpeech|ttsPauseSpeech]],  
+
[[#ttsPause|ttsPause]],  
−
[[Manual:Text to Speech Functions#ttsResumeSpeech|ttsResumeSpeech]],  
+
[[#ttsResume|ttsResume]],  
−
[[Manual:Text to Speech Functions#ttsClearQueue|ttsClearQueue]],  
+
[[#ttsClearQueue|ttsClearQueue]],  
−
[[Manual:Text to Speech Functions#ttsGetState|ttsGetState]],  
+
[[#ttsGetState|ttsGetState]],  
−
[[Manual:Text to Speech Functions#ttsSpeak|ttsSpeak]]
+
[[#ttsSpeak|ttsSpeak]]
  
 
;Parameters
 
;Parameters
Line 164: Line 244:
 
: (optional) number. The text will be inserted to the queue at this index position. If no index is provided, the text will be added to the end of the queue.
 
: (optional) number. The text will be inserted to the queue at this index position. If no index is provided, the text will be added to the end of the queue.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsQueueSpeech("We begin with some text")
+
ttsQueue("We begin with some text")
−
ttsQueueSpeech("And we continue it without interruption", 1)
+
ttsQueue("And we continue it without interruption")
−
display(ttsGetSpeechQueue())
+
display(ttsGetQueue())
−
-- The texts have changed order, the second will be spoken first.
+
-- will show the queued texts as follows
−
-- The queue shows as follows:
+
-- (first line ignored because it's being spoken and is not in queue):
 
-- {
 
-- {
−
-- "And we continue it without interruption",
+
--   "And we continue it without interruption"
−
--  "We begin with some text"
 
 
-- }
 
-- }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
==ttsResume==
−
==ttsResumeSpeech==
+
;ttsResume()
−
;ttsResumeSpeech()
 
 
: Resumes the speech which was previously spoken, if any has been paused.
 
: Resumes the speech which was previously spoken, if any has been paused.
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsPauseSpeech|ttsPauseSpeech]],  
+
[[#ttsPause|ttsPause]],  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
-- set some text to be spoken, pause it 2s later, and unpause 4s later
 +
ttsSpeak("Sir David Frederick Attenborough is an English broadcaster and naturalist. He is best known for writing and presenting, in conjunction with the BBC Natural History Unit, the nine natural history documentary series that form the Life collection, which form a comprehensive survey of animal and plant life on Earth. Source: Wikipedia")
 +
tempTimer(2, function() ttsPause() end)
 +
 +
tempTimer(4, function() ttsResume() end)
 +
</syntaxhighlight>
  
 
==ttsSpeak==
 
==ttsSpeak==
 
;ttsSpeak(text to speak)
 
;ttsSpeak(text to speak)
−
: This will speak the given text immediately with the currently selected voice. Any previously spoken text can and will be interrupted. Alternatively, use the speech queue.
+
: This will speak the given text immediately with the currently selected voice. Any currently spoken text will be interrupted (use the speech queue to queue a voice instead).
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
 
;Parameters
 
;Parameters
Line 202: Line 288:
 
: Any written text which you would like to hear spoken to you. You can write literal text, or put in string variables, maybe taken from triggers or aliases, etc.
 
: Any written text which you would like to hear spoken to you. You can write literal text, or put in string variables, maybe taken from triggers or aliases, etc.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
ttsSpeak("Hello World!")
 
ttsSpeak("Hello World!")
 +
 +
-- if 'target' is your target variable, you can also do this:
 +
ttsSpeak("Hello "..target)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
==ttsSetPitch==
−
==ttsSetSpeechPitch==
+
;ttsSetPitch(pitch)
−
;ttsSetSpeechPitch(pitch)
+
: Sets the pitch or tone of speech playback.
−
: Sets the pitch of speech playback.
 
  
 
;Parameters
 
;Parameters
Line 218: Line 306:
 
: Number. Should be between 1 and -1, will be limited otherwise.
 
: Number. Should be between 1 and -1, will be limited otherwise.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsSetSpeechPitch(-1)
+
-- talk deeply first, after 2 seconds talk highly, after 4 seconds normally again
−
ttsQueueSpeech("Deep voice")
+
ttsSetPitch(-1)
−
ttsSetSpeechPitch(1)
+
ttsQueue("Deep voice")
−
ttsQueueSpeech("High voice")
+
 
−
ttsSetSpeechPitch(0)
+
tempTimer(2, function()
−
ttsQueueSpeech("Normal voice")
+
  ttsSetPitch(1)
 +
  ttsQueue("High voice")
 +
end)
 +
 
 +
tempTimer(4, function()
 +
  ttsSetPitch(0)
 +
  ttsQueue("Normal voice")
 +
end)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
==ttsSetRate==
−
==ttsSetSpeechRate==
+
;ttsSetRate(rate)
−
;ttsSetSpeechRate(rate)
+
: Sets the rate or speed of speech playback. On macOS and Windows, adjusting the system rate adjusts this value automatically.
−
: Sets the rate of speech playback.
 
  
 
;Parameters
 
;Parameters
Line 239: Line 333:
 
: Number. Should be between 1 and -1, will be limited otherwise.
 
: Number. Should be between 1 and -1, will be limited otherwise.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
tempTimer(1, function ()
+
-- talk slowly first, after 2 seconds talk quickly, after 4 seconds normally again
−
ttsSetSpeechRate(-1)
+
ttsSetRate(-1)
−
ttsQueueSpeech("Slow voice")
+
ttsQueue("Slow voice")
−
end)
+
 
 
tempTimer(2, function ()
 
tempTimer(2, function ()
−
ttsSetSpeechRate(1)
+
  ttsSetRate(1)
−
ttsQueueSpeech("Quick voice")
+
  ttsQueue("Quick voice")
 
end)
 
end)
−
tempTimer(3, function ()
+
 
−
ttsSetSpeechRate(0)
+
tempTimer(4, function ()
−
ttsQueueSpeech("Normal voice")
+
  ttsSetRate(0)
 +
ttsQueue("Normal voice")
 
end)
 
end)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
==ttsSetVolume==
−
==ttsSetSpeechVolume==
+
;ttsSetVolume(volume)
−
;ttsSetSpeechVolume(volume)
+
: Sets the volume of speech playback. On macOS, adjusting the system rate adjusts this value automatically.
−
: Sets the volume of speech playback.
 
  
 
;Parameters
 
;Parameters
Line 266: Line 360:
 
: Number. Should be between 1 and 0, will be limited otherwise.
 
: Number. Should be between 1 and 0, will be limited otherwise.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
tempTimer(1, function ()
+
-- talk quietly first, after 2 seconds talk a bit louder, after 4 seconds normally again
−
ttsSetSpeechVolume(0.2)
+
ttsSetVolume(0.2)
 
ttsSpeak("Quiet voice")
 
ttsSpeak("Quiet voice")
−
end)
 
  
−
tempTimer(2, function ( )
+
tempTimer(2, function ()
−
ttsSetSpeechVolume(0.5)
+
  ttsSetVolume(0.5)
−
ttsSpeak("Low voice")
+
  ttsSpeak("Low voice")
 
end)
 
end)
  
−
tempTimer(3, function ()  
+
tempTimer(4, function ()  
−
ttsSetSpeechVolume(1)
+
  ttsSetVolume(1)
−
ttsSpeak("Normal voice")
+
  ttsSpeak("Normal voice")
 
end)
 
end)
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
  
 
==ttsSetVoiceByIndex==
 
==ttsSetVoiceByIndex==
 
;ttsSetVoiceByIndex(index)
 
;ttsSetVoiceByIndex(index)
−
: If you have multiple voices available, you can switch them with this function by giving their index position as seen in the table you receive from ttsGetVoices(). If you know their name, you can also use ttsSetVoiceByName.
+
: If you have multiple voices available, you can switch them with this function by giving their index position as seen in the table you receive from ttsGetVoices(). If you know their name, you can also use ttsSetVoiceByName. On macOS and Windows, adjusting the system voice adjusts this value automatically.
 
: Returns true, if the setting was successful, errors otherwise.  
 
: Returns true, if the setting was successful, errors otherwise.  
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsGetVoices|ttsGetVoices]]
+
[[#ttsGetVoices|ttsGetVoices]]
  
 
;Parameters
 
;Parameters
Line 299: Line 391:
 
: Number. The voice from this index position of the ttsGetVoices table will be set.  
 
: Number. The voice from this index position of the ttsGetVoices table will be set.  
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
Line 305: Line 397:
 
display(ttsGetVoices())
 
display(ttsGetVoices())
 
ttsSetVoiceByIndex(1)
 
ttsSetVoiceByIndex(1)
−
--
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
  
 
==ttsSetVoiceByName==
 
==ttsSetVoiceByName==
 
;ttsSetVoiceByName(name)
 
;ttsSetVoiceByName(name)
−
: If you have multiple voices available, and know their name already, you can switch them with this function.
+
: If you have multiple voices available, and know their name already, you can switch them with this function. On macOS and Windows, adjusting the system voice adjusts this value automatically.
 
: Returns true, if the setting was successful, false otherwise.  
 
: Returns true, if the setting was successful, false otherwise.  
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsGetVoices|ttsGetVoices]]
+
[[#ttsGetVoices|ttsGetVoices]]
  
 
;Parameters
 
;Parameters
Line 321: Line 411:
 
: Text. The voice with this exact name will be set.
 
: Text. The voice with this exact name will be set.
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
Line 329: Line 419:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
==ttsSkip==
−
==ttsSkipSpeech==
+
;ttsSkip()
−
;ttsSkipSpeech()
 
 
: Skips the current line of text.
 
: Skips the current line of text.
  
 
See also:  
 
See also:  
−
[[Manual:Text to Speech Functions#ttsPauseSpeech|ttsPauseSpeech]],  
+
[[#ttsPause|ttsPause]],  
−
[[Manual:Text to Speech Functions#ttsQueueSpeech|ttsQueueSpeech]]
+
[[#ttsQueue|ttsQueue]]
  
−
{{note}} Available since Mudlet 3.13
+
{{MudletVersion|3.17}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
ttsQueueSpeech("We hold these truths to be self-evident")
+
ttsQueue("We hold these truths to be self-evident")
−
ttsQueueSpeech("that all species are created different but equal")
+
ttsQueue("that all species are created different but equal")
−
ttsQueueSpeech("that they are endowed with certain unalienable rights")
+
ttsQueue("that they are endowed with certain unalienable rights")
−
tempTimer(2, function () ttsSkipSpeech() end)
+
tempTimer(2, function () ttsSkip() end)
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 09:10, 9 July 2022

Text to Speech Functions

These functions can make Mudlet talk for you (audible sound from written words). Check out the Text-To-Speech Manual for more detail on how this all works together.

Mudlet VersionAvailable in Mudlet3.17+

Several Mudlet events are available functionality as well:

  • ttsSpeechStarted
  • ttsSpeechReady
  • ttsSpeechQueued
  • ttsSpeechPaused
  • ttsSpeechError
  • ttsPitchChanged
  • ttsRateChanged
  • ttsVoiceChanged
  • ttsVolumeChanged

ttsClearQueue

ttsClearQueue([index])
This function will help, if you have already queued a few lines of text to speak, and now want to remove some or all of them.
Returns false if an invalid index is given.
See also: ttsGetQueue, ttsQueue
Parameters
  • index:
(optional) number. The text at this index position of the queue will be removed. If no number is given, the whole queue is cleared.
Mudlet VersionAvailable in Mudlet3.17+
Example
-- queue five words and then remove some, "one, two, four" will be actually said
ttsQueue("One")
ttsQueue("Two")
ttsQueue("Three")
ttsQueue("Four")
ttsQueue("Five")
ttsClearQueue(2)
ttsClearQueue(3)

-- clear the whole queue entirely
ttsClearQueue()

ttsGetCurrentLine

ttsGetCurrentLine()
If you want to analyse if or what is currently said, this function is for you.
Returns the text being spoken, or false if not speaking.

See also: ttsSpeak, ttsQueue

Mudlet VersionAvailable in Mudlet3.17+
Example
ttsQueue("One")
ttsQueue("Two")
ttsQueue("Three")
ttsQueue("Four")
ttsQueue("Five")

-- print the line currently spoken 1s and 3s after which will be "two" and "five"
tempTimer(1, function()
  echo("Speaking: ".. ttsGetCurrentLine().."\n")
end)

tempTimer(3, function()
  echo("Speaking: ".. ttsGetCurrentLine().."\n")
end)

ttsGetCurrentVoice

ttsGetCurrentVoice()
If you have multiple voices available on your system, you may want to check which one is currently in use.
Returns the name of the voice used for speaking.

See also: ttsGetVoices

Mudlet VersionAvailable in Mudlet3.17+
Example
-- for example returns "Microsoft Zira Desktop" on Windows (US locale)
display(ttsGetCurrentVoice())

ttsGetPitch

ttsGetPitch()
If you want to analyse the pitch or tone of your current speech.
Returns the current pitch as a number between 1 (high) and -1 (deep).

See also: ttsSetPitch

Mudlet VersionAvailable in Mudlet3.17+
Example
local pitch = ttsGetPitch()
echo(pitch)

ttsGetQueue

ttsGetQueue([index])
This function can be used to show your current queue of texts, or any single text thereof.
Returns a single text or a table of texts, or false. See index parameter for details.

See also: ttsQueue

Parameters
  • index
(optional) number. The text at this index position of the queue will be returned. If no index is given, the whole queue will be returned. If the given index does not exist, the function returns false.
Mudlet VersionAvailable in Mudlet3.17+
Example
ttsQueue("We begin with some text")
ttsQueue("And we continue it without interruption")
display(ttsGetQueue())
-- will show the queued texts as follows
-- (first line ignored because it's being spoken and is not in queue):
-- {
--   "And we continue it without interruption"
-- }

ttsGetRate

ttsGetRate()
If you want to analyse the rate or speed of your current speech.
Returns the current rate as a number between 1 (fast) and -1 (slow).

See also: ttsSetRate

Mudlet VersionAvailable in Mudlet3.17+
Example
local rate = ttsGetRate()
echo(rate)

ttsGetState

ttsGetState()
With this function you can find the current state of the speech engine.
Returns one of: ttsSpeechReady, ttsSpeechPaused, ttsSpeechStarted, ttsSpeechError, ttsUnknownState.

See also: ttsSpeak, ttsPause, ttsResume, ttsQueue

Mudlet VersionAvailable in Mudlet3.17+
Example
ttsQueue("We begin with some text")
ttsQueue("And we continue it without interruption")
echo(ttsGetState())
-- ttsSpeechStarted

ttsGetVoices

ttsGetVoices()
Lists all voices available to your current operating system and language settings. Currently uses the default system locale.
Returns a table of names.

See also: ttsGetCurrentVoice, ttsSetVoiceByName, ttsSetVoiceByIndex

Mudlet VersionAvailable in Mudlet3.17+
Example
display(ttsGetVoices())
-- for example returns the following on Windows (US locale)
-- {
--   "Microsoft Zira Desktop"
-- }

ttsGetVolume

ttsGetVolume()
If you want to analyse the volume of your current speech.
Returns the current volume as a number between 1 (loud) and 0 (quiet).

See also: ttsSetVolume

Mudlet VersionAvailable in Mudlet3.17+
Example
local volume = ttsGetVolume()
echo(volume)

ttsPause

ttsPause()
Pauses the speech which is currently spoken, if any. Engines on different OS's (Windows/macOS/Linux) behave differently - pause may not work at all, it may take several seconds before it takes effect, or it may pause instantly. Some engines will look for a break that they can later resume from, such as a sentence end.

See also: ttsResume, ttsQueue

Mudlet VersionAvailable in Mudlet3.17+
Example
-- set some text to be spoken, pause it 2s later, and unpause 4s later
ttsSpeak("Sir David Frederick Attenborough is an English broadcaster and naturalist. He is best known for writing and presenting, in conjunction with the BBC Natural History Unit, the nine natural history documentary series that form the Life collection, which form a comprehensive survey of animal and plant life on Earth. Source: Wikipedia")
tempTimer(2, function() ttsPause() end)

tempTimer(2, function() ttsResume() end)

ttsQueue

ttsQueue(text to queue, [index])
This function will add the given text to your speech queue. Text from the queue will be spoken one after the other. This is opposed to ttsSpeak which will interrupt any spoken text immediately. The queue can be reviewed and modified, while their content has not been spoken.

See also: ttsGetQueue, ttsPause, ttsResume, ttsClearQueue, ttsGetState, ttsSpeak

Parameters
  • text to queue:
Any written text which you would like to hear spoken to you. You can write literal text, or put in string variables, maybe taken from triggers or aliases, etc.
  • index
(optional) number. The text will be inserted to the queue at this index position. If no index is provided, the text will be added to the end of the queue.
Mudlet VersionAvailable in Mudlet3.17+
Example
ttsQueue("We begin with some text")
ttsQueue("And we continue it without interruption")
display(ttsGetQueue())
-- will show the queued texts as follows
-- (first line ignored because it's being spoken and is not in queue):
-- {
--   "And we continue it without interruption"
-- }

ttsResume

ttsResume()
Resumes the speech which was previously spoken, if any has been paused.

See also: ttsPause, ttsQueue

Mudlet VersionAvailable in Mudlet3.17+
Example
-- set some text to be spoken, pause it 2s later, and unpause 4s later
ttsSpeak("Sir David Frederick Attenborough is an English broadcaster and naturalist. He is best known for writing and presenting, in conjunction with the BBC Natural History Unit, the nine natural history documentary series that form the Life collection, which form a comprehensive survey of animal and plant life on Earth. Source: Wikipedia")
tempTimer(2, function() ttsPause() end)

tempTimer(4, function() ttsResume() end)

ttsSpeak

ttsSpeak(text to speak)
This will speak the given text immediately with the currently selected voice. Any currently spoken text will be interrupted (use the speech queue to queue a voice instead).

See also: ttsQueue

Parameters
  • text to speak:
Any written text which you would like to hear spoken to you. You can write literal text, or put in string variables, maybe taken from triggers or aliases, etc.
Mudlet VersionAvailable in Mudlet3.17+
Example
ttsSpeak("Hello World!")

-- if 'target' is your target variable, you can also do this:
ttsSpeak("Hello "..target)

ttsSetPitch

ttsSetPitch(pitch)
Sets the pitch or tone of speech playback.
Parameters
  • pitch:
Number. Should be between 1 and -1, will be limited otherwise.
Mudlet VersionAvailable in Mudlet3.17+
Example
-- talk deeply first, after 2 seconds talk highly, after 4 seconds normally again
ttsSetPitch(-1)
ttsQueue("Deep voice")

tempTimer(2, function()
  ttsSetPitch(1)
  ttsQueue("High voice")
end)

tempTimer(4, function()
  ttsSetPitch(0)
  ttsQueue("Normal voice")
end)

ttsSetRate

ttsSetRate(rate)
Sets the rate or speed of speech playback. On macOS and Windows, adjusting the system rate adjusts this value automatically.
Parameters
  • rate:
Number. Should be between 1 and -1, will be limited otherwise.
Mudlet VersionAvailable in Mudlet3.17+
Example
-- talk slowly first, after 2 seconds talk quickly, after 4 seconds normally again
ttsSetRate(-1)
ttsQueue("Slow voice")

tempTimer(2, function ()
  ttsSetRate(1)
  ttsQueue("Quick voice")
end)

tempTimer(4, function ()
  ttsSetRate(0)
 ttsQueue("Normal voice")
end)

ttsSetVolume

ttsSetVolume(volume)
Sets the volume of speech playback. On macOS, adjusting the system rate adjusts this value automatically.
Parameters
  • volume:
Number. Should be between 1 and 0, will be limited otherwise.
Mudlet VersionAvailable in Mudlet3.17+
Example
-- talk quietly first, after 2 seconds talk a bit louder, after 4 seconds normally again
ttsSetVolume(0.2)
ttsSpeak("Quiet voice")

tempTimer(2, function ()
  ttsSetVolume(0.5)
  ttsSpeak("Low voice")
end)

tempTimer(4, function () 
  ttsSetVolume(1)
  ttsSpeak("Normal voice")
end)

ttsSetVoiceByIndex

ttsSetVoiceByIndex(index)
If you have multiple voices available, you can switch them with this function by giving their index position as seen in the table you receive from ttsGetVoices(). If you know their name, you can also use ttsSetVoiceByName. On macOS and Windows, adjusting the system voice adjusts this value automatically.
Returns true, if the setting was successful, errors otherwise.

See also: ttsGetVoices

Parameters
  • index:
Number. The voice from this index position of the ttsGetVoices table will be set.
Mudlet VersionAvailable in Mudlet3.17+
Example
display(ttsGetVoices())
ttsSetVoiceByIndex(1)

ttsSetVoiceByName

ttsSetVoiceByName(name)
If you have multiple voices available, and know their name already, you can switch them with this function. On macOS and Windows, adjusting the system voice adjusts this value automatically.
Returns true, if the setting was successful, false otherwise.

See also: ttsGetVoices

Parameters
  • name:
Text. The voice with this exact name will be set.
Mudlet VersionAvailable in Mudlet3.17+
Example
display(ttsGetVoices())
ttsSetVoiceByName("Microsoft Zira Desktop") -- example voice on Windows

ttsSkip

ttsSkip()
Skips the current line of text.

See also: ttsPause, ttsQueue

Mudlet VersionAvailable in Mudlet3.17+
Example
ttsQueue("We hold these truths to be self-evident")
ttsQueue("that all species are created different but equal")
ttsQueue("that they are endowed with certain unalienable rights")
tempTimer(2, function () ttsSkip() end)
Retrieved from "https://wiki.mudlet.org/index.php?title=Manual:Text_to_Speech_Functions&oldid=20026"