PageRenderTime 25ms CodeModel.GetById 18ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/documentation/tutorial/usage_notes.html

http://eyes-free.googlecode.com/
HTML | 135 lines | 113 code | 21 blank | 1 comment | 0 complexity | 10d8b31c08e913483d8fa4bff3d4eb5d MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  2               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3<html xmlns="http://www.w3.org/1999/xhtml"
  4lang="en" xml:lang="en">
  5<head>
  6<title>Tips and Tricks for Using the TTS</title>
  7<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
  8<meta name="generator" content="Org-mode"/>
  9<meta name="generated" content="2008/12/12 14:29:02"/>
 10<meta name="author" content="Charles L. Chen"/>
 11<style type="text/css">
 12  html {
 13	font-family: Times, serif;
 14	font-size: 12pt;
 15  }
 16  .title { text-align: center; }
 17  .todo  { color: red; }
 18  .done { color: green; }
 19  .timestamp { color: grey }
 20  .timestamp-kwd { color: CadetBlue }
 21  .tag { background-color:lightblue; font-weight:normal }
 22  .target { background-color: lavender; }
 23  pre {
 24	border: 1pt solid #AEBDCC;
 25	background-color: #F3F5F7;
 26	padding: 5pt;
 27	font-family: courier, monospace;
 28  }
 29  table { border-collapse: collapse; }
 30  td, th {
 31	vertical-align: top;
 32	<!--border: 1pt solid #ADB9CC;-->
 33  }
 34</style>
 35</head><body>
 36<h1 class="title">Tips and Tricks for Using the TTS</h1>
 37
 38<h2>1 Introduction</h2>
 39
 40<p>Here are some tips and tricks on using the TTS in your app. <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tutorial/tutorial.html">These notes assume that you already have a basic understanding of how to set up an Android project that uses the TTS.</a>
 41</p>
 42
 43<h2>2 Dependency Management</h2>
 44
 45<p>One of the challenges in using a library like the TTS is dealing with the possibility that your app may be used by someone who does not have the TTS installed (or who has an obsolete version of the TTS).
 46</p>
 47<p>
 48If the user doesn't have the TTS installed, the TTS library allows you to either:
 49</p>
 50<ol>
 51<li>
 52Fail silently and not produce any spoken feedback,
 53</li>
 54<li>
 55Suggest that the user install the TTS but allow the user to proceed even if they choose not to install the TTS, or
 56</li>
 57<li>
 58Prompt the user to install the TTS and refuse to start until the TTS exists.
 59
 60</li>
 61</ol>
 62You can choose whichever of these behaviors makes the most sense for your app by how you <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#TTS(Context,%20com.google.tts.TTS.InitListener,%20boolean)">initialize the TTS object</a>.
 63
 64<p>
 65If you wish to fail silently, then you should set the displayInstallMessage parameter to false and ensure that your callback function does not do anything that is essential for starting your app because your callback will not be called at all if the TTS is not there.
 66</p>
 67<p>
 68If you wish to suggest the user install the TTS but allow them to proceed without it, then you should set the displayInstallMessage parameter to true and ensure that your callback function does not do anything that is essential for starting your app because your callback will not be called at all if the TTS is not there. 
 69</p>
 70<p>
 71If you wish to do nothing until the TTS has been installed because TTS functionality is an integral part of your app, then you should set the displayInstallMessage parameter to true and ensure that your callback function is what actually starts the app running. Typically, you can accomplish this by having an onCreate method which only has two lines: the first to call the super.onCreate method, and the second to initialize the TTS. The rest of your app initialization (including the call to setContentView which will set the layout of your app) should be done in your callback. This will ensure that the user gets a blank screen with nothing happening if they choose to not install the TTS.
 72</p>
 73<p>
 74The prompt will work even if the user does not have the TTS installed because the Java code for putting up the prompt is inside the TTS_library_stub.jar file you are building against. If you allow the user to proceed without the TTS, any calls made to the TTS will return immediately and are essentially no-ops; this means that you do not need to do any special checks within your code because you can assume that calls to the TTS methods will fail gracefully without doing anything.
 75</p>
 76<p>
 77Note that the argument for the callback function is the version number; if your app requires a minimum version of the TTS, the callback is a good place to check for it. The installation alert takes users to the TTS library on Market, so you should show that if you want the user to upgrade their TTS. You can show that by using the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#showVersionAlert()">showVersionAlert</a> method.
 78</p>
 79
 80
 81<h2>3 TTS Engines</h2>
 82
 83<p>Having a stable, unified TTS API that developers can work against is one of the major goals of this project. The idea is that as synthesis engines become available for Android, they can be plugged into this TTS library. As such, the TTS library currently supports <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTSEngine.html">three engines</a>: PRERECORDED_WITH_ESPEAK (default), ESPEAK_ONLY, and PRERECORDED_ONLY. You can specify the engine that you want your app to use by using the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#setEngine(com.google.tts.TTSEngine)">setEngine</a> method of the TTS.
 84</p>
 85<p>
 86PRERECORDED_WITH_ESPEAK (default) - Uses pre-recorded speech where available; otherwise, generates the speech using eSpeak.
 87</p>
 88<p>
 89ESPEAK_ONLY - Ignores all pre-recorded speech and only generates the speech using eSpeak.
 90</p>
 91<p>
 92PRERECORDED_ONLY - Uses pre-recorded speech only; if pre-recorded speech is not available, the TTS will fall back on spelling the text letter by letter.
 93</p>
 94
 95
 96<h2>4 Pre-Recorded Speech</h2>
 97
 98<p>There may be certain cases where pre-recorded audio is more appropriate than synthesized speech. Pre-recorded audio gives you higher quality voices and is easier on the CPU since it already exists so there are no computations needed to create it. For things that have a very limited vocabulary (a talking compass for instance) or for a special effect (perhaps you have a game where you want a particular phrase to be sung out in a jingle, rather than just spoken plainly), pre-recorded audio is a reasonable way to go.
 99</p>
100<p>
101To use pre-recorded speech, unless you are only speaking the alphabet and numbers, you will first have to associate the string of text with some audio by using the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#addSpeech(java.lang.String,%20java.lang.String,%20int)">addSpeech</a> method.
102</p>
103<p>
104The audio can either be a raw resource bundled in a package or a file on the user's SD card.
105</p>
106
107<h2>5 Voice Types</h2>
108
109<p>You can set the type of voice you would like used by having that as the params[0] in the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#speak(java.lang.String,%20int,%20java.lang.String[])">speak</a> method.
110</p>
111<p>
112The TTS does not support different types of voices in eSpeak yet, so for now, the voice types are for the alphabet/numbers of the pre-recorded sounds only. If you specify a voice type, eSpeak will just ignore it.
113</p>
114
115<h2>6 Speech Rate</h2>
116
117<p>You can set the speech rate by using the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#setSpeechRate(int)">setSpeechRate</a> method.
118</p>
119<p>
120The TTS does not support changing the speech rate in pre-recorded sounds, so this will only affect the speech produced by eSpeak.
121</p>
122
123<h2>7 Shutting Down</h2>
124
125<p>It's good practice to use the <a href="http://eyes-free.googlecode.com/svn/trunk/documentation/tts/com/google/tts/TTS.html#shutdown()">shutdown</a> method when your activity quits (call shutdown from inside the onDestroy method of your activity). This ensures that the TTS shuts down cleanly and prevents your app from generating a leaked service connection error in logcat.
126</p>
127
128
129
130<p class="author"> Author: Charles L. Chen
131<a href="mailto:clchen@google.com">&lt;clchen@google.com&gt;</a>
132</p>
133<p class="date"> Date: 2008/12/12 14:29:02</p>
134</body>
135</html>