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

From Mudlet
Jump to navigation Jump to search
(Initial commit)
 
m
Line 1: Line 1:
{{TOC right}}
+
{{TOC right}}  
 +
= Text to Speech Functions =
 +
 
 
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.
 
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.
  
A few new events have been added for this functionality as well:
+
A few new [[Manual:Event_Engine|events]] have been added for this functionality as well:
 
* ttsSpeechStarted
 
* ttsSpeechStarted
 
* ttsSpeechReady
 
* ttsSpeechReady

Revision as of 00:30, 10 August 2018

Text to Speech Functions

These functions are used to create audible sound from written words. The feature is available since Mudlet version 3.13. Check out our Text-To-Speech Manual for more detail on how this all works together.

A few new events have been added for this functionality as well:

  • ttsSpeechStarted
  • ttsSpeechReady
  • ttsSpeechQueued
  • ttsSpeechPaused
  • ttsSpeechError


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: ttsGetSpeechQueue

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.

Note Note: Available since Mudlet 3.13

Example
ttsQueueSpeech("One")
ttsQueueSpeech("Two")
ttsQueueSpeech("Three")
ttsQueueSpeech("Four")
ttsQueueSpeech("Five")
ttsClearQueue(2)
ttsClearQueue(3)


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, ttsQueueSpeech

Note Note: Available since Mudlet 3.13


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

Note Note: Available since Mudlet 3.13

Example
ttsGetCurrentVoice()
-- for example returns "Microsoft Zira Desktop" on Windows (US locale)


ttsGetSpeechQueue

ttsGetSpeechQueue([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: ttsQueueSpeech

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.

Note Note: Available since Mudlet 3.13

Example
ttsQueueSpeech("We begin with some text")
ttsQueueSpeech("And we continue it without interruption")
display(ttsGetSpeechQueue())
-- will show the queued texts as follows:
-- {
--   "And we continue it without interruption",
--   "We begin with some text"
-- }


ttsGetState

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

See also: ttsSpeak, ttsPauseSpeech, ttsResumeSpeech, ttsQueueSpeech

Note Note: Available since Mudlet 3.13

Example
ttsSpeak("This is just a test!")
display(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

Note Note: Available since Mudlet 3.13

Example
display(ttsGetVoices())
-- for example returns the following on Windows (US locale)
-- {
--   "Microsoft Zira Desktop"
-- }


ttsPauseSpeech

ttsPauseSpeech()
Pauses the speech which is currently spoken, if any.

See also: ttsResumeSpeech, ttsQueueSpeech

Note Note: Available since Mudlet 3.13


ttsQueueSpeech

ttsQueueSpeech(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: ttsGetSpeechQueue, ttsPauseSpeech, ttsResumeSpeech, 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.

Note Note: Available since Mudlet 3.13

Example
ttsQueueSpeech("We begin with some text")
ttsQueueSpeech("And we continue it without interruption", 1)
display(ttsGetSpeechQueue())
-- The texts have changed order, the second will be spoken first. 
-- The queue shows as follows:
-- {
--  "And we continue it without interruption",
--  "We begin with some text"
-- }


ttsResumeSpeech

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

See also: ttsPauseSpeech, ttsQueueSpeech

Note Note: Available since Mudlet 3.13


ttsSpeak

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.

See also: ttsQueueSpeech

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.

Note Note: Available since Mudlet 3.13

Example
ttsSpeak("Hello World!")


ttsSetSpeechPitch

ttsSetSpeechPitch(pitch)
Sets the pitch of speech playback.
Parameters
  • pitch:
Number. Should be between 1 and -1, will be limited otherwise.

Note Note: Available since Mudlet 3.13

Example
ttsSetSpeechPitch(-1)
ttsQueueSpeech("Deep voice")
ttsSetSpeechPitch(1)
ttsQueueSpeech("High voice")
ttsSetSpeechPitch(0)
ttsQueueSpeech("Normal voice")


ttsSetSpeechRate

ttsSetSpeechRate(rate)
Sets the rate of speech playback.
Parameters
  • rate:
Number. Should be between 1 and -1, will be limited otherwise.

Note Note: Available since Mudlet 3.13

Example
tempTimer(1, function ()
ttsSetSpeechRate(-1)
ttsQueueSpeech("Slow voice")
end)
tempTimer(2, function ()
ttsSetSpeechRate(1)
ttsQueueSpeech("Quick voice")
end)
tempTimer(3, function ()
ttsSetSpeechRate(0)
ttsQueueSpeech("Normal voice")
end)


ttsSetSpeechVolume

ttsSetSpeechVolume(volume)
Sets the volume of speech playback.
Parameters
  • volume:
Number. Should be between 1 and 0, will be limited otherwise.

Note Note: Available since Mudlet 3.13

Example
tempTimer(1, function ()
ttsSetSpeechVolume(0.2)
ttsSpeak("Quiet voice")
end)

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

tempTimer(3, function () 
ttsSetSpeechVolume(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.
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.

Note Note: Available since Mudlet 3.13

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.
Returns true, if the setting was successful, false otherwise.

See also: ttsGetVoices

Parameters
  • name:
Text. The voice with this exact name will be set.

Note Note: Available since Mudlet 3.13

Example
display(ttsGetVoices())
ttsSetVoiceByName("Microsoft Zira Desktop") -- example voice on Windows


ttsSkipSpeech

ttsSkipSpeech()
Skips the current line of text.

See also: ttsPauseSpeech, ttsQueueSpeech

Note Note: Available since Mudlet 3.13

Example
ttsQueueSpeech("We hold these truths to be self-evident")
ttsQueueSpeech("that all species are created different but equal")
ttsQueueSpeech("that they are endowed with certain unalienable rights")
tempTimer(2, function () ttsSkipSpeech() end)