LiveCode LessonsLiveCode LessonsHow To - LiveCode Sample ScriptsMiscellaneousHow do i use the Speech library on Mac,iOS and Android?

How do i use the Speech library on Mac,iOS and Android?

Starting with version 9.6 Livecode includes a new  library that provides functionality for synthesizing speech for macOS, iOS and Android. The library allows for choosing from among the system voices, altering the speech rate and pitch of the voice and speaking an utterance.

Please note, this speech library requires Indy or Business editions of LiveCode to work.

Create a new test stack

Create a new stack and add a field and a button to it. Name the field for example "Message2speak".


Create the stack script

Before we can use the library it has to be initialized. On Android it is mandatory that you initialize it in (pre)openstack.

So the suggested approach is to call "speechInitializeLibrary" once on (pre)openstack, and then call "speechFinalizeLibrary" on closeStack.

In that way, the library will be ready for use while your app is running, and it will be finalized once your app closes.


Create a stack script and add the following script to it.

Banners and Alerts
on preopenstack
   -- to be able to use the library we have to initalize it first
end preopenstack

on closeStack
   -- when the library is no longer needed  we should cleanup resource using the above
end closeStack
Click to copy

Create the button script

stack "Speak_Example" - Code Editor (editing)
on mouseup
   speechSpeakUtterance the text of fld "message2speak"
end mouseup
Click to copy

Standalone settings

To make use of the speech library you'll need to manually select it in Standalone Settings under Inclusions.

Make sure that you've selected "Select inclusions for the standalone application" unger General in the standalone settings

Standalone Application Settings for Speak_Example - General

Under Inclusions select Speech Library.

Standalone Application Settings for Speak_Example - Inclusions

Select the platform to which you want to deploy the app. Please remember that only Mac OS, iOS and Android are supported.

In this lesson we deploy to Mac OS.

Standalone Application Settings for Speak_Example - Mac

Now close the Standalone Settings window and save the stack.

Testing the our Speak_Example app.

To test our app either open Development menu and select Test  (1) or press the  Test icon in the Livecode toolbar (2).


Livecode IDE prompts with a Save dialog. Press Save to save your stack before testing.

Livecode now shows a little status stack giving information about the build process.

Standalone Builder Progress

After some seconds you should see the test app on your Mac OS desktop. Enter some text into the field and press the Button. You should hear the spoken text.

Speak_Example *

There are additional handlers and messages available in the library to the ones used in this lesson.


- speechSetRate (allows to change rate of speech)

Syntax: speechSetRate pRate

where pRate can be according to the dictionary between 0.01 and 2

Example:  speechSetRate 2


- speechSetPitch  (allows to change pitch of speech )

Syntax: speechSetRate pPitch

where pRate can be according to the dictionary between 0.01 and 2

Example: speechSetRate 2


- speechgetVoices() (retrieves a list of all available voices. On Android this is supported from Android version 6 and above)

Syntax: speechGetVoices()

Example: put speechgetVoices() into tVoices


- speechSetVoice  (allows to specifiy the voice to use. On Android this is supported from Android version 6 and above)

Syntax: speechSetVoice pVoice

where pVoice is the name of one of the available voices

Example: speechSetVoice


speechLibraryInitialized  This message is sent when the library has been initialized

 Could be useful if you want to execute some code after the library was initialized.

e.g. to fill  an option menu button with all the voice names.


speechUtteranceDidFinish This message is sent when an utterance is finished speaking




Below is a sample stack which makes also use of  speechSetVoice, speechGetVoice, speechSetPitch, speechSetRate, speechLibraryInitialized


Michael McLean

After spending a day with my students working on this it appears this library is only included on indy/business version, not community version. Is there any way I can just buy the library extension without having to buy an indy licence? Otherwise I'll have to give up the project which would be a shame.

Heather Laine

I'm afraid this library does only work in Indy and Business editions, it is not possible to buy or use it separately. Sorry I can't help with this :(

Michael McLean

Thanks for getting back to me. That's a shame. Seems strange that the features already available in the windows version are available for other operating systems but not included in the libraries. Anyway, not your decision I'm sure. I'll try something else. Even being able to purchase specific libraries would be better than $500 q year or nothing. Well I guess it's something for the powers that be to consider.


Hi, I'd like to know if there is any way to instead of playing the generated speech immediatly save it to file for later use...thanks

Elanor Buchanan

Hi Simon,

What is is that you want to achieve? You can just call speechSpeakUtterance when you want the text to be spoken.

Or do you mean you want to create a sound file?

Kind regards



Hi Elanor, the idea is to save the text to be spoken to a file to be played later instead to be played imediatly after being converted. Same question was posted on the forum ( and according to the answers it is not possible at this time...


Lately, on Android 10 devices, sometime, not always, I receive the following error, after calling speechSetVoice tChosenVoice:
864,19,1, cannot convert value
I guess the extension does not fail silently if it doesn't like the tChosenVoice.
Is this true?
I could put a try end try, but it would be better to know what is going on...

sam norris


That is quite likely to be the case. Could you please file a bug report for this with a reliable recipe/specific problematic voice?


Unfortunately the error report arrive automatically from some customer devices (Android 10) and I was never able to reproduce it.
The reported error is this one:
864,19,1,cannot convert value
353,0,0,button id 2049 of group id 2047 of group id 2035 of card id 1998 of stack "r_Settings" of stack "/data/app/".
My question is: do libraries (and widgets) are usually constructed inside LCB with a solid error handling, that pass info to LC scripts, or these reports are mostly used only by the developer of the specific library or widget?
I say this because in the past I often had "impossible" errors (like ...line 0 of..) that forced me, to be in the safe side, to rebuild the same functionality using LCS (like the segment widget, for example)

sam norris


We have made a bug report about this and will investigate. If you get any additional information about this, please post it at

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.