How to Set Up Model Registry URL Override in FluidAudio for Offline Mirrors

Override the model registry URL in FluidAudio by setting ModelRegistry.baseURL programmatically before manager initialization, or by exporting the REGISTRY_URL (or MODEL_REGISTRY_URL) environment variable to redirect all model downloads to your internal mirror.

When deploying fluidinference/fluidaudio in air‑gapped environments, you must redirect model downloads away from the default HuggingFace servers to an internal host. The ModelRegistry component provides a centralized mechanism to configure a model registry URL override without modifying download logic throughout the codebase.

How the Model Registry URL System Works

The registry logic lives in Sources/FluidAudio/ModelRegistry.swift. Lines 30‑38 define the baseURL property, which defaults to https://huggingface.co when no override is present. Once you change this value, every URL‑building helper in lines 46‑85—including apiModels(), resolveModel(), apiDatasets(), resolveDataset(), and resolveDatasetBase()—automatically prepends your custom host to all endpoint paths.

Three Methods to Override the Model Registry URL

FluidAudio evaluates these options in strict priority order:

1. Programmatic Override via ModelRegistry.baseURL

Set the static property in Swift before any manager creates or downloads a model. This approach is recommended for macOS or iOS applications where you control the app lifecycle.

import FluidAudio

// Point to your internal mirror before instantiating managers
ModelRegistry.baseURL = "https://my-internal-mirror.example.com"

// Subsequent managers will download from the mirror
let diarizer = DiarizerManager()

2. REGISTRY_URL Environment Variable

If no programmatic value exists, FluidAudio checks the REGISTRY_URL variable at runtime. This method is ideal for CI/CD pipelines and command‑line usage.

export REGISTRY_URL=https://my-internal-mirror.example.com
swift run fluidaudio transcribe meeting.wav

3. MODEL_REGISTRY_URL Environment Variable (Fallback)

When REGISTRY_URL is absent, FluidAudio falls back to MODEL_REGISTRY_URL. This secondary option ensures compatibility with legacy deployment scripts.

export MODEL_REGISTRY_URL=https://backup-mirror.example.com
swift run fluidaudio diarization-benchmark --auto-download

Configuring Proxy Settings for Offline Mirrors

If your internal mirror sits behind a corporate proxy, the ModelRegistry respects standard https_proxy and http_proxy environment variables. The methods configureProxySettings() and parseProxyURL() (both in Sources/FluidAudio/ModelRegistry.swift) read these variables and apply them to the URLSession returned by configuredSession().

export https_proxy=http://proxy.corp.com:8080
export http_proxy=http://proxy.corp.com:8080
export REGISTRY_URL=https://my-internal-mirror.example.com

swift run fluidaudio transcribe audio.wav

Implementation Examples

Xcode Scheme Configuration

For local development in Xcode:

1. Open Product → Scheme → Edit Scheme → Run → Arguments.
2. Switch to the Environment Variables tab.
3. Add REGISTRY_URL with the value https://my-internal-mirror.example.com.
4. Close the dialog and run your target.

Swift Application Bootstrap

import FluidAudio

func applicationDidFinishLaunching(_ notification: Notification) {
    // Set mirror before any audio processing begins
    ModelRegistry.baseURL = "https://artifactory.internal.com/hf-mirror"
    
    // Initialize managers after registry is configured
    let transcriptionManager = TranscriptionManager()
}

Complete Offline Deployment Script

#!/bin/bash

# setup-offline.sh

export REGISTRY_URL="https://airgap-models.corp.internal"
export https_proxy="http://proxy.corp.internal:3128"

# Validate FluidAudio can reach the mirror

swift run fluidaudio list-models --verify-registry

Summary

• Programmatic control is achieved by setting ModelRegistry.baseURL in Swift before any manager instantiation (lines 30‑38 of ModelRegistry.swift).
• Environment variables provide flexible deployment options: REGISTRY_URL takes precedence over MODEL_REGISTRY_URL if both are present.
• Automatic propagation occurs across all URL builders (resolveModel, apiDatasets, etc.) once the base URL is changed.
• Proxy support is handled automatically via https_proxy/http_proxy variables, parsed by configureProxySettings() and applied to the shared URLSession.

Frequently Asked Questions

What is the default model registry URL in FluidAudio?

If you do not provide a model registry URL override, FluidAudio defaults to https://huggingface.co. This hard‑coded value is defined in the baseURL property of Sources/FluidAudio/ModelRegistry.swift (lines 30‑38).

Which environment variable takes precedence for registry overrides?

REGISTRY_URL has higher priority than MODEL_REGISTRY_URL. FluidAudio checks for REGISTRY_URL first; only if it is absent does the system fall back to MODEL_REGISTRY_URL. If neither variable is set, the default HuggingFace URL is used.

How does FluidAudio handle corporate proxy settings for model downloads?

The ModelRegistry class automatically detects https_proxy and http_proxy environment variables through its parseProxyURL() helper (called within configureProxySettings()). These settings configure the URLSession used by all download methods, routing traffic through your corporate proxy before reaching the mirrored registry.

Can I switch registry URLs at runtime after models have started downloading?

You can change ModelRegistry.baseURL at any time, but the change only affects subsequent download requests. Any model downloads already in progress will continue using the endpoint that was active when the URLSession task began. For consistent behavior, set the override once during application startup or before running CLI commands.

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