Updated smnp.audio.mic (markdown)

smnp.audio.mic.md

@@ -1,9 +1,32 @@
+The [[smnp.audio.mic]] module is equivalent of [Listening module](https://github.com/bartlomiej-pluta/Simple-Music-Notation-Processor#listening-module) of Python-based SMNP implementation and it provides some fundamental functions that allows you handle the microphone input. 
+
+
 # Functions
 ## wait
 ```
 wait(noiseThreshold: int, silenceThreshold: int)
 ```
+Suspends the script execution and waits for incoming sound through connected microphone. When the function detects sound with level greater than `noiseThreshold`, it waits until the level of the sound is less than `silenceThreshold`. After that it resumes the script execution.
+
+The algorithm can be described using following model of finite states machine:
+[[model/wait_fsm.svg]]
+
+##### Example
+This function could be useful in some ear-training scenarios, when you need to i.e. play some notes and then wait for a user to repeat them and then do the same in another key, like:
+```
+noiseThreshold = 30;
+silenceThreshold = 10;
+keys = range(@c, @c5);
+melody = $ 4/4 @c @e @g @e | @c @f @a @f | @c @e @g @e | @c:2 2 ||;
+
+keys as key ^ {
+   synth(transposeTo(key, melody));
+   wait(noiseThreshold, silenceThreshold);
+}
+```
+
 ## micLevel
 ```
 micLevel()
-```
+```
+Prints the current level of microphone in real time. It allows you to estimate and adjust correct thresholds for [[smnp.audio.mic#wait]] function.