Metadata-Version: 2.4
Name: deepbach_pytorch
Version: 1.5.0
Summary: DeepBach implementation for harmonization
Home-page: https://github.com/Ghadjeres/DeepBach
Author: Gaetan Hadjeres, JinruGuan
Author-email: grudan930809@outlook.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: music21>=8.1.0
Requires-Dist: tqdm
Requires-Dist: numpy>=1.23.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# deepbach-pytorch
```
pip install deepbach-pytorch==1.5.0
```
For detailed usage instructions for the package api, please refer to `test.py`

## What's new in 1.5.0

No public API was removed or renamed. `harmonize()` gained two keyword
arguments, both with defaults, so existing calls behave as before.

**Input robustness.** `harmonize()` now accepts a melody-only file. It picks
the part that actually carries notes rather than trusting the part count, so an
exported lead sheet that ships one real staff plus three empty ones no longer
fixes silence and regenerates the wrong voice. A single-part input used to
produce a `(1, length)` tensor and crash the sampler; the melody is now encoded
with the trained range and vocabulary of the slot it will occupy and the other
voices are filled with rests. Metadata is padded or truncated to the melody
length, which fixes the assertion failure on imported scores with pickups or
trailing measures, and empty or zero-length input now raises a named error
instead of failing deep inside the sampler.

**Fixing an inner voice.** `melody_voice` was documented as 0/1/2/3 but the
generation span was built with `[min(others), max(others) + 1]`, which for
`melody_voice=1` or `2` expanded to all four voices and silently regenerated
the melody it was supposed to hold fixed. The voices to regenerate are now
enumerated explicitly through a new `voice_indices` argument on
`DeepBach.generation()`, so any voice can be held fixed.

**Cadential cue.** An imported melody normally carries no fermata, which left
the fermata metadata channel — the model's only explicit phrase-ending cue — at
zero for the whole piece. `derive_fermatas=True` (default) fills it with the
convention the model was trained on: the last beat of every two bars plus the
final note. Worth roughly +3.3 points of note-exact reconstruction accuracy on
Bach chorales (70.2% -> 67.9% of the gap to a true channel; leaving it zeroed
is 64.6%). Pass `False` for the previous behaviour. The channel is a
conditioning input, not part of the generated music, so `fermata_marks`
controls how it is written out: `"none"` (default) writes the XML with no
fermata marks, `"input"` keeps only the input file's own, `"channel"` draws the
channel as-is. Purely notational — a music21 Fermata carries no duration, so
removing one changes no note's offset, length or pitch.

**Range diagnostic.** DeepBach encodes any note outside the trained range of
the voice it occupies as a single out-of-range token, losing the pitch. A
melody well below C4 therefore reaches the model as a nearly constant line.
`harmonize()` now reports how many notes fall outside the fixed voice's range
and suggests the voice that fits better, instead of failing silently. The
melody is never transposed for you.

**Two metadata fixes.** `FermataMetadata.generate()` tested
`len(note.expressions) == 1`, which reports any single expression as a fermata
and misses a real fermata sharing a note with another expression; it now tests
for `music21.expressions.Fermata` directly. It also indexed `list_notes[0]` on
a part with no notes and raised `IndexError`. The MuseScore server no longer
returns the conditioning channel painted onto the soprano of its output.




# DeepBach
This repository contains implementations of the DeepBach model described in

*DeepBach: a Steerable Model for Bach chorales generation*<br/>
Gaëtan Hadjeres, François Pachet, Frank Nielsen<br/>
*ICML 2017 [arXiv:1612.01010](http://proceedings.mlr.press/v70/hadjeres17a.html)*


The code uses python 3.9 together with [PyTorch v2.0](https://pytorch.org/) and
 [music21](http://web.mit.edu/music21/) libraries.

For the original Keras version, please checkout the `original_keras` branch.

Examples of music generated by DeepBach are available on [this website](https://sites.google.com/site/deepbachexamples/)

Models, Dataset caches and Deployment script are available on [Google Drive](https://drive.google.com/drive/folders/1ZbZiDmX3yShaelS3p_xdGBEQsPoHi6tb?usp=drive_link)

## Installation

You can clone this repository, install dependencies using Anaconda and download a pretrained 
model together with a dataset  
 with the following commands:
```
git clone git@github.com:Ghadjeres/DeepBach.git
cd DeepBach
conda env create --name deepbach_pytorch -f environment.yml
bash dl_dataset_and_models.sh
```
This will create a conda env named `deepbach_pytorch`.

### music21 editor

You might need to
Open a four-part chorale. Press enter on the server address, a list of computed models should appear. Select and (re)load a model. 
[Configure properly the music editor
 called by music21](http://web.mit.edu/music21/doc/moduleReference/moduleEnvironment.html). On Ubuntu you can eg. use MuseScore:

```shell
sudo apt install musescore
python -c 'import music21; music21.environment.set("musicxmlPath", "/usr/bin/musescore")'
```

For usage on a headless server (no X server), just set it to a dummy command:

```shell
python -c 'import music21; music21.environment.set("musicxmlPath", "/bin/true")'
```

## Usage
```
Usage: deepBach.py [OPTIONS]

Options:
  --note_embedding_dim INTEGER    size of the note embeddings
  --meta_embedding_dim INTEGER    size of the metadata embeddings
  --num_layers INTEGER            number of layers of the LSTMs
  --lstm_hidden_size INTEGER      hidden size of the LSTMs
  --dropout_lstm FLOAT            amount of dropout between LSTM layers
  --linear_hidden_size INTEGER    hidden size of the Linear layers
  --batch_size INTEGER            training batch size
  --num_epochs INTEGER            number of training epochs
  --train                         train or retrain the specified model
  --num_iterations INTEGER        number of parallel pseudo-Gibbs sampling
                                  iterations
  --sequence_length_ticks INTEGER
                                  length of the generated chorale (in ticks)
  --help                          Show this message and exit.
```

## Examples
You can generate a four-bar chorale with the pretrained model and display it in MuseScore  by 
simply running
```
python deepBach.py
```

You can train a new model from scratch by adding the `--train` flag.


## Usage with NONOTO
The command 
```
python flask_server.py
```
starts a Flask server listening on port 5000. You can then use 
[NONOTO](https://github.com/SonyCSLParis/NONOTO) to compose with DeepBach in an interactive way.

This server can also been started using Docker with:
```
docker run -p 5000:5000 -it --rm ghadjeres/deepbach
```
(CPU version), with
or
```
docker run --runtime=nvidia -p 5000:5000 -it --rm ghadjeres/deepbach
```
(GPU version, requires [nvidia-docker](https://github.com/NVIDIA/nvidia-docker).


## Usage within MuseScore
*Deprecated*

Put `deepBachMuseScore.qml` file in your MuseScore plugins directory, and run
```
python musescore_flask_server.py
```
Open MuseScore and activate deepBachMuseScore plugin using the Plugin manager.
You can then click on the Compose button without any selection to create a new chorale from 
scratch. You can then select a region in the chorale score and click on the Compose button to 
regenerated this region using DeepBach.


### Issues

### Music21 editor not set

```
music21.converter.subConverters.SubConverterException: Cannot find a valid application path for format musicxml. Specify this in your Environment by calling environment.set(None, '/path/to/application')
```

Either set it to MuseScore or similar (on a machine with GUI) to to a dummy command (on a server). See the installation section.

# Citing

Please consider citing this work or emailing me if you use DeepBach in musical projects.
```
@InProceedings{pmlr-v70-hadjeres17a,
  title = 	 {{D}eep{B}ach: a Steerable Model for {B}ach Chorales Generation},
  author = 	 {Ga{\"e}tan Hadjeres and Fran{\c{c}}ois Pachet and Frank Nielsen},
  booktitle = 	 {Proceedings of the 34th International Conference on Machine Learning},
  pages = 	 {1362--1371},
  year = 	 {2017},
  editor = 	 {Doina Precup and Yee Whye Teh},
  volume = 	 {70},
  series = 	 {Proceedings of Machine Learning Research},
  address = 	 {International Convention Centre, Sydney, Australia},
  month = 	 {06--11 Aug},
  publisher = 	 {PMLR},
  pdf = 	 {http://proceedings.mlr.press/v70/hadjeres17a/hadjeres17a.pdf},
  url = 	 {http://proceedings.mlr.press/v70/hadjeres17a.html},
}
```
