diff --git a/smnp.audio.midi.md b/smnp.audio.midi.md
index 920c186..8e96658 100644
--- a/smnp.audio.midi.md
+++ b/smnp.audio.midi.md
@@ -1,14 +1,74 @@
+# Reference
+## Playing notes
+### Standard music notation
+The [[Music notation]] guide instructs how to compose notes that are consumable by the [[smnp.audio.midi#midi]] function.
+
+### PPQ-based music notation
+If you specify the `ppq` parameter in the config map of [[smnp.audio.midi#midi]] function, you will switch the duration-evaluation mode to PPQ-based. PPQ stands for _Pulses Per Quarter_ and it specifies the resolution of MIDI track. In other words - it specifies the smallest unit of duration that you will be able to use in your music sheet.
+
+As specifying the `ppq` parameter changes totally the meaning of duration in note literals, it requires an individual explanation.
+Compare following notes' durations:
+
+| NOTE            | `ppq` not specified | `ppq = 8`
+|:---------------:|:-------------------:|:---------
+| C, quarter      | `@c`                | `@c:8`
+| D, half         | `@d:2`              | `@d:16`
+| E, whole        | `@e:1`              | `@e:32`
+| F, half dotted  | `@f:2d`             | `@f:24 # 16 (half) + 8 (quarter)`
+| G, eighth       | `@g:8`              | `@g:4`
+| A, sixteenth    | `@a:16`             | `@a:2`
+| H, thirty-second| `@h:32`             | `@h:1`
+| C, sixty-fourth | `@c:64`             | not available
+
+## Supported commands
+
 # Functions
 ## midi
 ```
-midi(...notes: list<note, int, string>)
-midi(config: map<string><>, ...notes: list<note, int, string>)
-midi(notes: map<int><list<list<note, int, string>>>)
-midi(config: map<string><>, notes: map<int><list<list<note, int, string>>>)
+midi(...notes: list<note, int, string>)                                      #1
+midi(config: map<string><>, ...notes: list<note, int, string>)               #2
+midi(notes: map<int><list<list<note, int, string>>>)                         #3
+midi(config: map<string><>, notes: map<int><list<list<note, int, string>>>)  #4
+midi(midiFile: string)                                                       #5
 ```
+Allows you to play given notes using MIDI engine (`#1`, `#2`, `#3`, `#4`) and play existing MIDI file (`#5`).
+
+#### Arguments
+##### #2, #4
+* `config` - a config map which of the following shape (all keys are optional):
+
+| KEY | TYPE | VALUE | DEFAULT 
+|:---:|:----:|:-----:|:-------
+| bpm | `int` | Tempo determined as a number of beats per minute. | 120
+| ppq | `int` | The _Pulses Per Quarter_ - a MIDI parameter which determines the resolution of MIDI events list. Specifies the smallest/atomic unit of time used to play notes. If specified, it disables the default way to determining a duration of notes and switches it to _ticks_. For example, if `PPQ = 2` the `@c:1` is eight note, the `@c:2` is the quarter note, the `@c:4` is half note and `@c:8` is whole note. | -
+| output | `string` | The output MIDI file, where notes are intended to be written. If specified, the notes won't be played, only written to MIDI file. | -
+
+##### #1, #2
+* `notes` - is a list of staffs that are intended to be played polyphonically. Each staff is played using different channel (the MIDI's limit is up to 16 channels). Thanks to that, each staff can be played by different instrument. If you need to have more than 16 polyphonic lines, look at `#3` and `#4` respectively.
+
+##### #3, #4
+* `notes` - is a map that assigns a list of staff that are intended to be played polyphonically to given channel.
+It allows you to make use of special channel (for example the 10th for drums) as well as to have more than 16 polyphonic lines (still there is limit to have up to 16 channels/different instruments).
+
+##### #5
+* `midiFile` - the name of MIDI file intended to be played
 
 ## midiHelp
 ```
-midiHelp(command: string)
-midiHelp(instrument: int, bpm: int = 120, begin: note = @C1, end: note = @H9, channel: int = 1)
+midiHelp(command: string)                                                                       #1
+midiHelp(instrument: int, bpm: int = 120, begin: note = @C1, end: note = @H9, channel: int = 1) #2
+```
+Allows to obtain some useful info about your OS' MIDI engine (`#1`). Allows you to perform sound test of selected instrument (`#2`) using configurable notes range.
+
+#### Arguments
+##### #1
+* `command` - is the command which determines the category of info you'd like to obtain. Supported commands are:
+  * `instruments` - this command lists all instruments with their numbers available in your OS' MIDI engine that are ready to be used in your music sheets
+
+##### #2
+* `instrument` - the number of instrument to be tested
+* `bpm` - the tempo of executing test
+* `begin` - the range-beginning note
+* `end` - the range-ending note
+* `channel` - the channel intended to be used for test
 ```
\ No newline at end of file