How to Configure Multi-Instance Providers for Multiple Accounts in Music Assistant

Music Assistant supports running multiple instances of the same provider simultaneously by setting "multi_instance": true in the provider's manifest.json and supplying a unique instance_id for each account configuration.

The music-assistant/server repository enables users to connect multiple accounts from the same streaming service through its multi-instance provider architecture. When you configure multi-instance providers for multiple accounts, the system creates isolated provider objects that route playback, metadata retrieval, and library indexing to the correct credentials.

Understanding Multi-Instance Provider Architecture

Manifest Configuration

Each provider’s capabilities are declared in music_assistant/providers/<provider>/manifest.json. The multi_instance boolean flag determines whether the framework allows multiple concurrent instances. For example, the Spotify provider sets this flag at line 11 of its manifest file, signaling that users may add several Spotify accounts.

Instance Identification and Validation

The ProviderManifest dataclass in music_assistant/models/provider.py defines the multi_instance attribute that drives this behavior. When parsing configurations, music_assistant/controllers/config.py enforces validation around line 1025, ensuring that entries for multi-instance providers include a distinct instance_id field to prevent collision between accounts.

Provider Registration Logic

During startup, music_assistant/mass.py handles provider instantiation at approximately line 969. The registration logic evaluates the condition existing and prov_manifest and not prov_manifest.multi_instance.

• For single-instance providers, this check blocks duplicate registrations.
• For multi-instance providers, the system bypasses this restriction and creates a new MusicProvider object for every unique instance_id encountered in the configuration database.

Library Item Mapping

After all providers load, music_assistant/controllers/music.py executes correct_multi_instance_provider_mappings() at approximately line 3483. This method constructs a lookup table that maps library items—such as tracks, albums, and playlists—to their specific provider instances. This ensures that a "Discover Weekly" playlist from your work account routes through the correct provider instance rather than your personal account.

How to Configure Multi-Instance Providers via API

To programmatically add multiple accounts for the same provider, create configuration entries with unique instance_id values.

Adding a second Spotify account:

await mass.config_entries.create(
    domain="spotify",
    data={
        "username": "user2@example.com",
        "password": "secure-token",
        "instance_id": "spotify-work"
    }
)

Retrieving a specific instance:

provider = await mass.get_provider(
    domain="spotify",
    instance_id="spotify-work"
)
await provider.login()

Accessing provider-specific media:

playlist = await provider.get_playlist_by_name("My Favorites")
await music_controller.play_media_item(playlist.tracks[0])

Summary

• Set "multi_instance": true in the provider's manifest.json to enable support for multiple accounts per the ProviderManifest dataclass.
• Supply a unique instance_id for each account configuration to prevent registration collisions.
• The registration logic in music_assistant/mass.py (line ~969) creates isolated provider instances by checking existing and prov_manifest and not prov_manifest.multi_instance.
• Use correct_multi_instance_provider_mappings() in music_assistant/controllers/music.py (line ~3483) to maintain proper routing between library items and their respective provider instances.
• Access specific instances programmatically using await mass.get_provider(domain, instance_id).

Frequently Asked Questions

Can I add multiple accounts for any provider in Music Assistant?

No. Only providers that declare "multi_instance": true in their manifest.json support multiple concurrent accounts. Single-instance providers will reject additional configuration entries if an existing instance is already registered for that domain.

What happens if I use the same instance_id for two different accounts?

The system treats duplicate instance_id values as identical instances. In music_assistant/mass.py, the registration logic skips configurations that would create duplicates, potentially ignoring the second account's credentials and preventing login.

How do I access a specific account when using the Music Assistant API?

Use the get_provider() method with both the domain and instance_id parameters: await mass.get_provider("spotify", instance_id="personal-account"). This returns the specific provider instance associated with those credentials, allowing you to interact with that account's library.

Do library items from different accounts remain separate?

Yes. The correct_multi_instance_provider_mappings() method in music_assistant/controllers/music.py maintains discrete mappings for each provider instance. Tracks, playlists, and metadata from your work account remain distinct from your personal account, preventing cross-contamination between libraries.

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