Included full documentation in the README file

README.md

@@ -67,7 +67,7 @@ The first one will clone the repository. Then, fluidsynth, a real-time MIDI synt
 
 ## Training Details
 
-Pivaenist was trained on the [MAESTRO v2.0.0 dataset](https://magenta.tensorflow.org/datasets/maestro), which contains 1282 midi files [check it in colab]. Their preprocessing involves splitting each note in pitch, duration and step, which compose a column of a 3xN matrix (which we call song map), where N is the number of notes and a row represents sequentially the different pitches, durations and steps. The VAE's objective is to reconstruct these matrices, making it then possible to generate random maps by sampling from the distribution, and then convert them to a MIDI file.
+Pivaenist was trained on the midi files of the [MAESTRO v2.0.0 dataset](https://magenta.tensorflow.org/datasets/maestro). Their preprocessing involves splitting each note in pitch, duration and step, which compose a column of a 3xN matrix (which we call song map), where N is the number of notes and a row represents sequentially the different pitches, durations and steps. The VAE's objective is to reconstruct these matrices, making it then possible to generate random maps by sampling from the distribution, and then convert them to a MIDI file.
 
 <figure>
     <img src="https://huggingface.co/TomRB22/pivaenist/resolve/main/.images/map_example.png" style="width:30%; display:block; margin:auto">
@@ -76,7 +76,35 @@ Pivaenist was trained on the [MAESTRO v2.0.0 dataset](https://magenta.tensorflow
 
 # Documentation
 
-## **_Audio_**
+## **_model.VAE_**
+
+### encode
+
+```python
+def encode(self, x_input: tf.Tensor) -> tuple[tf.Tensor]:
+```
+Get a "song map" and make a forward pass through the encoder, in order to return the latent representation and the distribution's parameters.
+
+Parameters:
+* x_input (tf.Tensor): Song map to be encoded by the VAE.
+
+Returns:
+* tf.Tensor: The parameters of the distribution which encode the song (mu, sd) and a sampled latent representation from this distribution (z_sample).
+
+### generate
+
+```python
+def generate(self, z_sample: tf.Tensor=None) -> tf.Tensor:
+```
+Decode a latent representation of a song.
+
+Parameters:
+* z_sample (tf.Tensor): Song encoding outputed by the encoder. If None, this sampling is done over an unit Gaussian distribution.
+
+Returns:
+* tf.Tensor: Song map corresponding to the encoding.
+
+## **_audio_**
 
 ### midi_to_notes
 
@@ -103,5 +131,42 @@ Parameters
 * pm (pretty_midi.PrettyMIDI): PrettyMIDI object containing a song.
 * seconds (int): Time fraction of the song to be displayed. When set to -1, the full length is taken.
 
-Returns
-* display.Audio: Song as an object allowing for display.
+Returns:
+* display.Audio: Song as an object allowing for display.
+
+### map_to_wav
+
+```python
+def map_to_wav(song_map: pd.DataFrame, out_file: str, velocity: int=100) -> pretty_midi.PrettyMIDI:
+```
+Convert "song map" to midi file (reverse process with respect to 
+midi_to_notes) and (optionally) save it, generating a PrettyMidi object in the process.
+
+Parameters:
+* song_map (pd.DataFrame): 3xN matrix where each column is a note, composed of pitch, duration and step.
+* out_file (str): Path or file to write .mid file to. If None, no saving is done.
+* velocity (int): Note loudness, i. e. the hardness a piano key is struck with.
+
+Returns:
+* pretty_midi.PrettyMIDI: PrettyMIDI object containing the song's representation.
+
+### generate_and_display
+
+```python
+def generate_and_display(model: VAE, 
+                         out_file: str=None, 
+                         z_sample: tf.Tensor=None, 
+                         velocity: int=100, 
+                         seconds: int=120) -> display.Audio:
+```
+Generate a song, (optionally) save it and display it.
+
+Parameters:
+* model (VAE): Instance of VAE to generate the song with.
+* out_file (str): Path or file to write .mid file to. If None, no saving is done.
+* z_sample (tf.Tensor): Song encoding used to generate a song. If None, perform generate an unconditioned piece.
+* velocity (int): Note loudness, i. e. the hardness a piano key is struck with.
+* seconds (int): Time fraction of the song to be displayed. When set to -1, the full length is taken.
+
+Returns:
+* display.Audio: Song as an object allowing for display.