Guest User


a guest
Oct 19th, 2013
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. his file contains the documentation for the natlink Python extension
  2. module. This extension module provides a thin wrapper around various
  3. functions in the Dragon NaturallySpeaking extended SAPI interface.
  5. playString( keys, flags )
  6. This is a utility function which will send a series of keystrokes to the
  7. window with the focus. The passed parameter is a string in standard
  8. Dragon NaturallySpeaking format (control sequences in braces). This
  9. function will not return until the last keystroke has been drained from
  10. the input queue.
  12. The second parameter is optional. It is a combination of one or more
  13. of the following flags:
  14. 0x01 # add SHIFT to the first character in the string
  15. 0x02 # add ALT to the first character in the string
  16. 0x04 # add CTRL to the first character in the string
  17. 0x08 # add RIGHT SHIFT to the first character in the string
  18. 0x10 # add RIGHT ALT to the first character in the string
  19. 0x20 # add RIGHT CTRL to the first character in the string
  20. 0x40 # use the extended keyboard version of the first char
  21. 0x100 # set this to defer the termination of the playStrings
  22. operation until the system is sure that the event queue
  23. has been drained. This works around a Win95 problem.
  24. 0x200 # set to send system keys, uses low-level keyboard hook
  25. 0x400 # when set, an exception will be raises if the user is
  26. holding in a shift key during the playString. This
  27. flag is highly recommended when sending system keys.
  28. 0x10000 # use scan codes when generating events
  29. 0x20000 # uppercase the entire string
  30. 0x40000 # lowercase the entire string
  31. 0x80000 # uppercase the first character in the string
  33. displayText( text, isError, logText )
  34. Natlink will create a window in which the user can display messages.
  35. Call this function to append a message to that window, displaying the
  36. window is necessary. The second parameter will cause the text to be
  37. displayed in red instead of black. The third parameter (if 1) will
  38. also copy the text to the dragon.log file.
  40. This function is useful for redirecting stdout and stderr.
  42. Note: this function does nothing unless NatLink is running as a command
  43. and control subsystem for NatSpeak.
  45. getClipboard()
  46. Returns a string which represents the current contents of the clipboard
  47. in text form. The string will be empty if there is no text in the
  48. clipboard.
  50. This function is useful for testing NatLink itself.
  52. getCurrentModule()
  53. This function returns a tuple which contains information about the current
  54. module and window which is active. The tuple contains:
  55. (1) the full file name of the module with the path and extension,
  56. (2) the title of the currently active window,
  57. (3) the handle of the currently active window as an integer.
  59. In the event that the current module name can not be determines, the
  60. getCurrentModule function will return the tuple ("","",0) instead of
  61. raising an exception.
  63. getCurrentUser()
  64. This function will return a tuple of information about the current user
  65. (set of speech files) for Dragon NaturallySpeaking. The tuple contains
  66. (1) the name of the user,
  67. (2) a full directory path where the user's speech files are
  68. located. If no user is loaded, the name of the user will be an
  69. empty string.
  71. getMicState()
  72. This function returns the microphone state, which can be one of 'off',
  73. 'on', 'disabled' and 'sleeping'.
  75. setMicState( newState )
  76. Use this function to change the microphone state. You can pass in
  77. 'off' to turn the microphone off, 'on' to turn the microphone on (which
  78. takes NatSpeak out of the sleeping state), or 'sleeping' to put NatSpeak
  79. in the sleeping state.
  81. Raised ValueError if the newState is not one of the indicated strings.
  83. execScript( command, args, comment )
  84. This function can be used to execute an arbitrary script using Dragon
  85. NaturallySpeakings built-in script language. The second parameter is
  86. optional and is a list of strings which represents the words which should
  87. be matched to _arg1, _arg2, etc. in the script. The third parameter is
  88. also optional and represents a comment which is displayed in an error
  89. messages if the script fails. Usually you pass in the command name.
  91. Raises SyntaxError is there is a syntax error in the script.
  93. getCallbackDepth()
  94. This function was primarily designed as a support function for the
  95. natlinkmain module. This function returns an integer which indicates
  96. how many nested callbacks are active. It returns 0 when you are not
  97. in a callback (for example, during initialization of natlinkmain). For
  98. a basic callback it returns 1 but if you call back into natlink from
  99. a callback causing a nested callback to happen (for example, you call
  100. recognitionMimic) then the callback nesting may be greater than 1.
  102. recognitionMimic( words )
  103. This function simulates the effect of a recognition. You pass in an
  104. array of words which represent the recognition results and NatSpeak
  105. then simulates the exact effect of having recognized that array of words.
  106. You will get an error if you pass in words which are unknown or if the
  107. array of words represents an impossible recognition given the current
  108. system state.
  110. Can raise MimicFailed if the phrase to be recognized is not legal in
  111. the current context (not in an active grammar). You also get this
  112. exception if a word in the input list was invalid.
  114. playEvents( events )
  115. This function is a more powerful version of playString which can play
  116. any sequence of events. You pass in a list of events to play where each
  117. event is a tuple of message, wParam and lParam as defined by windows.
  118. The following tuples are supported:
  119. (0x100, keycode, repeat) # wm_keydown
  120. (0x101, keycode, repeat) # wm_keyup
  121. (0x104, keycode, repeat) # wm_syskeydown
  122. (0x105, keycode, repeat) # wm_syskeyup
  123. (0x200, x, y) # wm_mousemove
  124. (0x201, x, y) # wm_lbuttondown
  125. (0x202, x, y) # wm_lbuttonup
  126. (0x203, x, y) # wm_lbuttondblclk
  127. (0x204, x, y) # wm_rbuttondown
  128. (0x205, x, y) # wm_rbuttonup
  129. (0x206, x, y) # wm_rbuttondblclk
  130. (0x207, x, y) # wm_mbuttondown
  131. (0x208, x, y) # wm_mbuttonup
  132. (0x209, x, y) # wm_mbuttondblclk
  134. getCursorPos()
  135. Returns a tuple with the x and y coordinates of the current position of
  136. the mouse on the screen. (0,0) is the upper left corner of the screen.
  138. getScreenSize()
  139. Returns a tuple with the x and y size of the full screen in pixels. This
  140. value can be used to make sure that the cursor remains on the screen.
  142. inputFromFile( fileName, realtime, playlist, uttDetect )
  143. This function will caused Dragon NaturallySpeaking to take its input from
  144. a wave file with the indicated filename. The realtime flag is optional
  145. and if true (integer 1) it will cause the playback to be slowed down to
  146. simulate realtime recognition.
  148. The playlist is optional and represents a list of utterances
  149. (zero-based) to play from the file. The playlist is only valid for
  150. UTT, UTD and NWV files. It is not valid for WAV files. For WAV
  151. files, utterance detection will be used to separate the utterances (all
  152. other files are assumed to have already been separated into
  153. utterances). The play list can contain a mixture of single integers and
  154. ranges represented as tuples of start and ending integers.
  156. Warning: because of a bug in NatSpeak, this code can not handle the
  157. error if you specify an utterance number in the playlist which is not
  158. present in the input file. If that happens you will get a NatSpeak
  159. SDAPI error and this function will not return. The only way to recover
  160. from this error will be to end the Python and NatSpeak processes.
  162. The defatly behavior of inputFromFile is to perform utterance
  163. detection (split speek at pauses) when using files with an extension
  164. of .wav and not perform utterance detection for other file extensions.
  165. You can override this default behavior by setting uttDetect. Setting
  166. uttDetect to 1 forces utterance detection and setting uttDetect to 0
  167. disables utterance detection. The default value is -1.
  169. Raises ValueError is the file is missing or has an unsupported
  170. extension.
  172. setTimerCallback( pCallback, nMilliseconds )
  173. Pass in the address of a Python function which will automatically be
  174. called every N milliseconds. The callback function will not be passed
  175. any parameters. Reset the timer by passing in a function of None.
  177. getTrainingMode()
  178. Returns information about the current training mode. If no special
  179. training mode is active then None is returned. Otherwise, we return
  180. a tuple of the current training mode (one of 'calibrate', 'shorttrain',
  181. 'longtrain', and 'batchadapt') and the total number of milliseconds
  182. of speech accepted for training so far.
  184. startTraining( mode )
  185. Initiates a special training mode. The possible training modes are:
  186. 'calibrate', 'shorttrain', 'longtrain' and 'batchadapt'.
  188. To perform training (in any training mode), you need to first call
  189. setTraining. Then you need to call the correction method for a series
  190. of previously recognized result objects (ResObj). Finally, after
  191. calling correction for each of the results objects you need to call
  192. finishTraining.
  194. To train a new user from scratch, you need to use the 'calibrate' special
  195. training mode on 5-10 utterances. Then you need to use either the
  196. 'shorttrain' or 'longtrain' special training mode. Short training is
  197. appropiate when using BestMatch III models and requires training of
  198. at least 3 minutes of speech. Long training is appropiate for normal
  199. models or the original BestMatch models and requires training of at least
  200. 18 minutes of speech.
  202. The third step is to use the 'batchadapt' special training mode.
  203. Usually you retrain the same utterances in 'batchadapt' mode that you
  204. trained in 'shorttrain' or 'longtrain' mode but this is not a requirement.
  205. There is no lower limit for the number of utterances trained using
  206. 'batchadapt' mode.
  208. Once a user has been trained it is no longer legal to use the
  209. 'calibrate', 'shorttrain' or 'longtrain' special training modes on that
  210. user. However, it is legal to perform additional training using the
  211. 'batchadapt' special training mode as many times as desired.
  213. Can raise WrongState you try to set any batch training mode when
  214. calibration has not been done or you try to set calibrate mode if
  215. calibration has already been done. Also if you try to set any
  216. training mode when the system is not in normal training mode.
  217. Can raise ValueError if the mode is not of the listed strings.
  219. finishTraining( bProcess )
  220. Terminates a special training mode. With no parameter, or a parameter
  221. of 1, calling finishTraining will perform the actual training operation.
  222. This may take a while. With a parameter of 0, no training is performed
  223. but the special training mode is cancelled.
  225. Can raise WrongState if a special training mode is not active.
  227. createUser( userName, baseModel, baseTopic )
  228. This call create a new user (NatSpeak speaker profile). The userName
  229. is a required string. The baseModel is an optional string. If
  230. specified it should be the name of one of the build-in base models
  231. (for example: "BestMatch Model"). You can see a list of known models
  232. by running NatSpeak and creating a new user. If missing, the default
  233. base models will be used.
  235. The baseTopic is also an optional string. If specified it should be
  236. the name of one of the built-in base topics (for example: "General
  237. English - BestMatch"). You can see a list of known topics by running
  238. NatSpeak and creating a new user (Professional Edition only). If
  239. missing, the default base topic will be used.
  241. Creating a user does not open it. You need to call openUser separately.
  243. Raises InvalidWord if the user name is invalid.
  244. Raises UserExists if the specified user already exists.
  245. Raises OutOfRange if the specified baseModel or baseTopic does not exist.
  247. openUser( userName )
  248. This call opens a specified NatSpeak user for recognition.
  250. Raises UnknownName is the specified user does not exist.
  252. saveUser()
  253. This call saves any modifications made to the currently open NatSpeak
  254. user to disk.
  256. getUserTraining()
  257. Returns a string which describes whether this user has been trained or
  258. not. Possible values are:
  259. None (which means no training has been done)
  260. 'calibrate' (which means only calibration was done)
  261. 'trained' (which means the user has been trained)
  263. getAllUsers()
  264. Returns an array of strings of the names of all existing users.
  266. getWordInfo( word, flags )
  267. Dragon 11: function does not work any more
  268. Looks a word up in the vocabulary and returns an integer which
  269. represents the word formatting information. The word formatting
  270. information can be 0. If the word does not exist in the vocabulary then
  271. None is returned.
  273. Flags is optional (default value is 0). If specified, you can combine
  274. of the following values:
  275. 1 = consider inactive words (backup dictionary)
  276. 2 = consider active non-dictation words
  277. 4 = case insensitive match
  279. The returned integer is a bit vector of the following flags:
  280. 0x00000001 - Word was added by the user
  281. 0x00000002 - Internal use only
  282. 0x00000004 - Internal use only
  283. 0x00000008 - Word can not be deleted
  284. 0x00000010 - Normally capitalize the next word (like period)
  285. 0x00000020 - Always capitalize the next word (like Cap Next)
  286. 0x00000040 - Uppercase the next word (like All Caps Next)
  287. 0x00000080 - Lowercase the next word (like No Caps Next)
  288. 0x00000100 - No space following this word (like left paren)
  289. 0x00000200 - Two spaces following this word (like period)
  290. 0x00000400 - No spaces between words with this flag set (like with numbers)
  291. 0x00000800 - Turn capitalization mode on (like Caps On)
  292. 0x00001000 - Turn uppercase mode on (like All Caps On)
  293. 0x00002000 - Turn lowercase mode on (like No Caps On)
  294. 0x00004000 - Turn off spacing between words (like No Space On)
  295. 0x00008000 - Restore normal spacing (like No Space Off)
  296. 0x00010000 - Internal use only
  297. 0x00020000 - Suppress after a word which ends in a period (like period after elipsis)
  298. 0x00040000 - Do not apply formatting to this word (like Cap)
  299. 0x00080000 - Do not reset the spacing state (like Cap)
  300. 0x00100000 - Do not reset the capitalization state (like close quote)
  301. 0x00200000 - No space preceeding this word (like comma)
  302. 0x00400000 - Restore normal capitalization (like Caps Off)
  303. 0x00800000 - Follow this word with one new line characters (like New-Line)
  304. 0x01000000 - Follow this word with two new line characters (like New-Paragraph)
  305. 0x02000000 - Do not capitalize this word in a title (like and)
  306. 0x04000000 - Internal use only
  307. 0x08000000 - Add an extra space following this word (like space-bar)
  308. 0x10000000 - Internal use only
  309. 0x20000000 - Internal use only
  310. 0x40000000 - Word was added by the vocabulary builder.
  312. Raises InvalidWord if the word is invalid.
  313. Raises ValueError if the flags are invalid.
  315. deleteWord( word )
  316. Removes a word from the active vocabulary. The word will still be in
  317. the backup dictionary.
  319. Raises InvalidWord if the word is invalid.
  320. Raises UnknownName if the word is not in the active vocabulary.
  322. addWord( word, wordInfo, pronList )
  323. Adds a word to the active vocabulary. The word may either be
  324. completely new or already in the backup dictionary. The wordInfo is
  325. optional, if missing it defaults to 0x00000001 (word was added by
  326. user).
  328. The third parameter is an optional pronunciation or list of
  329. pronunciations for the word using Dragon System's pronunciation
  330. alphabet. You can add pronunciations to an existing word using
  331. this function but you can not delete pronunciations.
  333. The function returns 1 if the word is added or a pronunciation is
  334. passed in. The function returns 0 if you pass in no pronunciations and
  335. the word already exists.
  337. If the function returns 0 then the wordInfo will be ignored. To change
  338. the wordInfo of an existing word then you must pass in a pronunciation.
  339. For example, use the following trick.
  340. currentProns = natlink.getWordProns( wordName )
  341. natlink.addWord( wordName, newInfo, currentProns[0] )
  343. Usage hints:
  345. - when adding words which are already in the backup dictionary, use a
  346. wordInfo of 0. This mimics Dragon NaturallySpeaking's own behavior.
  347. You can use the getWordInfo function to determine if the word is in the
  348. backup dictionary.
  350. - when adding a single compleyelt new word, include the 0x00000001 bit
  351. in wordInfo. This marks the word as user added and mimics Dragon
  352. NaturallySpeaking's own behavior.
  354. - when adding in lots of words at a time, also set the 0x40000000 bit
  355. in wordInfo. This simulates the effect of using the vocabulary builder
  356. which means that the word will be added with lower frequency.
  358. Raises InvalidWord if the word is invalid.
  360. setWordInfo( word, wordInfo )
  361. Changes the wordInfo for a word already in the active vocabulary.
  363. Raises InvalidWord if the word is invalid.
  364. Raises UnknownName if the word is not in the active vocabulary.
  366. getWordProns( wordName )
  367. Dragon 11: function does not work any more
  368. Returns a list of pronunciations for the given word. Each pronunciation
  369. is a string. Returns None if the word does not exist.
  371. Raises InvalidWord if the word is invalid.
  373. setTrayIcon( iconName, toolTip, callback )
  374. This function, provided by Jonathan Epstein, will draw an icon in the
  375. tray section of the tackbar.
  377. Pass in the absolute path to a Windows icon file (.ico) or pass in one
  378. of the following predefined names:
  379. 'right', 'right2', 'down', 'down2',
  380. 'left', 'left2', 'up', 'up2', 'nodir'
  381. You can also pass in an empty string (or nothing) to remove the tray
  382. icon.
  384. The toolTip parameter is optional. It is the text which is displayed
  385. as a tooltip when the mouse is over the tray icon. If missing, a generic
  386. tooltip is used.
  388. The callback parameter is optional. When used, it should be a Python
  389. function which will be called when a mouse event occurs for the tray
  390. icon. The function should take one parameters which is the type of
  391. mouse event:
  392. wm_lbuttondown, wm_lbuttonup, wm_lbuttondblclk, wm_rbuttondown,
  393. wm_rbuttonup, wm_rbuttondblclk, wm_mbuttondown, wm_mbuttonup,
  394. or wm_mbuttondblclk (all defined in natlinkutils)
  396. Raises ValueError if the iconName is invalid.
  398. The following functions are used in the natlinkmain base module. You
  399. should only used these if you are control NatSpeak using the NatLink module
  400. instead of using Python as a command and control subsystem for NatSpeak. In
  401. the later case, users programs should probably not use either of these two
  402. functions because they replace the callback used by the natlinkmain module
  403. which could prevent proper module (re)loading and user changes.
  405. setBeginCallBack( pCallback )
  406. Pass in the address of a Python function to call when the beginning of a
  407. new recognition is detected. Dragon NaturallySpeaking will pause all
  408. recognition processing until the Python function returns. However, it
  409. is safe to call other natlink module functions from within the
  410. Python callback function.
  412. When a recognition starts, this callback will be made and passed a single
  413. parameter which is the same tuple which is returned from getCurrentModule.
  415. setChangeCallback( pCallback )
  416. Pass in the address of a Python function to cal when something in the
  417. system changes. When a change occurs, the callback function will be
  418. passed two parameters. The first parameter is a string indicating what
  419. changed. The second parameter which depends on what changed.
  421. Active user changes: 'user', same tuple returned from getCurrentUser
  422. Mic state changes: 'mic', same string returned from getMicState
  424. The following three functions are designed to be used when you have a
  425. Python program which controls NatSpeak by explicitly importing the natlink
  426. module. Do not use these functions when you are using Python as a command
  427. and control subsystem for NatSpeak. In that case, these functions are
  428. automatically handled for you.
  430. isNatSpeakRunning()
  431. Returns 1 is NatSpeak is running and 0 otherwise. This is the only
  432. function which can be called before calling natConnect.
  434. natConnect( bUseThreads )
  435. Connect with Dragon NaturallySpeaking. This call will launch Dragon
  436. NaturallySpeaking if NaturallySpeaking is not running. As a side
  437. effect of this call, the natlink module will grap a number of COM
  438. interface pointers into Dragon NaturallySpeaking itself. Pass in an
  439. optional boolean to enable thread safety. This is required when running
  440. with the Pythonwin code.
  442. natDisconnect()
  443. Disconnect from NatSpeak by releasing all internal COM interfaces
  444. pointers. This will cause Dragon NaturallySpeaking to stop running it
  445. it was launched by calling connect.
  447. waitForSpeech( timeout )
  448. The Python program must call this function in order to allow speech to
  449. be processed. This function will enter a standard Windows message loop.
  450. When speech events occur, the previously established Python callback
  451. functions will be envoked in a nested call.
  453. A message box will be displayed if the timeout is zero or positive and the
  454. waitForSpeech call will not return until this message box is closed or
  455. until the timeout period (in milliseconds) ends. A timeout of zero
  456. suppresses the timeout. A negative timeout is just like a positive
  457. timeout except that the message box is not displayed (the function only
  458. returns when the timeout elapses).
  460. Inside natlink, each grammar is maintained as a separate object. To expose
  461. this structure, each grammar object will be exposed to Python as a class.
  462. The GrammarBase class defined in natlinkutils encapusulates and extends the
  463. basic functions of a grammar object. It is recommended that you use the
  464. GrammarBase class instead of using GramObj directly. The syntax for
  465. building grammars is documented in
  467. class GramObj():
  469. load( binary, allResults=0, hypothesis=0 )
  470. Before you use a grammar you need to pass in a binary representation
  471. of the grammar in SAPI format (as a string). This call actually
  472. creates the associated COM objects.
  474. If you set the optional allResults parameter to 1 then you will be
  475. able to get a results object even when the recognition is not
  476. specific to your grammar.
  478. If you optionally set hypothesis to 1 then partial recognition
  479. hypothesises will be available during recognition using a hypothesis
  480. callback (see setHypothesisCallback).
  482. The first DWORD of the SAPI binary grammar format defines the type
  483. of grammar. Command grammars (like those created by GrammarBase
  484. in natlinkutils) have a type of 0. Dictation grammars have a type
  485. of 1. Not every member function of GramObj is supported by every
  486. grammar type.
  488. Can raise InvalidWord if the grammar contains an invalid word.
  489. Can raise BadGrammar if the grammar specification is in error.
  491. unload()
  492. Call this to unload the grammar and delete the associated COM objects.
  493. This function will automatically be called when the GrammarBase object
  494. is garbage collected but it can also be called explicitly.
  496. activate( ruleName, window )
  497. Call this to activate a named exported rule in the grammar. You
  498. can activate multiple exported rules by calling this multiple times.
  499. Pass in the handle of a window (from getCurrentModule) or 0 for
  500. a global grammar.
  502. Pass in an empty ruleName for dictation grammars.
  504. Can raise UnknownName if ruleName is not defined in the grammar.
  505. Can raise BadGrammar if the grammar is too complex to be recognized.
  506. Can raise WrongState if the named rule is already active.
  507. Can raise BadWindow is the specified window does not exist.
  509. deactivate( ruleName )
  510. Call this to deactivate a named exported rule in the grammar.
  512. Can raise WrongState of the named rule is not currently active.
  514. setExclusive( state )
  515. Set the exclusive property on a grammar to force the recognizer
  516. to limit the recognition to only grammars which are marked as
  517. exclusive.
  519. setBeginCallBack( pCallback )
  520. Pass in the address of a Python function to call when the beginning of
  521. a new recognition is detected. Dragon NaturallySpeaking will pause
  522. all recognition processing until the Python function returns.
  523. However, it is safe to call other natlink module functions from
  524. within the Python callback function.
  526. This callback for each grammar object which has been loaded, and after
  527. the global BeginCallback is made.
  529. When a recognition starts, this callback will be made and passed a
  530. single parameter which is the same tuple which is returned from
  531. getCurrentModule
  533. setResultsCallback( pCallback )
  534. Call this to setup a callback function which will be called when a
  535. recognition occurs for this grammar object. Pass the callback
  536. function.
  538. When a recognition occurs, the callback function will be called with
  539. two parameters. The first parameter is the same list which is returned
  540. by ResObj.getResults(0). The second parameter will be a ResObj instance
  541. which represents the results object.
  543. If you have set the optional allResults parameter to load() then
  544. your results callback will also get the results of recognitions
  545. which were not the result of your grammar. If a recognition is
  546. the results of some other grammar in the system then the first
  547. parameter passed to your callback function will be the string 'other'
  548. instead of a list of words. If a recognition corresponds to a
  549. system rejection then the first parameter passed to your callback
  550. function will be 'reject'.
  552. setHypothesisCallback( pCallback )
  553. Call this to setup a callback function which will be called during
  554. the middle of recognitions with the partial hypothesis of the
  555. recognition in progress. You must have set the hypothesis
  556. parameter on load or the callback will not be called.
  558. The callback routine is passed a list of words representing
  559. the best recognition hypothesis so far. The frequency of callbacks
  560. is determined by Dragon NaturallySpeaking. Any word in the
  561. hypothesis is subject to chang ein the next callback or when the
  562. recognition completes.
  564. emptyList( listName )
  565. This function removes all the words in a named list in the grammar.
  567. Can raise UnknownName if listName is not defined in the grammar.
  568. Can raise WrongType is used with dictation grammars.
  570. appendList( listName, word )
  571. This function adds a new word (which can be a phrase) to a named list
  572. defined for the grammar. You can only append one word at a time.
  573. Combine this with emptyList to replace the words in a given list.
  575. Can raise InvalidWord if word list contains an invalid word.
  576. Can raise UnknownName if listName is not defined in the grammar.
  577. Can raise WrongType if used with dictation grammars.
  579. setContext( beforeText, afterText )
  580. For dictation grammars, this sets the speech recognition context.
  581. The context is the set of words (passing in at least 2 words is
  582. suggested) which the recognizer should assume proceed and optionally
  583. follow the text to be recognized next. Pass in two strings (the
  584. strings can be blank) which correspond to text (not words).
  585. AfterText is optional and will be assumed to be blank if missing.
  587. Can raise WrongType if used with command grammars.
  589. setSelectText( text )
  590. For SelectXYZ grammars only, this function is used to tell the
  591. recognition engine what text should be used for the SelectXYZ
  592. grammar. Pass in the visible text exactly as it appears on the
  593. screen. The recognition engine will automatically build the
  594. grammar.
  596. Can raise WrongType if used with other than SelectXYZ grammars.
  598. getSelectText()
  599. For SelectXYZ grammars only, this function returns the text
  600. currently stored in the reocgnition engine for this active
  601. SelectXYZ grammar. getText should return the same value stored
  602. with setText including modifications made by calling changeText.
  604. Can raise WrongType if used with other than SelectXYZ grammars.
  607. Results are also represented by objects which can be manipulated. Result
  608. objects are returned as the second parameter to the grammar results callback.
  610. class ResObj():
  612. getResults( choice )
  613. Call this to return the recognition results for a given choice
  614. on the choice list. Choice 0 (the default) is the actual recognition
  615. results. Other choices are alternatives. Returns None if there
  616. are no results.
  618. Normally returns a a list which which represents the recognition
  619. results. The list will contain a sequence of tuples. Each tuple
  620. will be a pair of the word which was recognized and the rule number
  621. of the innermost rule in the grammar which contains that word.
  623. Note that the rule number is only signifiant for command grammars.
  624. For dictation and selection grammars the rule number is always 0.
  626. Can raise OutOfRange if choice too large for that recognition.
  628. getWords( choice )
  629. Just like getResults except that it only returns a list of words not
  630. rule numbers. Returns None if there are no results for the given
  631. choice. This call is faster that getResults.
  633. Can raise OutOfRange if choice too large for that recognition.
  635. correction( words )
  636. Call this to perform a correction (and adaptation) of a results
  637. object. Pass in an array of words which represents what should
  638. have been recognized (which can be the same as what was recognized).
  639. This call can also be used when doing batch training.
  641. Returns 1 if training succeeds and 0 if training fails. Training
  642. can fail of the transcription is not close enough to the utterance.
  643. This is not considered to be a serious enough error to throw an
  644. exception.
  646. Can raise InvalidWord if word list contains an invalid word.
  648. getWave()
  649. Returns a string which contains binary data which represents the
  650. wave data for this results object.
  652. Can raise DataMissing is no wave data is available.
  654. getWordInfo( choice )
  655. Call this to return the recognition results for a given choice
  656. on the choice list. Choice 0 (the default) is the actual recognition
  657. results. Other choices are alternatives. Returns None if there
  658. are no results.
  660. Returns a list of tuples. Each tuple contains the following elements:
  661. wordName - same as returned by ResObj.getChoice
  662. cfgParse - same as returned by ResObj.getChoice
  663. wordScore - for the first word of the result, this is the score
  664. of this choice; lower is better; zero for other words
  665. startTime - start of word in milliseconds from start of utterance
  666. endTime - end of word in milliseconds from start of utterance
  667. engineInfo - integer (actually a DWORD) properties of the word
  668. wordPron - first pronunciation for the word; not necessarily
  669. the pronunciation which was recognized
  671. Multiply startTime and endTime by 11.025 to index into the wave data
  672. returned by ResObj.getWave
  674. Can raise OutOfRange if choice too large for that recognition.
  676. getSelectInfo( gramObj, choice=0 )
  677. Only for results from the recognition of a SelectXYZ grammar, this
  678. function returns a tuple containing information about the SelectXYZ
  679. recognition.
  681. The first parameter should be the grammar object for which you want
  682. the select info. The section parameter should be the choice number
  683. (just like getResults).
  685. The returned tuple contains:
  686. startPos - character position in the text buffer
  687. (GramObj.getSelectText) for the start of the selection
  688. endPos - character position for the end of the selection
  690. Can raise TypeError is the first parameter is not a GramObj instance.
  691. Can raise BadGrammar if the result did not come from the grammar.
  692. Can raise WrongType if used with other than SelectXYZ results.
  693. Can raise OutOfRange if choice too large for that recognition.
  695. This is a dictation objectm which encapsulates a complete dictation client.
  696. With NatSpeak, when you create a window which supports dictation, you
  697. associate that window with one dictation object.
  699. The dictation object maintains an internal buffer which is an exact copy of
  700. the text in the window. When the user changes the content of the window by
  701. typing, the dictation object buffer needs to be updated. When the user
  702. dictates into the window, the dictation object will change its internal
  703. buffer and then make a callback so the window can be updated.
  705. class DictObj():
  707. activate( window )
  708. Call this to activate the dictation grammar. Pass in the handle of a
  709. window (from getCurrentModule) or 0 for a global grammar.
  711. Can raise BadWindow is the specified window does not exist.
  713. deactivate()
  714. Call this to deactive the dictation grammar. It is safe to call
  715. deactivate even if activate has not been called.
  717. setBeginCallback( pCallback )
  718. Pass in the address of a Python function to call when the beginning of
  719. a new recognition is detected. Dragon NaturallySpeaking will pause
  720. all recognition processing until the Python function returns.
  721. However, it is safe to call other natlink module functions from
  722. within the Python callback function.
  724. This callback is made before the internal buffer is readied for
  725. recognition so it is safe to make changes to the internal buffer
  726. during the callback.
  728. When a recognition starts, this callback will be made and passed a
  729. single parameter which is the same tuple which is returned from
  730. getCurrentModule
  732. setChangeCallback( pCallback )
  733. Pass in the address of a Python function to call when recognition
  734. happens and the contents of the internal buffer is changed in some
  735. way.
  737. The called function will be passed the following parameters:
  738. ( delStart, delEnd, text, selStart, selEnd ).
  740. delStart,delEnd - define the range of characters in the buffer which
  741. were replaced by the recognition.
  743. text - is the string which replaced those charcters. The length of
  744. text may be different than end-start.
  746. selStart,selEnd - is the location of the selection after the the
  747. recognition.
  750. The following functions operate on the internal buffer. To be consistant
  751. with Python, it is legal to pass in negative values which are offsets
  752. from the end of the buffer. It is also legal to leave out the end
  753. parameter, in which case the end of the buffer is assumed.
  755. setLock( state )
  756. Call this to control the lock on the internal buffer. setLock(1)
  757. sets the lock and setLock(0) resets the lock. Internally the lock
  758. state is incremented when you set the lock so you need to call
  759. setLock(0) for every (nested) call to setLock(1).
  761. Locking the internal buffer guarentees that the state of the buffer
  762. remains consistant while the lock is held. You should lock the
  763. internal buffer before calling any of the following functions.
  765. Note: NatSpeak requires you to lock the internal buffer before
  766. any of these calls but to make Python programming easier, this
  767. module will set the lock for you. This is ok for a single call,
  768. but if you make multiple calls, you could get inconsistant
  769. information if you are not protected by a lock around all the
  770. calls.
  772. Can raise WrongState if you call setLock(0) when no lock is active.
  774. getLength()
  775. Returns the length of the text in the internal buffer. Note that
  776. getLength maybe somewhat expensive for large buffers.
  778. setText( text, start, end )
  779. Changes the text in the internal buffer at the indicated position.
  780. The length of the region to be changed (end-start) does not have
  781. to match the length of the text. This allows text to be inserted
  782. or deleted.
  784. getText( start, end )
  785. Returns a string which represents the text in the internal buffer
  786. at the indicated position. The length of the returned string will
  787. be end-start.
  789. setTextSel( start, end )
  790. Changes the current selected region.
  792. getTextSel()
  793. Returns the current selected region as a tuple of (start,end).
  795. setVisibleText( start, end )
  796. Establishes a subset of the buffer as being the range of visible
  797. text. Only visible text can be selected or corrected by voice.
  798. Otherwise, the visible text range has no effect on recognition.
  800. Unlike setTextSel which will coerce the end position to match the
  801. end of the buffer, if the start position is 0 and the end position
  802. is missing then the end position will be set to 0x7FFFFFFF rather
  803. than the length of the buffer.
  805. getVisibleText()
  806. Returns the current visible text range which was set by
  807. setVisibleText.
  809. The initial value of the visible text range is 0 - 0x7FFFFFFF
  810. which covers the entire buffer. This ensures that the selection
  811. commands work even if you do not set the visible text range
  814. ------------------------------------------------------------------------------
  816. About exceptions in NatLink. NatLink will return exceptions classes for
  817. errors which occur using the NatLink functions. In order to make it
  818. possible to look for specific errors, there are a number of possible error
  819. classes which can be returned. All NatLink error classes are derived from
  820. the base class "NatLink.NatError". The following subclasses are currently
  821. defined.
  823. NatError
  824. Base class for all NatLink errors. This is also returned for
  825. unexpected errors which are not common enough to have been converted
  826. into a more explicit error class.
  827. InvalidWord
  828. Raised when a word or named passed into a function is invalid.
  829. Usually because the word is too long or uses backslash characters
  830. improperly.
  831. UnknownName
  832. Raised when an unknown rule or list names is passed into a function.
  833. Also raised when passing an unknown username to openUser.
  834. OutOfRange
  835. Raised when accessing a result which is not available, usually
  836. because the choice number is too high. Also raised when an unknown
  837. base model or base topic is passed to createUser.
  838. MimicFailed
  839. Raised when recognitionMimic fails for any reason.
  840. BadGrammar
  841. Raised from GramObj.load when the grammar loads for any reason. Also
  842. returned from GramObj.activate when the grammar object is too complex
  843. to be activated.
  844. WrongState
  845. Raised when function can not be applied because system is in the wrong
  846. state. For example, if you call GramObj.activate on a rule which is
  847. already active or you call startTraining('calibrate') when the
  848. speech files have already been calibrated.
  849. BadWindow
  850. Raised when passing an invalid window handle to GramObj.activate.
  851. SyntaxError
  852. Raised when a script with a syntax error is passed to execScript.
  853. UserExists
  854. Raised when calling createUser when the user already exists.
  855. ValueError
  856. Raised when passing an invalid string to setMicState or startTraining.
  857. Also raised when the file passed to inputFromFile is missing or has
  858. an unsupported extension.
  859. DataMissing
  860. Raised by ResObj.getWave when the wave data is not available.
  861. WrongType
  862. Raised by GramObj when you make a function call which is not suppored
  863. for that grammar type. For example, GramObj.setContext is only
  864. supported for dictation grammars; if used on a command grammar this
  865. exception is raised.
RAW Paste Data