home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #7 / amigamamagazinepolishissue1998.iso / varia / animan / voicelibrary.doc < prev   
Text File  |  1978-06-30  |  16KB  |  478 lines
  1. *****************************************************************
  2.  
  3.    Voice Recognition for the Amiga using an audio digitizer.
  4.  
  5.    Voice.library (Ver 8.2) by Richard Horne - July 1993
  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.    _LVOPickTimer       EQU   -96
  23.    _LVOWhatGain        EQU   -102
  24.    _LVOPickChannel     EQU   -108
  25.    _LVOPickInput       EQU   -114
  26.  
  27. ************************* FUNCTION DEFINITIONS ******************
  28.  
  29. >>>>> All variables are long words unless otherwise noted. <<<<<<
  30.  
  31. NOTE:  Voice.library is opened with a call to the exec OpenLibrary
  32. function.  OpenLibrary can fail for one of three reasons:
  33.  
  34. 1.  The voice.library file is not available in the libs: directory or
  35.     cannot be found.
  36.  
  37. 2.  The parallel port is busy.
  38.  
  39. 3.  Voice.library is currently opened and being used by another
  40.     application program.
  41.  
  42. Also note that earlier versions of voice.library automatically set your
  43. current task priority to a high value for fastest voice recognition.
  44. This caused problems for some users, so this is no longer done.  It is
  45. entirely up to you to set your own task priority.
  46.  
  47. *****************************************************************
  48.  
  49. NAME:      
  50. Learn -- Learn a spoken phrase.
  51.  
  52. OFFSET:      
  53. -30
  54.  
  55. SYNOPSIS:
  56. MapAddress = Learn (MapBuffer, Text, Screen, SequenceNum, X, Y)
  57. d0                  a0         a1    a2      d0           d1 d2
  58.  
  59. FUNCTION:
  60. The "Learn" function stores a frequency map of a spoken word or
  61. phrase.  Each frequency map is made up of 72 long words of data
  62. plus a 16 byte header for the associated ASCII text (304 bytes
  63. total).  "Learn" requires the user to reserve a MapBuffer in
  64. memory equal to the size of vocabulary desired (number of words)
  65. times 304 bytes.  MapBuffer address is passed to "Learn" in a0. 
  66. Address of a null terminated text string representing the word or
  67. phrase to be learned is passed to "Learn" in a1.
  68.  
  69. The "Learn" function will open it's own window on the screen
  70. specified in a2 (use NULL for WBENCHSCREEN), at a position X, Y
  71. specified in d1 and d2.  The user will then be prompted to speak
  72. the specified word or phrase to obtain three good digital
  73. samples.  Internally, these three samples are analyzed for
  74. frequency content and transformed into a frequency map (304
  75. bytes) which is stored in the MapBuffer according to the Sequence
  76. Number specified in d0.  "Learn" returns the memory address
  77. within MapBuffer at which this particular frequency map is
  78. stored.  If "Learn" is intentionally cancelled using the close
  79. gadget of the Learn Window, then a zero will be returned.
  80.  
  81. "Learn" is called separately for each word or phrase in the
  82. vocabulary.  After every word has been learned, MapBuffer will be
  83. filled with a sequence of frequency maps (each 304 bytes).  Then
  84. the "Recognize" or "AddVoiceTask" functions can be called which
  85. will listen to the audio digitizer, compute a frequency map
  86. of incoming words compare them to the words in MapBuffer, and
  87. indicate by Sequence Number which word or phrase is the best
  88. match.  The maximum number of words or phrases in the vocabulary
  89. is 64.
  90.  
  91. Note that you must select an audio sampler (PerfectSound3,
  92. SoundMaster, or Generic) using the "PickSampler" function before
  93. using the "Learn" function.
  94.  
  95. *****************************************************************
  96.  
  97. NAME:
  98. Recognize -- Recognize a spoken word or phrase.
  99.  
  100. OFFSET:
  101. -36
  102.  
  103. SYNOPSIS:
  104. SequenceNum = Recognize (MapBuffer, SizeVocabulary, Resolution)
  105. d0                       a0         d0              d1 
  106.  
  107. FUNCTION:
  108. "Recognize" assumes that the user has learned a sequence of words
  109. or phrases using the "Learn" function.  MapBuffer contains a
  110. sequence of frequency maps produced by "Learn" corresponding to
  111. each word or phrase in the vocabulary.  Mapbuffer address is
  112. passed to "Recognize" in a0.  Number of words or phrases in the
  113. vocabulary are passed to "Recognize" in d0.
  114.  
  115. "Recognize" listens for an incoming word, computes it's frequency
  116. map, and compares this map to the sequence of maps contained in
  117. MapBuffer.  The Sequence Number of the word or phrase in
  118. MapBuffer which is most similar to that of the incoming word is
  119. returned in d0.  Note that the number "0" represents the first
  120. word, "1" the second, and so on.
  121.  
  122. "Recognize" will operate at either high resolution (d1 = 0) or
  123. low resolution (d1 = 1).  High resolution computes a frequency
  124. analysis of the incoming word or phrase at twice the number of
  125. points in time as low resolution.  High resolution is somewhat
  126. better at word recognition, but takes almost twice the processing
  127. time.
  128.  
  129. "Recognize" will return the following error codes if it cannot
  130. find a match.
  131.  
  132. d0 = -1 if there is no match between the incoming frequency map  
  133.    and any of the maps in MapBuffer.
  134.  
  135. d0 = -2 if the incoming word causes unacceptable digital
  136.    clipping.  Volume should be reduced by moving your
  137.    microphone or by using the "GainDown" function.
  138.     
  139. d0 = -3 if incoming word is too low in volume.  Volume should be
  140.    increased by moving your microphone or by using the "GainUp"
  141.    function.
  142.  
  143. d0 = -4 if the incoming sample is confused by extraneous noise.
  144.  
  145. *****************************************************************
  146.  
  147. NAME:      
  148. AddVoiceTask -- Initiate a separate task to recognize a spoken 
  149.                 word or phrase.
  150.  
  151. OFFSET:      
  152. -42
  153.  
  154. SYNOPSIS:
  155. AddVoiceTask (MapBuffer, MsgPort, SizeVocabulary, Resolution)
  156.               a0         a1       d0              d1
  157.  
  158. FUNCTION:
  159. "AddVoiceTask" is similar in function to "Recognize" except that
  160. here, a separate task is started under the Amiga multitasking
  161. operating system which listens for incoming words or phrases and
  162. returns messages to the user's Message Port indicating the
  163. Sequence Number of the frequency map in Mapbuffer which best
  164. matches the frequency map of the incoming word.  MapBuffer
  165. address and Message Port address are passed to "AddVoiceTask"
  166. in a0 and a1.  Number of words or phrases in the vocabulary are
  167. passed to "AddVoiceTask" in d0.
  168.  
  169. "AddVoiceTask" will operate at either high resolution (d1 = 0) or
  170. low resolution (d1 = 1).  High resolution computes a frequency
  171. analysis of the incoming word or phrase at twice the number of
  172. points in time as low resolution.  High resolution is somewhat
  173. better at word recognition, but takes almost twice the processing
  174. time.
  175.  
  176. The messages sent to MessagePort are designed to mimic shortened
  177. IDCMP messages with a im_Class = $0.  Thus you can receive and
  178. process these messages at either an Intuition window IDCMP
  179. message port or at a custom message port of your own.
  180. Messages sent by this task are as follows.
  181.  
  182. im_Class = 0
  183.  
  184. im_Code = Sequence number of frequency map in MapBuffer that
  185.           best matches the frequency map of the incoming
  186.           word or phrase.
  187.  
  188. im_Code = -1 if there is no match between the incoming
  189.           frequency map and any of the maps in MapBuffer.
  190.  
  191. im_Code = -2 if the incoming word causes unacceptable
  192.           digital clipping.  Volume should be reduced by
  193.           moving your microphone or by using the "GainDown"
  194.           function.
  195.  
  196. im_Code = -3 if incoming word is too low in volume.  Volume
  197.           should be increased by moving your microphone or
  198.           by using the "GainUp" function.
  199.  
  200. im_Code = -4 if the incoming sample is confused by
  201.           extraneous noise.
  202.  
  203. im_Qualifier = Word Recognition Score (See WordScore for definition)
  204.  
  205. Upon calling "AddVoiceTask", the audio digitizer becomes
  206. immediately active, listening for an incoming word.  After
  207. receipt of a word or phrase, a message as described above is sent
  208. to Message Port.  The VoiceTask then goes into a WAIT mode and
  209. remains inactive until it receives a reply to the message it has
  210. sent to Message Port.  Upon receipt of a reply, VoiceTask again
  211. becomes goes active and listens for an incoming word.  The priority
  212. of this task will be 120 for fastest possible voice recognition.
  213. You may change this priority to a lower value with the "SetVoicePri"
  214. function.
  215.  
  216. It is important that you remove this task using "RemVoiceTask" before
  217. learning any new commands or modifying data in MapBuffer.
  218.  
  219. *****************************************************************
  220.  
  221. NAME:      
  222. RemVoiceTask -- Remove task initiated by AddVoiceTask
  223.  
  224. OFFSET:      
  225. -48
  226.  
  227. SYNOPSIS:
  228. RemVoiceTask ()
  229.    
  230. FUNCTION:
  231. Deallocates memory and removes VoiceTask from the Amiga system.
  232. Note that the Message Port specified for the "AddVoiceTask" function
  233. must still exist at the time you call "RemVoiceTask".  Also you
  234. must reply to all outstanding messages from VoiceTask BEFORE calling
  235. this function.
  236.  
  237. *****************************************************************
  238.  
  239. NAME:
  240. GainUp -- Increase gain of PerfectSound 3 or DSS 8 audio digitizer.
  241.  
  242. OFFSET:
  243. -54
  244.  
  245. SYNOPSIS:
  246. GainUp()
  247.  
  248. FUNCTION:
  249. Increases gain of the PerfectSound or DSS 8 audio digitizer by one step. 
  250. Note that when Perfect Sound gain reaches maximum, "GainUp" will wrap
  251. around and return gain to it's lowest value.  DSS8 does not have this
  252. problem.  This function will have no effect on SoundMaster or Generic
  253. digitizers.
  254.  
  255. *****************************************************************
  256.  
  257. NAME:
  258. GainDown -- Decease gain of PerfectSound 3 or DSS 8 audio digitizer.
  259.  
  260. OFFSET:
  261. -60
  262.  
  263. SYNOPSIS:
  264. GainDown()
  265.  
  266. FUNCTION:
  267. Decreases gain of the PerfectSound or DSS 8 digitizer by one step.
  268. Note that when Perfect Sound gain reaches minimum, "GainDown" will wrap
  269. around and return gain to it's highest value.  DSS 8 does not have this
  270. problem.  This function will have no effect on SoundMaster or Generic
  271. digitizers.
  272.  
  273. *****************************************************************
  274.  
  275. NAME:
  276. RecDataAddress -- Return memory address of digital sample of
  277.                   incoming word or phrase.
  278.  
  279. OFFSET:
  280. -66
  281.  
  282. SYNOPSIS:
  283. Address = RecDataAddress()
  284. d0
  285.  
  286.  
  287. FUNCTION:
  288. When an incoming word or phrase is digitized, 3/4 second of
  289. digital data is stored in an internal buffer.  This is 8 bit
  290. digitized data is sampled at a rate of 6400 Hz.  Thus the buffer
  291. for storing this data is 4800 bytes in size.  This function
  292. returns the address of this buffer for possible additional
  293. experimental uses.
  294.  
  295. *****************************************************************
  296.  
  297. NAME:
  298. RecMapAddress -- Return memory address of frequency map of
  299.                  incoming word or phrase.
  300.  
  301. OFFSET:
  302. -72
  303.  
  304. SYNOPSIS:
  305. Address = RecMapAddress()
  306. d0
  307.  
  308. FUNCTION:
  309. A frequency map of each incoming word or phrase is computed for
  310. comparison with maps learned and stored in MapBuffer.  Each map
  311. consists of a frequency analysis of 3/4 second of audio data at
  312. 72 points in time.  For each of these 72 time points, the data is
  313. examined for frequency content at 32 points between 0 Hz and 3200
  314. Hz.  A frequency map is made up of 72, 32 bit words corresponding
  315. to the 72 time points analyzed.  For each of these 32 bit words,
  316. bit 0 is set if the signal contains frequency components from 
  317. 0-100 Hz.  Bit 1 is set if the signal contains frequency
  318. components from 100-200 Hz.  Bit 2 is set if the signal contains
  319. frequency components from 200-300 Hz etc.  This function returns
  320. the address of this frequency map for possible additional
  321. experimental uses.  Note that this internal frequency map does
  322. not have the 16 byte ASCII header as do the frequency maps
  323. stored in MapBuffer.
  324.  
  325. *****************************************************************
  326.  
  327. NAME:
  328. WordScore -- Return recognition score of a recognized word.
  329.  
  330. OFFSET:
  331. -78
  332.  
  333. SYNOPSIS:
  334. Value = WordScore()
  335. d0
  336.  
  337. FUNCTION:
  338. The "Recognize" function computes a numerical score representing the
  339. "goodness" of a match between the frequency map of an incoming word
  340. and each frequency map stored in MapBuffer.  The recognized word
  341. is determined by highest score.  This function returns the score value
  342. for the recognized word.  Internally, a score of #2000 must be achieved
  343. in order for a match to be declared.  If you wish to have a higher match
  344. score threshold to reduce false matches, you may call "WordScore" after
  345. each word is recognized and set your own higher score threshold before
  346. accepting a match.  Increasing the match score threshold will reduce
  347. false matches, but will also decrease recognition performance.
  348.  
  349.  
  350. *****************************************************************
  351.  
  352. NAME:      
  353. PickSampler -- Specify which model audio sampler to use (either
  354.                PerfectSound3, SoundMaster, DSS8, or Generic).
  355.  
  356. OFFSET:      
  357. -84
  358.  
  359. SYNOPSIS:
  360. Sampler = PickSampler (SamplerID) (Gain)
  361.                           d0        d1
  362.  
  363. FUNCTION:
  364. Select the audio sampler to be used with this function.  SamplerID = 0
  365. for PerfectSound3.  SamplerID = 1 for SoundMaster.  SamplerID = 2 for
  366. Generic Sampler. SamplerID = 3 for DSS8 Sampler.
  367.  
  368. If you are selecting the DSS 8 digitizer, you can also select a gain
  369. value from 0-7.
  370.  
  371. If you are running a VoiceTask (See AddVoiceTask) the remove VoiceTask
  372. before running this function.
  373.  
  374. *****************************************************************
  375.  
  376. NAME:
  377. SetVoicePri -- Set the multitasking priority of a voice recognition
  378.                task that has been started by the "AddVoiceTask"
  379.                function.
  380.  
  381. OFFSET:
  382. -90
  383.  
  384. SYNOPSIS:
  385. Old Priority = SetVoicePri (New Priority)
  386. d0                          d0
  387.  
  388. FUNCTION:
  389. When "AddVoiceTask" is called, a voice recgnition task of priority 127
  390. is started for the fastest possible voice recognition.  You may modify
  391. this priority by setting New Priority to any value between -128 and 127
  392. and calling "SetVoicePri" which changes task priority to the new value
  393. and returns the value of the old task priority.  "AddVoiceTask" must
  394. be called before "SetVoicePri."
  395.  
  396. *****************************************************************
  397.  
  398. NAME:
  399.  
  400. PickTimer -- Select either Timer A or Timer B of the CIA B for use
  401.              in timing digital audio samples.
  402.  
  403. OFFSET:
  404. -96
  405.  
  406. SYNOPSIS:
  407. PickTimer(TimerID)
  408.             d0
  409.  
  410. FUNCTION:
  411. Voice.library uses CIA B Timer B by default for setting the time interval
  412. between digital audio samples.  You may find situations where other
  413. applications require Timer B, causing a conflict.  Use this function to
  414. choose either Timer B or Timer A as required.  TimerID = 0 for selection
  415. of Timer B.  TimerID = 1 for selection of Timer A.  If you are running a
  416. VoiceTask (See AddVoiceTask) then remove VoiceTask before running this
  417. function.
  418.  
  419. *****************************************************************
  420.  
  421. NAME:
  422.  
  423. WhatGain -- Determine the gain setting of the DSS 8 digitizer.
  424.  
  425. OFFSET:
  426. -102
  427.  
  428. SYNOPSIS:
  429. Value = WhatGain()
  430. d0
  431.  
  432. FUNCTION:                                                                                          
  433. If you have selected the DSS 8 digitizer using PickSampler, you may then
  434. subsequently determine the digitizer gain setting using this function.
  435.  
  436. *****************************************************************
  437.  
  438. NAME:      
  439. PickChannel -- Specify left or right digitizer channel
  440.  
  441.  
  442. OFFSET:      
  443. -108
  444.  
  445. SYNOPSIS:
  446. Channel = PickChannel (ChannelID)
  447.                           d0
  448.  
  449. FUNCTION:
  450. Use this function after PickSampler to choose input from the left or right
  451. channel of your audio digitizer.  If you are running a VoiceTask
  452. (See AddVoiceTask), remove VoiceTask before running this function. Use
  453. ChannelID = 0 for right channel and ChannelID = 1 for left channel.  This
  454. function works for all digitizers except "Generic."
  455.  
  456. *****************************************************************
  457.  
  458. NAME:      
  459. PickInput -- Specify Microphone or Line Input
  460.  
  461.  
  462. OFFSET:      
  463. -114
  464.  
  465. SYNOPSIS:
  466. Input = PickInput (InputID)
  467.                      d0
  468.  
  469. FUNCTION:
  470. Use this function after PickSampler to choose input from either line or
  471. microphone to your audio digitizer.  If you are running a VoiceTask (See
  472. AddVoiceTask), remove VoiceTask before running this function.  InputID = 0
  473. for microphone and InputID = 1 for line input.  This function works for
  474. Sound Magic and DSS 8 digitizers.  The Perfect Sound 3 digitizer accepts
  475. both line and microphone input continuously.
  476.  
  477. *****************************************************************
  478.