Environment:Facebookresearch Audiocraft AudioCraft Environment Variables

Knowledge Sources	AudioCraft
Domains	Infrastructure, Configuration
Last Updated	2026-02-13 23:00 GMT

Overview

Configuration environment variables used by AudioCraft to control cluster detection, team settings, experiment directories, and model caching.

Description

AudioCraft uses a set of AUDIOCRAFT_* environment variables to configure its runtime behavior across different compute clusters (AWS, FAIR, RSC, macOS). These variables override auto-detected defaults from the AudioCraftEnvironment singleton class. The cluster type is auto-detected from system information (hostname FQDN, kernel release), but can be overridden for custom deployments.

All variables are optional. When unset, AudioCraft falls back to auto-detection and default configuration files in config/teams/.

Usage

Set these environment variables when deploying AudioCraft on custom clusters, when you need to override auto-detected settings, or when sharing experiment state across team members via a reference directory.

System Requirements

Category	Requirement	Notes
OS	Any supported platform	Variables work across all cluster types

Dependencies

No additional dependencies beyond the core AudioCraft environment.

Credentials

The following environment variables must be set as needed:

• AUDIOCRAFT_TEAM: Team name for selecting cluster configuration (default: "default"). Maps to a YAML file in config/teams/{team}.yaml.
• AUDIOCRAFT_CLUSTER: Override auto-detected cluster type. Valid values: aws, fair, rsc, darwin, default.
• AUDIOCRAFT_CONFIG: Path to custom teams YAML configuration file. Overrides config/teams/{team}.yaml.
• AUDIOCRAFT_DORA_DIR: Override Dora experiment tracking output directory.
• AUDIOCRAFT_REFERENCE_DIR: Override shared reference directory for model signatures and files.
• AUDIOCRAFT_CACHE_DIR: Override cache directory for downloaded HuggingFace model checkpoints.

Quick Install

# Example: Configure for a custom cluster
export AUDIOCRAFT_TEAM=my_team
export AUDIOCRAFT_CLUSTER=default
export AUDIOCRAFT_DORA_DIR=/data/experiments/audiocraft
export AUDIOCRAFT_REFERENCE_DIR=/shared/models/audiocraft
export AUDIOCRAFT_CACHE_DIR=/data/cache/audiocraft

Code Evidence

Team selection from audiocraft/environment.py:51:

self.team: str = os.getenv("AUDIOCRAFT_TEAM", self.DEFAULT_TEAM)

Cluster override from audiocraft/environment.py:53-54:

cluster = os.getenv(
    "AUDIOCRAFT_CLUSTER", cluster_type.value
)

Config path override from audiocraft/environment.py:60-64:

config_path = os.getenv(
    "AUDIOCRAFT_CONFIG",
    Path(__file__)
    .parent.parent.joinpath("config/teams", self.team)
    .with_suffix(".yaml"),
)

Dora directory override from audiocraft/environment.py:109:

dora_dir = os.getenv("AUDIOCRAFT_DORA_DIR", cluster_config["dora_dir"])

Reference directory override from audiocraft/environment.py:119:

return Path(os.getenv("AUDIOCRAFT_REFERENCE_DIR", cluster_config["reference_dir"]))

Cache directory for model downloads from audiocraft/models/loaders.py:37:

def get_audiocraft_cache_dir() -> tp.Optional[str]:
    return os.environ.get('AUDIOCRAFT_CACHE_DIR', None)

Cluster auto-detection from audiocraft/utils/cluster.py:27-42:

def _guess_cluster_type() -> ClusterType:
    uname = os.uname()
    fqdn = socket.getfqdn()
    if uname.sysname == "Linux" and (uname.release.endswith("-aws") or ".ec2" in fqdn):
        return ClusterType.AWS
    if fqdn.endswith(".fair"):
        return ClusterType.FAIR
    if fqdn.endswith(".facebook.com"):
        return ClusterType.RSC
    if uname.sysname == "Darwin":
        return ClusterType.LOCAL_DARWIN
    return ClusterType.DEFAULT

Common Errors

Error Message	Cause	Solution
KeyError: 'default' in environment config	Team YAML file missing cluster section	Ensure config/teams/{team}.yaml has a section for the detected cluster type
AssertionError: Reference directory does not exist	AUDIOCRAFT_REFERENCE_DIR points to non-existent path	Create the directory or update the env var
FileNotFoundError on config load	AUDIOCRAFT_CONFIG points to missing file	Verify the path exists and contains valid YAML

Compatibility Notes

• Cluster auto-detection: Works for AWS (kernel ending in -aws or FQDN containing .ec2), FAIR (.fair FQDN), RSC (.facebook.com FQDN), and macOS (Darwin sysname).
• Custom clusters: Set AUDIOCRAFT_CLUSTER=default and provide a matching config section.
• Reference paths: Paths starting with //reference are auto-resolved to the configured reference directory.
• Dataset mappers: Regex-based path rewriting rules in team config allow sharing manifests across clusters.

Related Pages

• Implementation:Facebookresearch_Audiocraft_AudioCraftEnvironment