Update README.md

README.md

@@ -22,6 +22,8 @@ tags:
 ***
 
 ```
+Monster Piano by QVQ 7B
+
 In the heart of a grand piano black and blue,  
 A fuzzy monster with eyes of yellow hue,  
 Its fingers dance upon the ivory keys,  
@@ -72,6 +74,31 @@ choco install fluidsynth
 
 ***
 
+## Gradio app
+
+```sh
+# pip package includes a demo Gradio app without audio output
+
+# Please refer to monsterpianotransformer/gradio/app_full.py
+# for a full version with fluidsynth audio output
+
+monsterpianotransformer-gradio
+```
+
+***
+
+## Available models
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Print a list of available models
+mpt.load_model('models info')
+```
+
+***
+
 ## Quick-start use example
 
 ```python
@@ -86,13 +113,13 @@ model = mpt.load_model()
 sample_midi_path = mpt.get_sample_midi_files()[6][1]
 
 # Load seed MIDI
-input_tokens = mpt.midi_to_tokens(sample_midi_path, model_with_velocity=False)
+input_tokens = mpt.midi_to_tokens(sample_midi_path)
 
 # Generate seed MIDI continuation
-output_tokens = mpt.generate(model, input_tokens, 600, return_prime=True)
+output_tokens = mpt.generate(model, input_tokens, num_gen_tokens=600, return_prime=True)
 
-# Save output batch 0 to MIDI
-mpt.tokens_to_midi(output_tokens[0], model_with_velocity=False)
+# Save output batch # 0 to MIDI
+mpt.tokens_to_midi(output_tokens[0])
 ```
 
 ***
@@ -113,13 +140,13 @@ model = mpt.load_model()
 sample_midi_path = mpt.get_sample_midi_files()[6][1]
 
 # Load seed MIDI
-input_tokens = mpt.midi_to_tokens(sample_midi_path, model_with_velocity=False)
+input_tokens = mpt.midi_to_tokens(sample_midi_path)
 
 # Generate long seed MIDI auto-continuation
 output_tokens = mpt.generate_long(model, input_tokens, return_prime=True)
 
 # Save output batch 0 to MIDI
-mpt.tokens_to_midi(output_tokens[0], model_with_velocity=False)
+mpt.tokens_to_midi(output_tokens[0])
 ```
 
 ### Pitches inpainting
@@ -136,13 +163,13 @@ model = mpt.load_model()
 sample_midi_path = mpt.get_sample_midi_files()[6][1]
 
 # Load seed MIDI
-input_tokens = mpt.midi_to_tokens(sample_midi_path, model_with_velocity=False)
+input_tokens = mpt.midi_to_tokens(sample_midi_path)
 
 # Inpaint pitches
 output_tokens = mpt.inpaint_pitches(model, input_tokens)
 
 # Save output to MIDI
-mpt.tokens_to_midi(output_tokens, model_with_velocity=False)
+mpt.tokens_to_midi(output_tokens)
 ```
 
 ### Simple velocities inpainting
@@ -159,13 +186,13 @@ model = mpt.load_model(model_name='with velocity - 3 epochs')
 sample_midi_path = mpt.get_sample_midi_files()[6][1]
 
 # Load seed MIDI
-input_tokens = mpt.midi_to_tokens(sample_midi_path, model_with_velocity=True)
+input_tokens = mpt.midi_to_tokens(sample_midi_path)
 
 # Inpaint velocities
 output_tokens = mpt.inpaint_velocities_simple(model, input_tokens)
 
 # Save output to MIDI
-mpt.tokens_to_midi(output_tokens, model_with_velocity=True)
+mpt.tokens_to_midi(output_tokens)
 ```
 
 ### Seq2Seq velocities inpainting
@@ -176,19 +203,19 @@ import monsterpianotransformer as mpt
 
 # Load desired Monster Piano Transformer model
 # There are several to choose from...
-model = mpt.load_model(model_name='velocity inpainting - 3 epochs')
+model = mpt.load_model(model_name='velocity inpainting - 2 epochs')
 
 # Get sample seed MIDI path
 sample_midi_path = mpt.get_sample_midi_files()[6][1]
 
 # Load seed MIDI
-input_tokens = mpt.midi_to_tokens(sample_midi_path, model_with_velocity=True)
+input_tokens = mpt.midi_to_tokens(sample_midi_path)
 
 # Inpaint velocities
 output_tokens = mpt.inpaint_velocities_seq2seq(model, input_tokens, verbose=True)
 
 # Save output to MIDI
-mpt.tokens_to_midi(output_tokens, model_with_velocity=True)
+mpt.tokens_to_midi(output_tokens)
 ```
 
 ### Timings inpainting
@@ -237,7 +264,250 @@ output_tokens = mpt.inpaint_bridge(model, input_tokens)
 mpt.tokens_to_midi(output_tokens)
 ```
 
+### Single chord generation
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+model = mpt.load_model()
+
+# Generate single chord
+output_tokens = mpt.generate_chord(model)
+
+print(output_tokens)
+```
+
+### Chords progressions
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+model = mpt.load_model('chords progressions - 3 epochs')
+
+# Prime chord(s) as a list of lists of semitones and/or pitches
+prime_chords = [
+                [0],
+                [0, 2],
+                [0, 2, 4],
+                [60],
+                [60, 62]
+               ]
+
+# Convert chords to chords tokens
+chords_tokens = mpt.chords_to_chords_tokens(prime_chords)
+
+# Generate chord progression continuation
+output_tokens = mpt.generate(model, chords_tokens, num_gen_tokens=32, return_prime=True)
+
+# Convert output tokens batch # 0 back to the chords list
+chords_list = mpt.chords_tokens_to_chords(output_tokens[0])
+
+print(chords_list)
+```
+
+### Chords texturing
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+model = mpt.load_model('chords texturing - 3 epochs')
+
+# Get sample seed MIDI path
+sample_midi_path = mpt.get_sample_midi_files()[6][1]
+
+# Convert MIDI to chords list
+chords_list = mpt.midi_to_chords(sample_midi_path)
+
+# Texture chords
+output_tokens = mpt.texture_chords(model, chords_list)
+
+# Save output to MIDI
+mpt.tokens_to_midi(output_tokens)
+```
+
 ***
 
+## Advanced use examples
+
+### Chords progressions generation and texturing
+
+#### From custom chords list
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+cp_model = mpt.load_model('chords progressions - 3 epochs')
+tex_model = mpt.load_model('chords texturing - 3 epochs')
+
+# Prime chord(s) as a list of lists of semitones and/or pitches
+prime_chords = [
+                [0],
+                [0, 2],
+                [0, 2, 4]
+               ]
+
+# Convert chords to chords tokens
+chords_tokens = mpt.chords_to_chords_tokens(prime_chords)
+
+# Generate chords progression continuation
+cp_tokens = mpt.generate(cp_model, chords_tokens, num_gen_tokens=64, return_prime=True)
+
+# Generate pitches for chords in generated chords progression continuation
+output_tokens = mpt.generate_chords_pitches(tex_model, cp_tokens[0])
+
+# Convert output tokens to MIDI
+mpt.chords_pitches_to_midi(output_tokens)
+```
+
+#### From custom MIDI
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+cp_model = mpt.load_model('chords progressions - 3 epochs')
+tex_model = mpt.load_model('chords texturing - 3 epochs')
+
+# Get sample seed MIDI path
+sample_midi_path = mpt.get_sample_midi_files()[7][1]
+
+# Load seed MIDI
+chords_tokens = mpt.midi_to_chords(sample_midi_path, return_only_chords=True)
+
+# Generate chords progression continuation
+cp_tokens = mpt.generate(cp_model, chords_tokens[:64], num_gen_tokens=64, return_prime=True)
+
+# Generate pitches for chords in generated chords progression continuation
+output_tokens = mpt.generate_chords_pitches(tex_model, cp_tokens[0])
+
+# Convert output tokens to MIDI
+mpt.chords_pitches_to_midi(output_tokens)
+```
+
+#### From custom MIDI with prime chords and prime chords pitches
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+cp_model = mpt.load_model('chords progressions - 3 epochs')
+tex_model = mpt.load_model('chords texturing - 3 epochs')
+
+# Get sample seed MIDI path
+sample_midi_path = mpt.get_sample_midi_files()[7][1]
+
+# Load seed MIDI
+chords_list = mpt.midi_to_chords(sample_midi_path)
+
+# Number of prime chords
+num_prime_chords = 64
+
+# Create prime chords tokens list
+prime_chords_tokens = [c[0][0] for c in chords_list[:num_prime_chords]]
+
+# Create prime chords pitches list
+prime_chords_pitches = [c[0][1:] for c in chords_list[:num_prime_chords]]
+
+# Generate chords progression continuation
+cp_tokens = mpt.generate(cp_model, prime_chords_tokens, num_gen_tokens=128, return_prime=True)
+
+# Generate pitches for chords in generated chords progression continuation
+output_tokens = mpt.generate_chords_pitches(tex_model, cp_tokens[0], prime_chords_pitches)
+
+# Convert output tokens to MIDI
+mpt.chords_pitches_to_midi(output_tokens, chords_list)
+```
+
+#### From custom chords list with chords texturing and timings inpainting
+
+```python
+# Import Monster Piano Transformer as mpt
+import monsterpianotransformer as mpt
+
+# Load desired Monster Piano Transformer model
+# There are several to choose from...
+cp_model = mpt.load_model('chords progressions - 3 epochs')
+tex_model = mpt.load_model('chords texturing - 3 epochs')
+tim_model = mpt.load_model('timings inpainting - 2 epochs')
+
+# Prime chord(s) as a list of lists of semitones and/or pitches
+prime_chords = [
+                [0],
+                [0, 2],
+                [0, 2, 4]
+               ]
+
+# Convert chords to chords tokens
+chords_tokens = mpt.chords_to_chords_tokens(prime_chords)
+
+# Generate chords progression continuation
+cp_tokens = mpt.generate(cp_model, chords_tokens, num_gen_tokens=64, return_prime=True)
+
+# Generate pitches for chords in generated chords progression continuation
+cptcs_tokens = mpt.generate_chords_pitches(tex_model, cp_tokens[0], return_as_tokens_seq=True)
+
+# Inpaint timings
+output_tokens = mpt.inpaint_timings(tim_model, cptcs_tokens)
+
+# Save output to MIDI
+mpt.tokens_to_midi(output_tokens)
+```
+
+***
+
+## Dev and tests
+
+### Loading
+
+```python
+# You can load and use one or several models at the time
+
+# Default model (without velocity - 3 epochs)
+default_model = mpt.load_model()
+
+# More models...
+cp_model = mpt.load_model('chords progressions - 3 epochs')
+tex_model = mpt.load_model('chords texturing - 3 epochs')
+tim_model = mpt.load_model('timings inpainting - 2 epochs')
+```
+
+### Parameters
+
+```python
+# Dev models parameters can be accessed like so
+
+# Max sequence length
+print(default_model.max_seq_len)
+
+# Max number of tokens
+print(default_model.pad_value)
+```
+
+### Generation
+
+```python
+# Use generate or generate long functions for dev or testing with all models
+
+# Just make sure to prime the models with at least one token within its tokens range
+default_output = mpt.generate(default_model, input_tokens=[0], num_gen_tokens=32)
+tex_output = mpt.generate_long(tex_model, input_tokens=[0], num_gen_tokens=32)
+```
+
 ### Project Los Angeles
 ### Tegridy Code 2025