home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d7xx / d723 / animan.lha / AniMan / VoiceLib.doc < prev    next >
Text File  |  1992-09-04  |  13KB  |  370 lines
  1. *****************************************************************
  2.  
  3.    Voice Recognition for the Amiga and PerfectSound 3
  4.  
  5.    Voice.library (Ver 5.0) by Richard Horne - August 1992
  6.  
  7. *****************************************************************
  8.  
  9. FUNCTION OFFSET DEFINITIONS
  10.  
  11.    _LVOLearn           EQU   -30
  12.    _LVORecognize       EQU   -36
  13.    _LVOAddVoiceTask    EQU   -42
  14.    _LVORemVoiceTask    EQU   -48
  15.    _LVOGainUp          EQU   -54
  16.    _LVOGainDown        EQU   -60
  17.    _LVORecDataAddress  EQU   -66
  18.    _LVORecMapAddress   EQU   -72
  19.    _LVOWordScore       EQU   -78
  20.    _LVOPickSampler     EQU   -84
  21.    _LVOSetVoicePri     EQU   -90
  22.  
  23. ************************* FUNCTION DEFINITIONS ******************
  24.  
  25. >>>>> All variables are long words unless otherwise noted. <<<<<<
  26.  
  27. NOTE:  Voice.library is opened with a call to the exec OpenLibrary
  28. function.  OpenLibrary can fail for one of three reasons:
  29.  
  30. 1.  The voice.library file is not available in the libs: directory.
  31.  
  32. 2.  The parallel port is busy.
  33.  
  34. 3.  Voice.library is currently opened and being used by another
  35.     application program.
  36.  
  37. *****************************************************************
  38.  
  39. NAME:      
  40. Learn -- Learn a spoken phrase.
  41.  
  42. OFFSET:      
  43. -30
  44.  
  45. SYNOPSIS:
  46. MapAddress = Learn (MapBuffer, Text, Screen, SequenceNum, X, Y)
  47. d0                  a0         a1    a2      d0           d1 d2
  48.  
  49. FUNCTION:
  50. The "Learn" function stores a frequency map of a spoken word or
  51. phrase.  Each frequency map is made up of 72 long words of data
  52. plus a 16 byte header for the associated ASCII text (304 bytes
  53. total).  "Learn" requires the user to reserve a MapBuffer in
  54. memory equal to the size of vocabulary desired (number of words)
  55. times 304 bytes.  MapBuffer address is passed to "Learn" in a0. 
  56. Address of a null terminated text string representing the word or
  57. phrase to be learned is passed to "Learn" in a1.
  58.  
  59. The "Learn" function will open it's own window on the screen
  60. specified in a2 (use NULL for WBENCHSCREEN), at a position X, Y
  61. specified in d1 and d2.  The user will then be prompted to speak
  62. the specified word or phrase to obtain three good digital
  63. samples.  Internally, these three samples are analyzed for
  64. frequency content and transformed into a frequency map (304
  65. bytes) which is stored in the MapBuffer according to the Sequence
  66. Number specified in d0.  "Learn" returns the memory address
  67. within MapBuffer at which this particular frequency map is
  68. stored.  If "Learn" is intentionally cancelled using the close
  69. gadget of the Learn Window, then a zero will be returned.
  70.  
  71. "Learn" is called separately for each word or phrase in the
  72. vocabulary.  After every word has been learned, MapBuffer will be
  73. filled with a sequence of frequency maps (each 304 bytes).  Then
  74. the "Recognize" or "AddVoiceTask" functions can be called which
  75. will listen to the audio digitizer, compute a frequency map
  76. of incoming words compare them to the words in MapBuffer, and
  77. indicate by Sequence Number which word or phrase is the best
  78. match.  The maximum number of words or phrases in the vocabulary
  79. is 64.
  80.  
  81. Note that you must select an audio sampler (PerfectSound3 or
  82. SoundMaster) using the "PickSampler" function before using the
  83. "Learn" function.
  84.  
  85. *****************************************************************
  86.  
  87. NAME:
  88. Recognize -- Recognize a spoken word or phrase.
  89.  
  90. OFFSET:
  91. -36
  92.  
  93. SYNOPSIS:
  94. SequenceNum = Recognize (MapBuffer, SizeVocabulary, Resolution)
  95. d0                       a0         d0              d1 
  96.  
  97. FUNCTION:
  98. "Recognize" assumes that the user has learned a sequence of words
  99. or phrases using the "Learn" function.  MapBuffer contains a
  100. sequence of frequency maps produced by "Learn" corresponding to
  101. each word or phrase in the vocabulary.  Mapbuffer address is
  102. passed to "Recognize" in a0.  Number of words or phrases in the
  103. vocabulary are passed to "Recognize" in d0.
  104.  
  105. "Recognize" listens for an incoming word, computes it's frequency
  106. map, and compares this map to the sequence of maps contained in
  107. MapBuffer.  The Sequence Number of the word or phrase in
  108. MapBuffer which is most similar to that of the incoming word is
  109. returned in d0.  Note that the number "0" represents the first
  110. word, "1" the second, and so on.
  111.  
  112. "Recognize" will operate at either high resolution (d1 = 0) or
  113. low resolution (d1 = 1).  High resolution computes a frequency
  114. analysis of the incoming word or phrase at twice the number of
  115. points in time as low resolution.  High resolution is somewhat
  116. better at word recognition, but takes almost twice the processing
  117. time.
  118.  
  119. "Recognize" will return the following error codes if it cannot
  120. find a match.
  121.  
  122. d0 = -1 if there is no match between the incoming frequency map  
  123.    and any of the maps in MapBuffer.
  124.  
  125. d0 = -2 if the incoming word causes unacceptable digital
  126.    clipping.  Volume should be reduced by moving your
  127.    microphone or by using the "GainDown" function.
  128.     
  129. d0 = -3 if incoming word is too low in volume.  Volume should be
  130.    increased by moving your microphone or by using the "GainUp"
  131.    function.
  132.  
  133. d0 = -4 if the incoming sample is confused by extraneous noise.
  134.  
  135. *****************************************************************
  136.  
  137. NAME:      
  138. AddVoiceTask -- Initiate a separate task to recognize a spoken 
  139.                 word or phrase.
  140.  
  141. OFFSET:      
  142. -42
  143.  
  144. SYNOPSIS:
  145. AddVoiceTask (MapBuffer, MsgPort, SizeVocabulary, Resolution)
  146.               a0         a1       d0              d1
  147.  
  148. FUNCTION:
  149. "AddVoiceTask" is similar in function to "Recognize" except that
  150. here, a separate task is started under the Amiga multitasking
  151. operating system which listens for incoming words or phrases and
  152. returns messages to the user's Message Port indicating the
  153. Sequence Number of the frequency map in Mapbuffer which best
  154. matches the frequency map of the incoming word.  MapBuffer
  155. address and Message Port address are passed to "AddVoiceTask"
  156. in a0 and a1.  Number of words or phrases in the vocabulary are
  157. passed to "AddVoiceTask" in d0.
  158.  
  159. "AddVoiceTask" will operate at either high resolution (d1 = 0) or
  160. low resolution (d1 = 1).  High resolution computes a frequency
  161. analysis of the incoming word or phrase at twice the number of
  162. points in time as low resolution.  High resolution is somewhat
  163. better at word recognition, but takes almost twice the processing
  164. time.
  165.  
  166. The messages sent to MessagePort are designed to mimic shortened
  167. IDCMP messages with a im_Class = $0.  Thus you can receive and
  168. process these messages at either an Intuition window IDCMP
  169. message port or at a custom message port of your own.
  170. Messages sent by this task are as follows.
  171.  
  172. im_Code = Sequence number of frequency map in MapBuffer that
  173.           best matches the frequency map of the incoming
  174.           word or phrase.
  175.  
  176. im_Code = -1 if there is no match between the incoming
  177.           frequency map and any of the maps in MapBuffer.
  178.  
  179. im_Code = -2 if the incoming word causes unacceptable
  180.           digital clipping.  Volume should be reduced by
  181.           moving your microphone or by using the "GainDown"
  182.           function.
  183.  
  184. im_Code = -3 if incoming word is too low in volume.  Volume
  185.           should be increased by moving your microphone or
  186.           by using the "GainUp" function.
  187.  
  188. im_Code = -4 if the incoming sample is confused by
  189.           extraneous noise.
  190.  
  191. Upon calling "AddVoiceTask", the PerfectSound digitizer becomes
  192. immediately active, listening for an incoming word.  After
  193. receipt of a word or phrase, a message as described above is sent
  194. to Message Port.  The VoiceTask then goes into a WAIT mode and
  195. remains inactive until it receives a reply to the message it has
  196. sent to Message Port.  Upon receipt of a reply, VoiceTask again
  197. becomes goes active and listens for an incoming word.  The priority
  198. of this task will be 127 for fastest possible voice recognition.
  199. You may change this priority to a lower value with the "SetVoicePri"
  200. task.
  201.  
  202. *****************************************************************
  203.  
  204. NAME:      
  205. RemVoiceTask -- Remove task initiated by AddVoiceTask
  206.  
  207. OFFSET:      
  208. -48
  209.  
  210. SYNOPSIS:
  211. RemVoiceTask ()
  212.    
  213. FUNCTION:
  214. Deallocates memory and removes VoiceTask from the Amiga system.
  215. Note that the Message Port specified for the "AddVoiceTask" function
  216. must still exist at the time you call "RemVoiceTask".
  217.  
  218. *****************************************************************
  219.  
  220. NAME:
  221. GainUp -- Increase gain of PerfectSound 3 audio digitizer.
  222.  
  223. OFFSET:
  224. -54
  225.  
  226. SYNOPSIS:
  227. GainUp()
  228.  
  229. FUNCTION:
  230. Increases gain of the PerfectSound audio digitizer by one step. 
  231. Note that when gain reaches maximum, "GainUp" will wrap around
  232. and return gain to it's lowest value.  Do not call this function
  233. if you are using the SoundMaster audio digitizer.
  234.  
  235. *****************************************************************
  236.  
  237. NAME:
  238. GainDown -- Decease gain of PerfectSound 3 audio digitizer.
  239.  
  240. OFFSET:
  241. -60
  242.  
  243. SYNOPSIS:
  244. GainDown()
  245.  
  246. FUNCTION:
  247. Decreases gain of the PerfectSound audio digitizer by one step. 
  248. Note that when gain reaches minimum, "GainDown" will wrap around
  249. and return gain to it's highest value.  Do not call this function
  250. if you are using the SoundMaster audio digitizer
  251.  
  252. *****************************************************************
  253.  
  254. NAME:
  255. RecDataAddress -- Return memory address of digital sample of
  256.                   incoming word or phrase.
  257.  
  258. OFFSET:
  259. -66
  260.  
  261. SYNOPSIS:
  262. Address = RecDataAddress()
  263. d0
  264.  
  265.  
  266. FUNCTION:
  267. When an incoming word or phrase is digitized, 3/4 second of
  268. digital data is stored in an internal buffer.  This is 8 bit
  269. digitized data is sampled at a rate of 6400 Hz.  Thus the buffer
  270. for storing this data is 4800 bytes in size.  This function
  271. returns the address of this buffer for possible additional
  272. experimental uses.
  273.  
  274. *****************************************************************
  275.  
  276. NAME:
  277. RecMapAddress -- Return memory address of frequency map of
  278.                  incoming word or phrase.
  279.  
  280. OFFSET:
  281. -72
  282.  
  283. SYNOPSIS:
  284. Address = RecMapAddress()
  285. d0
  286.  
  287. FUNCTION:
  288. A frequency map of each incoming word or phrase is computed for
  289. comparison with maps learned and stored in MapBuffer.  Each map
  290. consists of a frequency analysis of 3/4 second of audio data at
  291. 72 points in time.  For each of these 72 time points, the data is
  292. examined for frequency content at 32 points between 0 Hz and 3200
  293. Hz.  A frequency map is made up of 72, 32 bit words corresponding
  294. to the 72 time points analyzed.  For each of these 32 bit words,
  295. bit 0 is set if the signal contains frequency components from 
  296. 0-100 Hz.  Bit 1 is set if the signal contains frequency
  297. components from 100-200 Hz.  Bit 2 is set if the signal contains
  298. frequency components from 200-300 Hz etc.  This function returns
  299. the address of this frequency map for possible additional
  300. experimental uses.  Note that this internal frequency map does
  301. not have the 16 byte ASCII header as do the frequency maps
  302. stored in MapBuffer.
  303.  
  304. *****************************************************************
  305.  
  306. NAME:
  307. WordScore -- Return recognition score of a recognized word.
  308.  
  309. OFFSET:
  310. -78
  311.  
  312. SYNOPSIS:
  313. Value = WordScore()
  314. d0
  315.  
  316. FUNCTION:
  317. The "Recognize" function computes a numerical score representing the
  318. "goodness" of a match between the frequency map of an incoming word
  319. and each frequency map stored in MapBuffer.  The recognized word
  320. is determined by highest score.  This function returns the score value
  321. for the recognized word.  Internally, a score of #2000 must be achieved
  322. in order for a match to be declared.  If you wish to have a higher match
  323. score threshold to reduce false matches, you may call "WordScore" after
  324. each word is recognized and set your own higher score threshold before
  325. accepting a match.  Increasing the match score threshold will reduce
  326. false matches, but will also decrease recognition performance.
  327.  
  328.  
  329. *****************************************************************
  330.  
  331. NAME:      
  332. PickSampler -- Specify which model audio sampler to use (either
  333.                PerfectSound3 or SoundMaster).
  334.  
  335. OFFSET:      
  336. -84
  337.  
  338. SYNOPSIS:
  339. PickSampler (SamplerID)
  340.                 d0
  341.  
  342. FUNCTION:
  343. Select the audio sampler to be used with this function.  SamplerID = 0
  344. for PerfectSound3.  SamplerID = 1 for SoundMaster
  345.  
  346. *****************************************************************
  347.  
  348. NAME:
  349. SetVoicePri -- Set the multitasking priority of a voice recognition
  350.                task that has been started by the "AddVoiceTask"
  351.                function.
  352.  
  353. OFFSET:
  354. -90
  355.  
  356. SYNOPSIS:
  357. Old Priority = SetVoicePri (New Priority)
  358. d0                          d0
  359.  
  360. FUNCTION:
  361. When "AddVoiceTask" is called, a voice recgnition task of priority 127
  362. is started for the fastest possible voice recognition.  You may modify
  363. this priority by setting New Priority to any value between -128 and 127
  364. and calling "SetVoicePri" which changes task priority to the new value
  365. and returns the value of the old task priority.  "AddVoiceTask" must
  366. be called before "SetVoicePri."
  367.  
  368. *****************************************************************
  369.  
  370.