Create README.md

#2
by reach-vb HF staff - opened
Files changed (1) hide show
  1. README.md +244 -0
README.md ADDED
@@ -0,0 +1,244 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ inference: true
3
+ tags:
4
+ - musicgen
5
+ license: cc-by-nc-4.0
6
+ ---
7
+
8
+ # MusicGen - Stereo - Large - 3.3B
9
+
10
+ We further release a set of stereophonic capable models. Those were fine tuned for 200k updates starting
11
+ from the mono models. The training data is otherwise identical and capabilities and limitations are shared with the base modes. The stereo models work by getting 2 streams of tokens from the EnCodec model, and interleaving those using
12
+ the delay pattern.
13
+
14
+ MusicGen is a text-to-music model capable of genreating high-quality music samples conditioned on text descriptions or audio prompts.
15
+ It is a single stage auto-regressive Transformer model trained over a 32kHz EnCodec tokenizer with 4 codebooks sampled at 50 Hz.
16
+ Unlike existing methods, like MusicLM, MusicGen doesn't require a self-supervised semantic representation, and it generates all 4 codebooks in one pass.
17
+ By introducing a small delay between the codebooks, we show we can predict them in parallel, thus having only 50 auto-regressive steps per second of audio.
18
+
19
+ MusicGen was published in [Simple and Controllable Music Generation](https://arxiv.org/abs/2306.05284) by *Jade Copet, Felix Kreuk, Itai Gat, Tal Remez, David Kant, Gabriel Synnaeve, Yossi Adi, Alexandre Défossez*.
20
+
21
+ We provide a simple API and 10 pre-trained models. The pre trained models are:
22
+ - `facebook/musicgen-small`: 300M model, text to music only - [🤗 Hub](https://huggingface.co/facebook/musicgen-small)
23
+ - `facebook/musicgen-medium`: 1.5B model, text to music only - [🤗 Hub](https://huggingface.co/facebook/musicgen-medium)
24
+ - `facebook/musicgen-melody`: 1.5B model, text to music and text+melody to music - [🤗 Hub](https://huggingface.co/facebook/musicgen-melody)
25
+ - `facebook/musicgen-large`: 3.3B model, text to music only - [🤗 Hub](https://huggingface.co/facebook/musicgen-large)
26
+ - `facebook/musicgen-melody-large`: 3.3B model, text to music and text+melody to music - [🤗 Hub](https://huggingface.co/facebook/musicgen-melody-large)
27
+ - `facebook/musicgen-stereo-*`: All the previous models fine-tuned for stereo generation -
28
+ [small](https://huggingface.co/facebook/musicgen-stereo-small),
29
+ [medium](https://huggingface.co/facebook/musicgen-stereo-medium),
30
+ [large](https://huggingface.co/facebook/musicgen-stereo-large),
31
+ [melody](https://huggingface.co/facebook/musicgen-stereo-melody),
32
+ [melody large](https://huggingface.co/facebook/musicgen-stereo-melody-large)
33
+
34
+ ## Example
35
+
36
+ Try out MusicGen yourself!
37
+
38
+ * Audiocraft Colab:
39
+
40
+ <a target="_blank" href="https://colab.research.google.com/drive/1fxGqfg96RBUvGxZ1XXN07s3DthrKUl4-?usp=sharing">
41
+ <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
42
+ </a>
43
+
44
+ * Hugging Face Colab:
45
+
46
+ <a target="_blank" href="https://colab.research.google.com/github/sanchit-gandhi/notebooks/blob/main/MusicGen.ipynb">
47
+ <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
48
+ </a>
49
+
50
+ * Hugging Face Demo:
51
+
52
+ <a target="_blank" href="https://huggingface.co/spaces/facebook/MusicGen">
53
+ <img src="https://huggingface.co/datasets/huggingface/badges/raw/main/open-in-hf-spaces-sm.svg" alt="Open in HuggingFace"/>
54
+ </a>
55
+
56
+ ## 🤗 Transformers Usage
57
+
58
+ You can run MusicGen locally with the 🤗 Transformers library from version 4.31.0 onwards.
59
+
60
+ 1. First install the 🤗 [Transformers library](https://github.com/huggingface/transformers) and scipy:
61
+
62
+ ```
63
+ pip install --upgrade pip
64
+ pip install --upgrade transformers scipy
65
+ ```
66
+
67
+ 2. Run inference via the `Text-to-Audio` (TTA) pipeline. You can infer the MusicGen model via the TTA pipeline in just a few lines of code!
68
+
69
+ ```python
70
+ from transformers import pipeline
71
+ import scipy
72
+
73
+ synthesiser = pipeline("text-to-audio", "facebook/musicgen-large")
74
+
75
+ music = synthesiser("lo-fi music with a soothing melody", forward_params={"do_sample": True})
76
+
77
+ scipy.io.wavfile.write("musicgen_out.wav", rate=music["sampling_rate"], music=audio["audio"])
78
+ ```
79
+
80
+ 3. Run inference via the Transformers modelling code. You can use the processor + generate code to convert text into a mono 32 kHz audio waveform for more fine-grained control.
81
+
82
+ ```python
83
+ from transformers import AutoProcessor, MusicgenForConditionalGeneration
84
+
85
+ processor = AutoProcessor.from_pretrained("facebook/musicgen-large")
86
+ model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-large")
87
+
88
+ inputs = processor(
89
+ text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
90
+ padding=True,
91
+ return_tensors="pt",
92
+ )
93
+
94
+ audio_values = model.generate(**inputs, max_new_tokens=256)
95
+ ```
96
+
97
+ 4. Listen to the audio samples either in an ipynb notebook:
98
+
99
+ ```python
100
+ from IPython.display import Audio
101
+
102
+ sampling_rate = model.config.audio_encoder.sampling_rate
103
+ Audio(audio_values[0].numpy(), rate=sampling_rate)
104
+ ```
105
+
106
+ Or save them as a `.wav` file using a third-party library, e.g. `scipy`:
107
+
108
+ ```python
109
+ import scipy
110
+
111
+ sampling_rate = model.config.audio_encoder.sampling_rate
112
+ scipy.io.wavfile.write("musicgen_out.wav", rate=sampling_rate, data=audio_values[0, 0].numpy())
113
+ ```
114
+
115
+ For more details on using the MusicGen model for inference using the 🤗 Transformers library, refer to the [MusicGen docs](https://huggingface.co/docs/transformers/model_doc/musicgen).
116
+
117
+ ## Audiocraft Usage
118
+
119
+ You can also run MusicGen locally through the original [Audiocraft library]((https://github.com/facebookresearch/audiocraft):
120
+
121
+ 1. First install the [`audiocraft` library](https://github.com/facebookresearch/audiocraft)
122
+ ```
123
+ pip install git+https://github.com/facebookresearch/audiocraft.git
124
+ ```
125
+
126
+ 2. Make sure to have [`ffmpeg`](https://ffmpeg.org/download.html) installed:
127
+ ```
128
+ apt get install ffmpeg
129
+ ```
130
+
131
+ 3. Run the following Python code:
132
+
133
+ ```py
134
+ from audiocraft.models import MusicGen
135
+ from audiocraft.data.audio import audio_write
136
+
137
+ model = MusicGen.get_pretrained("large")
138
+ model.set_generation_params(duration=8) # generate 8 seconds.
139
+
140
+ descriptions = ["happy rock", "energetic EDM"]
141
+
142
+ wav = model.generate(descriptions) # generates 2 samples.
143
+
144
+ for idx, one_wav in enumerate(wav):
145
+ # Will save under {idx}.wav, with loudness normalization at -14 db LUFS.
146
+ audio_write(f'{idx}', one_wav.cpu(), model.sample_rate, strategy="loudness")
147
+ ```
148
+
149
+ ## Model details
150
+
151
+ **Organization developing the model:** The FAIR team of Meta AI.
152
+
153
+ **Model date:** MusicGen was trained between April 2023 and May 2023.
154
+
155
+ **Model version:** This is the version 1 of the model.
156
+
157
+ **Model type:** MusicGen consists of an EnCodec model for audio tokenization, an auto-regressive language model based on the transformer architecture for music modeling. The model comes in different sizes: 300M, 1.5B and 3.3B parameters ; and two variants: a model trained for text-to-music generation task and a model trained for melody-guided music generation.
158
+
159
+ **Paper or resources for more information:** More information can be found in the paper [Simple and Controllable Music Generation](https://arxiv.org/abs/2306.05284).
160
+
161
+ **Citation details:**
162
+ ```
163
+ @misc{copet2023simple,
164
+ title={Simple and Controllable Music Generation},
165
+ author={Jade Copet and Felix Kreuk and Itai Gat and Tal Remez and David Kant and Gabriel Synnaeve and Yossi Adi and Alexandre Défossez},
166
+ year={2023},
167
+ eprint={2306.05284},
168
+ archivePrefix={arXiv},
169
+ primaryClass={cs.SD}
170
+ }
171
+ ```
172
+
173
+ **License:** Code is released under MIT, model weights are released under CC-BY-NC 4.0.
174
+
175
+ **Where to send questions or comments about the model:** Questions and comments about MusicGen can be sent via the [Github repository](https://github.com/facebookresearch/audiocraft) of the project, or by opening an issue.
176
+
177
+ ## Intended use
178
+ **Primary intended use:** The primary use of MusicGen is research on AI-based music generation, including:
179
+
180
+ - Research efforts, such as probing and better understanding the limitations of generative models to further improve the state of science
181
+ - Generation of music guided by text or melody to understand current abilities of generative AI models by machine learning amateurs
182
+
183
+ **Primary intended users:** The primary intended users of the model are researchers in audio, machine learning and artificial intelligence, as well as amateur seeking to better understand those models.
184
+
185
+ **Out-of-scope use cases:** The model should not be used on downstream applications without further risk evaluation and mitigation. The model should not be used to intentionally create or disseminate music pieces that create hostile or alienating environments for people. This includes generating music that people would foreseeably find disturbing, distressing, or offensive; or content that propagates historical or current stereotypes.
186
+
187
+ ## Metrics
188
+
189
+ **Models performance measures:** We used the following objective measure to evaluate the model on a standard music benchmark:
190
+
191
+ - Frechet Audio Distance computed on features extracted from a pre-trained audio classifier (VGGish)
192
+ - Kullback-Leibler Divergence on label distributions extracted from a pre-trained audio classifier (PaSST)
193
+ - CLAP Score between audio embedding and text embedding extracted from a pre-trained CLAP model
194
+
195
+ Additionally, we run qualitative studies with human participants, evaluating the performance of the model with the following axes:
196
+
197
+ - Overall quality of the music samples;
198
+ - Text relevance to the provided text input;
199
+ - Adherence to the melody for melody-guided music generation.
200
+
201
+ More details on performance measures and human studies can be found in the paper.
202
+
203
+ **Decision thresholds:** Not applicable.
204
+
205
+ ## Evaluation datasets
206
+
207
+ The model was evaluated on the [MusicCaps benchmark](https://www.kaggle.com/datasets/googleai/musiccaps) and on an in-domain held-out evaluation set, with no artist overlap with the training set.
208
+
209
+ ## Training datasets
210
+
211
+ The model was trained on licensed data using the following sources: the [Meta Music Initiative Sound Collection](https://www.fb.com/sound), [Shutterstock music collection](https://www.shutterstock.com/music) and the [Pond5 music collection](https://www.pond5.com/). See the paper for more details about the training set and corresponding preprocessing.
212
+
213
+ ## Evaluation results
214
+
215
+ Below are the objective metrics obtained on MusicCaps with the released model. Note that for the publicly released models, we had all the datasets go through a state-of-the-art music source separation method, namely using the open source [Hybrid Transformer for Music Source Separation](https://github.com/facebookresearch/demucs) (HT-Demucs), in order to keep only the instrumental part. This explains the difference in objective metrics with the models used in the paper.
216
+
217
+ | Model | Frechet Audio Distance | KLD | Text Consistency | Chroma Cosine Similarity |
218
+ |---|---|---|---|---|
219
+ | facebook/musicgen-small | 4.88 | 1.42 | 0.27 | - |
220
+ | facebook/musicgen-medium | 5.14 | 1.38 | 0.28 | - |
221
+ | **facebook/musicgen-large** | 5.48 | 1.37 | 0.28 | - |
222
+ | facebook/musicgen-melody | 4.93 | 1.41 | 0.27 | 0.44 |
223
+
224
+ More information can be found in the paper [Simple and Controllable Music Generation](https://arxiv.org/abs/2306.05284), in the Results section.
225
+
226
+ ## Limitations and biases
227
+
228
+ **Data:** The data sources used to train the model are created by music professionals and covered by legal agreements with the right holders. The model is trained on 20K hours of data, we believe that scaling the model on larger datasets can further improve the performance of the model.
229
+
230
+ **Mitigations:** Vocals have been removed from the data source using corresponding tags, and then using a state-of-the-art music source separation method, namely using the open source [Hybrid Transformer for Music Source Separation](https://github.com/facebookresearch/demucs) (HT-Demucs).
231
+
232
+ **Limitations:**
233
+
234
+ - The model is not able to generate realistic vocals.
235
+ - The model has been trained with English descriptions and will not perform as well in other languages.
236
+ - The model does not perform equally well for all music styles and cultures.
237
+ - The model sometimes generates end of songs, collapsing to silence.
238
+ - It is sometimes difficult to assess what types of text descriptions provide the best generations. Prompt engineering may be required to obtain satisfying results.
239
+
240
+ **Biases:** The source of data is potentially lacking diversity and all music cultures are not equally represented in the dataset. The model may not perform equally well on the wide variety of music genres that exists. The generated samples from the model will reflect the biases from the training data. Further work on this model should include methods for balanced and just representations of cultures, for example, by scaling the training data to be both diverse and inclusive.
241
+
242
+ **Risks and harms:** Biases and limitations of the model may lead to generation of samples that may be considered as biased, inappropriate or offensive. We believe that providing the code to reproduce the research and train new models will allow to broaden the application to new and more representative data.
243
+
244
+ **Use cases:** Users must be aware of the biases, limitations and risks of the model. MusicGen is a model developed for artificial intelligence research on controllable music generation. As such, it should not be used for downstream applications without further investigation and mitigation of risks.