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

The APIConfig class in 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 specifies "Music" as the base folder for all saved tracks. According to the source code, this default is defined at line 14:

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:

@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:

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:

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. 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

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

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

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 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.

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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}