Pretrained models#

Deprecated since version 3.4: With the shift towards models that can be distributed on Hugging Face, the model functionality related to download and saving models will be deprecated in 3.4, with a scheduled removal in MFA 5.0 (sometime in 2027). See MFA model versions for more details on the changes to models and distribution.

The command for interacting with MFA models is mfa model. The subcommands allow for inspecting currently saved pretrained models, downloading ones from MFA’s model repo, and saving models you have trained to be used with a simple name rather than the full path each time.

Following installation of MFA, mfa model list acoustic will not list any models. If you want to download the default English model trained on LibriSpeech, you can run mfa model download acoustic english_us_arpa. At which point, the previous list command will output “english_us_arpa” as an option. When referring to an acoustic model in another MFA command, rather than the full path to the acoustic model, you can now supply just english_us_arpa and MFA will resolve it to the saved path.

Similarly, if you train a new model, you can run mfa model save acoustic /path/where/the/model/was/saved.zip, then this model will be available via saved in the future. The name defaults to whatever the archive is called without the directory or extension. You can modify this name with the --name NEWNAME option

There are a number of pretrained models for aligning and generating pronunciation dictionaries. The command for downloading these is mfa model download <model_type> where model_type is one of acoustic, g2p, or dictionary.

Note

Please see the MFA Models site for information and statistics about various models.

Command reference#

mfa model#

Inspect, download, and save pretrained MFA models and dictionaries

Usage

mfa model [OPTIONS] COMMAND [ARGS]...

Options

-h, --help#: Show this message and exit.

add_words#

Add words from one pronunciation dictionary to another pronunciation dictionary, so long as the new pronunciations do not contain any new phones

Usage

mfa model add_words [OPTIONS] DICTIONARY_PATH NEW_PRONUNCIATIONS_PATH

Options

-h, --help#: Show this message and exit.

-p, --profile <profile>#: Configuration profile to use, defaults to “global”

-t, --temporary_directory <temporary_directory>#: Set the default temporary directory, default is /home/docs/Documents/MFA

-j, --num_jobs <num_jobs>#: Set the number of processes to use by default, defaults to 3

--clean, --no_clean#: Remove files from previous runs, default is True

--final_clean, --no_final_clean#: Remove temporary files at the end of run, default is False

-v, --verbose, -nv, --no_verbose#: Output debug messages, default is False

-q, --quiet, -nq, --no_quiet#: Suppress all output messages (overrides verbose), default is False

--overwrite, --no_overwrite#: Overwrite output files when they exist, default is False

--use_mp, --no_use_mp#: Turn on/off multiprocessing. Multiprocessing is recommended will allow for faster executions.

--use_threading, --no_use_threading#: Use threading library rather than multiprocessing library. Multiprocessing is recommended will allow for faster executions.

-d, --debug, -nd, --no_debug#: Run extra steps for debugging issues, default is False

--use_postgres, --no_use_postgres#: Use postgres instead of sqlite for extra functionality, default is False

--single_speaker#: Single speaker mode creates multiprocessing splits based on utterances rather than speakers. This mode also disables speaker adaptation equivalent to --uses_speaker_adaptation false.

--textgrid_cleanup, --cleanup_textgrids, --no_textgrid_cleanup, --no_cleanup_textgrids#: Turn on/off post-processing of TextGrids that cleans up silences and recombines compound words and clitics.

Arguments

DICTIONARY_PATH#: Required argument

NEW_PRONUNCIATIONS_PATH#: Required argument

create_hf_model#

Create a Hugging Face-compatible model from legacy models

Usage

mfa model create_hf_model [OPTIONS] ACOUSTIC_MODEL_PATH DICTIONARY_PATH
                          OUTPUT_MODEL_PATH

Options

--g2p_model_path <g2p_model_path>#: Path to G2P model to include.

--metadata_path <metadata_path>#: Path to additional metadata json file to use for creating the model card.

-c, --config_path <config_path>#: Path to config file to use for training. See MontrealCorpusTools/mfa-models for examples.

-h, --help#: Show this message and exit.

-p, --profile <profile>#: Configuration profile to use, defaults to “global”

-t, --temporary_directory <temporary_directory>#: Set the default temporary directory, default is /home/docs/Documents/MFA

-j, --num_jobs <num_jobs>#: Set the number of processes to use by default, defaults to 3

--clean, --no_clean#: Remove files from previous runs, default is True

--final_clean, --no_final_clean#: Remove temporary files at the end of run, default is False

-v, --verbose, -nv, --no_verbose#: Output debug messages, default is False

-q, --quiet, -nq, --no_quiet#: Suppress all output messages (overrides verbose), default is False

--overwrite, --no_overwrite#: Overwrite output files when they exist, default is False

--use_mp, --no_use_mp#: Turn on/off multiprocessing. Multiprocessing is recommended will allow for faster executions.

--use_threading, --no_use_threading#: Use threading library rather than multiprocessing library. Multiprocessing is recommended will allow for faster executions.

-d, --debug, -nd, --no_debug#: Run extra steps for debugging issues, default is False

--use_postgres, --no_use_postgres#: Use postgres instead of sqlite for extra functionality, default is False

--single_speaker#: Single speaker mode creates multiprocessing splits based on utterances rather than speakers. This mode also disables speaker adaptation equivalent to --uses_speaker_adaptation false.

--textgrid_cleanup, --cleanup_textgrids, --no_textgrid_cleanup, --no_cleanup_textgrids#: Turn on/off post-processing of TextGrids that cleans up silences and recombines compound words and clitics.

Arguments

ACOUSTIC_MODEL_PATH#: Required argument

DICTIONARY_PATH#: Required argument

OUTPUT_MODEL_PATH#: Required argument

download#

Download pretrained models from the MFA repository. If no model names are specified, the list of all downloadable models of the given model type will be printed.

Usage

mfa model download [OPTIONS]
                   {acoustic|dictionary|g2p|ivector|language_model|tokenizer}
                   [MODEL_NAME]...

Options

--github_token <github_token>#: Personal access token to use for requests to GitHub to increase rate limit.

--version <version>#: Specific version of model to download rather than the latest.

-f, --force, --ignore_cache#: Flag to ignore existing downloaded models and force a re-download.

-h, --help#: Show this message and exit.

Arguments

MODEL_TYPE#: Required argument

MODEL_NAME#: Optional argument(s)

inspect#

Inspect a model and print out its metadata.

Usage

mfa model inspect [OPTIONS]
                  {acoustic|dictionary|g2p|ivector|language_model|tokenizer}
                  MODEL

Options

-h, --help#: Show this message and exit.

Arguments

MODEL_TYPE#: Required argument

MODEL#: Required argument

list#

List of locally saved models.

Usage

mfa model list [OPTIONS]
               {acoustic|dictionary|g2p|ivector|language_model|tokenizer}

Options

-h, --help#: Show this message and exit.

Arguments

MODEL_TYPE#: Required argument

save#

Save a model to pretrained folder for later use

Parameters#

path: Path: Path to model
model_type: str: Type of model

Usage

mfa model save [OPTIONS]
               {acoustic|dictionary|g2p|ivector|language_model|tokenizer} PATH

Options

--name <name>#: Name to use as reference (defaults to the name of the zip file).

--overwrite, --no_overwrite#: Overwrite output files when they exist, default is False

-h, --help#: Show this message and exit.

Arguments

MODEL_TYPE#: Required argument

PATH#: Required argument

upload#

Upload an alignment model to Hugging Face Hub

Parameters#

local_path: Path: Path to model
repo_id: str: Repo id on Hugging Face Hub

Usage

mfa model upload [OPTIONS] LOCAL_PATH REPO_ID

Options

--version <version>#: Version to tag upload with.

--overwrite_version <overwrite_version>#: Flag to overwrite update version tag to the latest commit.

-h, --help#: Show this message and exit.

Arguments

LOCAL_PATH#: Required argument

REPO_ID#: Required argument