ESPnet Model Zoo

Utilities managing the pretrained models created by ESPnet.

• Zenodo community: https://zenodo.org/communities/espnet/
• Registered models: table.csv

Install

pip install torch
pip install espnet_model_zoo

Python API for inference

See the following section about model_name

ASR

import soundfile
from espnet_model_zoo.downloader import ModelDownloader
from espnet2.bin.asr_inference import Speech2Text
d = ModelDownloader()
speech2text = Speech2Text(**d.download_and_unpack("model_name"))

speech, rate = soundfile.read("speech.wav")
nbests = speech2text(speech)
text, *_ = nbests[0]
print(text)

TTS

import soundfile
from espnet_model_zoo.downloader import ModelDownloader
from espnet2.bin.tts_inference import Text2Speech
d = ModelDownloader()
text2speech = Text2Speech(**d.download_and_unpack("model_name"))

speech, *_ = text2speech("foobar")
soundfile.write("out.wav", speech.numpy(), text2speech.fs, "PCM_16")

Instruction for ModelDownloader

from espnet_model_zoo.downloader import ModelDownloader
d = ModelDownloader("~/.cache/espnet")  # Specify cachedir
d = ModelDownloader()  # <module_dir> is used as cachedir by default

To obtain a model, you need to give a model name, which is listed in table.csv.

>>> d.download_and_unpack("kamo-naoyuki/mini_an4_asr_train_raw_bpe_valid.acc.best")
{"asr_train_config": <config path>, "asr_model_file": <model path>, ...}

Note that if the model already exists, you can skip downloading and unpacking.

You can also get a model with certain conditions.

d.download_and_unpack(task="asr", corpus="wsj")

If multiple models are found with the condition, the last model is selected. You can also specify the condition using "version" option.

d.download_and_unpack(task="asr", corpus="wsj", version=-1)  # Get the last model
d.download_and_unpack(task="asr", corpus="wsj", version=-2)  # Get previous model

You can also obtain it from the URL directly.

d.download_and_unpack("https://zenodo.org/record/...")

If you need to use a local model file using this API, you can also give it.

d.download_and_unpack("./some/where/model.zip")

In this case, the contents are also expanded in the cache directory, but the model is identified by the file path, so if you move the model to somewhere and unpack again, it's treated as another model, thus the contents are expanded again at another place.

Query model names

You can view the model names from our Zenodo community, https://zenodo.org/communities/espnet/, or using query(). All information are written in table.csv.

d.query("name")

You can also show them with specifying certain conditions.

d.query("name", task="asr")

Command line tools

• espnet_model_zoo_query

  # Query model name
  espnet_model_zoo_query task=asr corpus=wsj 
  # Show all model name
  espnet_model_zoo_query
  # Query the other key
  espnet_model_zoo_query --key url task=asr corpus=wsj 

• espnet_model_zoo_download

  espnet_model_zoo_download <model_name>  # Print the path of the downloaded file
  espnet_model_zoo_download --unpack true <model_name>   # Print the path of unpacked files

• espnet_model_zoo_upload

  export ACCESS_TOKEN=<access_token>
  espnet_zenodo_upload \
      --file <packed_model> \
      --title <title> \
      --description <description> \
      --creator_name <your-git-account>

Use pretrained model in ESPnet recipe

# e.g. ASR WSJ task
git clone https://github.com/espnet/espnet
cd egs2/wsj/asr1
pip install -e .
cd egs2/wsj/asr1
./run.sh --skip_data_prep false --skip_train true --download_model kamo-naoyuki/wsj

Register your model

1. Upload your model to Zenodo

   You need to signup to Zenodo and create an access token to upload models. You can upload your own model by using espnet_model_zoo_upload command freely, but we normally upload a model using recipes.

2. Create a Pull Request to modify table.csv

   You need to append your record at the last line.

3. (Administrator does) Increment the third version number of setup.py, e.g. 0.0.3 -> 0.0.4

4. (Administrator does) Release new version

Update your model

If your model has some troubles, please modify the record at Zenodo directly or reupload a corrected file using espnet_zenodo_upload as another record.