# How the Spotify-Saver API Configuration Class Manages Output Directory and Format Settings

> Learn how the Spotify-Saver APIConfig class centralizes settings for output directory and audio formats. Easily customize paths and formats at runtime for your Spotify downloads.

- Repository: [Gabriel Baute/spotify-saver](https://github.com/gabrielbaute/spotify-saver)
- Tags: internals
- Published: 2026-03-02

---

**The `APIConfig` class in [`spotifysaver/api/config.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/api/config.py) centralizes FastAPI-specific settings, defining default paths and supported audio formats while allowing runtime customization via the `SPOTIFYSAVER_OUTPUT_DIR` environment variable.**

The `gabrielbaute/spotify-saver` repository implements a dedicated configuration layer to control where downloaded tracks are stored and which audio containers are permitted. At the heart of this layer lies the `APIConfig` class, which encapsulates default values and environment-driven overrides for the FastAPI application. Understanding how this API configuration class manages settings ensures you can customize file destinations and format restrictions without modifying core application logic.

## Default Output Directory and Format Settings

The `APIConfig` class defines sensible defaults for file system operations and audio handling. These constants serve as fallback values when users do not provide explicit overrides.

### Output Directory Management

The `DEFAULT_OUTPUT_DIR` class attribute in [`spotifysaver/api/config.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/api/config.py) specifies `"Music"` as the base folder for all saved tracks. According to the source code, this default is defined at line 14:

```python
DEFAULT_OUTPUT_DIR = "Music"

```

To retrieve the effective output directory at runtime, the class provides the `get_output_dir()` class method at lines 26-30. This method implements a priority lookup, checking for the `SPOTIFYSAVER_OUTPUT_DIR` environment variable before falling back to the hard-coded default:

```python
@classmethod
def get_output_dir(cls):
    return os.environ.get("SPOTIFYSAVER_OUTPUT_DIR", cls.DEFAULT_OUTPUT_DIR)

```

This approach allows users to customize the destination folder without code changes by exporting the variable before running the service:

```bash
export SPOTIFYSAVER_OUTPUT_DIR="/path/to/my/music"

```

### Audio Format Constraints

Format handling is declarative within `APIConfig`. The `ALLOWED_FORMATS` list defined at line 18 restricts valid download containers to `["m4a", "mp3"]`, while `DEFAULT_FORMAT` at line 19 supplies `"m4a"` as the fallback for API calls omitting the format parameter:

```python
ALLOWED_FORMATS = ["m4a", "mp3"]
DEFAULT_FORMAT = "m4a"

```

Validation of user-provided formats occurs elsewhere in the codebase, which checks requested values against `APIConfig.ALLOWED_FORMATS` before proceeding with downloads.

## Environment Variable Integration

The API configuration class manages settings through environment variables to support containerized deployments and development workflows. When `get_output_dir()` is invoked, it reads `SPOTIFYSAVER_OUTPUT_DIR` at call time, ensuring changes take effect immediately without restarting the Python process.

This environment-driven approach is mirrored in the broader application configuration found in [`spotifysaver/config/setting_environment.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/config/setting_environment.py). The generic `Config` class defined there also exposes an `OUTPUT_DIR` attribute that reads the same environment variable, defaulting to `"Music"` at lines 56-58. This dual exposure ensures consistency between the API layer and internal services.

## Practical Code Examples

The following examples demonstrate how to interact with the API configuration class programmatically.

### Retrieve the Effective Output Directory

```python
from spotifysaver.api.config import APIConfig

output_dir = APIConfig.get_output_dir()
print(f"Music will be saved to: {output_dir}")

# If SPOTIFYSAVER_OUTPUT_DIR is set, its value is printed; otherwise "Music"

```

### Validate Requested Formats

```python
from spotifysaver.api.config import APIConfig

def is_format_supported(fmt: str) -> bool:
    return fmt.lower() in APIConfig.ALLOWED_FORMATS

print(is_format_supported("mp3"))   # True

print(is_format_supported("flac"))  # False (not in ALLOWED_FORMATS)

```

### Resolve Format with Fallback

```python
from spotifysaver.api.config import APIConfig

def resolve_format(requested: str | None) -> str:
    if requested and requested.lower() in APIConfig.ALLOWED_FORMATS:
        return requested.lower()
    return APIConfig.DEFAULT_FORMAT  # falls back to "m4a"

print(resolve_format(None))        # "m4a"

print(resolve_format("mp3"))       # "mp3"

```

## Summary

- The `APIConfig` class in [`spotifysaver/api/config.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/api/config.py) defines default settings for output directories (`"Music"`) and supported audio formats (`m4a`, `mp3`).
- **Environment variables** take precedence: `SPOTIFYSAVER_OUTPUT_DIR` overrides the default output directory when set.
- The `get_output_dir()` class method provides a runtime lookup mechanism that prefers environment configuration over hard-coded defaults.
- Format restrictions are enforced through the `ALLOWED_FORMATS` and `DEFAULT_FORMAT` class attributes.
- Configuration parity is maintained between the API layer and core services via [`spotifysaver/config/setting_environment.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/config/setting_environment.py).

## Frequently Asked Questions

### How do I change the default output directory for downloaded music?

Export the `SPOTIFYSAVER_OUTPUT_DIR` environment variable with your desired path before starting the application. The `APIConfig.get_output_dir()` method automatically detects this variable and uses it instead of the default `"Music"` folder.

### What audio formats does the API support?

According to the source code in [`spotifysaver/api/config.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/api/config.py), the API configuration class manages settings for two supported formats: `m4a` and `mp3`. These are defined in the `ALLOWED_FORMATS` list at line 18, with `m4a` serving as the `DEFAULT_FORMAT` when callers do not specify a preference.

### Where does format validation occur if not in APIConfig?

While `APIConfig` defines the `ALLOWED_FORMATS` whitelist at line 18, the actual validation logic resides in the download service layer. This separation of concerns allows the configuration class to remain a simple data container while business logic handles request sanitization against `APIConfig.ALLOWED_FORMATS`.

### Is the configuration shared between the API and background services?

Yes. The `Config` class in [`spotifysaver/config/setting_environment.py`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/config/setting_environment.py) mirrors the API configuration by reading the same `SPOTIFYSAVER_OUTPUT_DIR` environment variable at lines 56-58. This ensures that both the FastAPI endpoints and internal processing services write files to consistent locations.