How to Self-Host Airsonic-Advanced with Docker

What Is Airsonic-Advanced?

If you need a Subsonic-compatible music server that handles transcoding, multi-user access, and DLNA playback without depending on a third party, Airsonic-Advanced is a solid option. It’s a community-maintained fork of the original Airsonic (itself a fork of Subsonic), focused on modernizing the codebase while keeping full compatibility with the Subsonic API ecosystem.

That API compatibility matters — it unlocks dozens of mobile apps (DSub, Ultrasonic, play:Sub, Sublime Music) and desktop clients without the server needing to implement its own. You host the server, pick any Subsonic-compatible client, and stream your library from anywhere.

Feature	Details
License	GPL-3.0
Subsonic API	Full compatibility
Transcoding	FFmpeg-based (on-the-fly)
DLNA/UPnP	Built-in server
Multi-user	Yes, with roles
Podcast support	Built-in
Internet radio	Built-in
Mobile apps	Any Subsonic-compatible client
Architecture	amd64, arm/v7, arm64

Prerequisites

• A Linux server (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker and Docker Compose installed (Docker Compose Basics)
• 512 MB of free RAM minimum (1 GB recommended if transcoding)
• Your music library accessible on the host filesystem
• A domain name (optional, for remote access)

Docker Compose Configuration

Create a directory for Airsonic-Advanced:

mkdir -p /opt/airsonic/{config,music,playlists,podcasts}

Create /opt/airsonic/docker-compose.yml:

services:
  airsonic:
    image: airsonicadvanced/airsonic-advanced:11.0.0-SNAPSHOT.20240424015024
    container_name: airsonic
    restart: unless-stopped
    ports:
      - "4040:4040"   # Web UI
      - "4041:4041"   # UPnP/DLNA
      - "1900:1900/udp" # DLNA discovery
    volumes:
      - ./config:/var/airsonic
      - ./music:/var/music:ro
      - ./playlists:/var/playlists
      - ./podcasts:/var/podcasts
    environment:
      # Java memory allocation — increase for large libraries (50k+ tracks)
      JAVA_OPTS: "-Xmx512m"
      # Run as specific user/group (match your music directory ownership)
      PUID: 1000
      PGID: 1000
      # Timezone
      TZ: "America/New_York"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4040/login"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Note on image tags: Airsonic-Advanced’s maintainers recommend snapshot builds over stable releases. The 10.6.0 stable release is from 2020 and missing years of improvements. The 11.x snapshots are actively maintained and used in production by the community.

Start the stack:

cd /opt/airsonic && docker compose up -d

Initial Setup

1. Open http://your-server-ip:4040 in your browser
2. Log in with default credentials: admin / admin
3. Change the admin password immediately — Settings → Users → admin → Change password
4. Go to Settings → Media folders → Add your music directory (/var/music inside the container)
5. Click “Scan media folders now” to index your library

The initial scan takes 1-5 minutes for a typical library (5,000-20,000 tracks). Large libraries (100k+ tracks) may take 30+ minutes.

Configuration

Transcoding

Airsonic-Advanced uses FFmpeg for on-the-fly transcoding. This lets low-bandwidth connections stream FLAC libraries as MP3/Opus without pre-converting your files.

Settings → Transcoding:

Setting	Recommended Value
Max bitrate (WiFi)	320 kbps
Max bitrate (mobile)	192 kbps
Preferred format	Opus (better quality/size than MP3)
Transcoding threads	2-4 (match your CPU cores)

FFmpeg is bundled in the Docker image. No additional installation needed.

User Management

Create separate accounts for family members or friends. Each user gets:

• Their own playlists and play history
• Configurable bitrate limits (useful for bandwidth-constrained users)
• Role-based permissions (admin, stream, download, share, settings)
• Per-user media folder visibility

Settings → Users → Add user.

DLNA/UPnP

Airsonic-Advanced includes a built-in DLNA server. Devices on your network (smart TVs, receivers, game consoles) can browse and play your library without installing any app.

Enable in Settings → DLNA → Enable DLNA. The server advertises on port 1900/UDP. Ensure this port is mapped in your Docker Compose (included above).

Podcast Support

Settings → Podcast → Add podcast feed URL. Airsonic downloads new episodes automatically on a configurable schedule. Episodes are stored in the /var/podcasts volume.

Advanced Configuration

External FFmpeg

If you need custom FFmpeg builds (hardware-accelerated transcoding, specific codec support), mount your own FFmpeg binary:

volumes:
  - /usr/bin/ffmpeg:/usr/bin/ffmpeg:ro

Jukebox Mode

Jukebox mode plays audio directly through the server’s audio hardware — useful if your server is connected to speakers. Enable in Settings → Players → your player → Technology → Jukebox.

Requires passing the host’s audio device to the container:

devices:
  - /dev/snd:/dev/snd

LDAP Authentication

For environments with existing directory services, Airsonic-Advanced supports LDAP authentication:

Settings → LDAP → Enable LDAP authentication. Configure your LDAP URL, search filter, and manager DN.

Reverse Proxy

Nginx Proxy Manager

Add a proxy host pointing to http://airsonic:4040. Set the custom location / with websocket support enabled.

For manual Nginx configuration:

location / {
    proxy_pass http://localhost:4040;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
}

See our Reverse Proxy Setup guide for full configuration.

Backup

Back up the /var/airsonic config directory. This contains:

• Database (user accounts, playlists, play counts, ratings)
• Settings and transcoding configuration
• Album art cache

Your music files are mounted read-only (/var/music:ro) — back those up separately with your normal backup strategy.

# Stop the container before backup to ensure consistency
docker compose stop airsonic
tar czf airsonic-backup-$(date +%Y%m%d).tar.gz ./config
docker compose start airsonic

See our Backup Strategy guide for automated backup approaches.

Troubleshooting

Transcoding fails with “Command not found”

Symptom: Playback fails when transcoding is required (FLAC to MP3, high-to-low bitrate).

Fix: Verify FFmpeg is available inside the container:

docker exec airsonic which ffmpeg

If missing, the Docker image may have changed. Mount FFmpeg from the host or switch to a different image tag.

Slow library scanning

Symptom: Media scan takes hours for a large library.

Fix: Increase Java heap memory. Edit JAVA_OPTS in your Docker Compose:

JAVA_OPTS: "-Xmx1024m"

Restart the container. For libraries over 100k tracks, consider 2 GB heap.

DLNA devices don’t see the server

Symptom: Smart TVs or receivers can’t find Airsonic in their DLNA browser.

Fix: DLNA discovery uses UDP multicast on port 1900. Ensure:

1. Port 1900/udp is mapped in Docker Compose
2. The container is on the host network, or the bridge network allows multicast
3. Your router isn’t blocking multicast traffic between VLANs

If bridge networking blocks DLNA, switch to host networking:

network_mode: host

Album art not displaying

Symptom: Album covers show as blank in the web UI or mobile apps.

Fix: Airsonic reads embedded album art from audio files and cover.jpg/folder.jpg in album directories. If art is missing:

1. Embed art using a tagger (MusicBrainz Picard, Mp3tag)
2. Place cover.jpg in each album folder
3. Clear the art cache: delete config/thumbs/ and rescan

Resource Requirements

Metric	Idle	Streaming (1 user)	Transcoding (3 users)
RAM	200-300 MB	300-400 MB	400-600 MB
CPU	Minimal	Low	Medium (FFmpeg)
Disk	50 MB (app)	+ music library	+ transcoded cache

Airsonic-Advanced is one of the lighter music servers. An N100 mini PC handles 5-10 concurrent transcoding streams without issue.

Verdict

Airsonic-Advanced is the right choice if Subsonic API compatibility is your priority. The ecosystem of mobile apps (DSub, Ultrasonic, play:Sub) is mature and well-tested. DLNA support, podcast management, and multi-user access are built in — no plugins or additional services needed.

The trade-off: the web UI feels dated compared to Navidrome’s modern interface, and active development has slowed. If you don’t need DLNA or podcast support and want a faster, lighter server with a polished UI, Navidrome is the better pick. If you want the full Subsonic feature set in a single self-hosted package, Airsonic-Advanced delivers.

FAQ

Is Airsonic-Advanced the same as Airsonic? No. Airsonic-Advanced is a maintained fork of the original Airsonic project, which itself was a fork of Subsonic. The original Airsonic is no longer actively developed. Airsonic-Advanced adds features like Opus transcoding, improved tagging, and security fixes.

Can I use Spotify clients with Airsonic-Advanced? No. Airsonic uses the Subsonic API, not the Spotify API. Use Subsonic-compatible clients like DSub (Android), play:Sub (iOS), or Sublime Music (Linux desktop).

Does Airsonic-Advanced support hardware-accelerated transcoding? Not natively. Transcoding uses FFmpeg in software mode. You can mount a custom FFmpeg binary with hardware acceleration support (VAAPI, NVENC), but this requires manual configuration.

How does it compare to Navidrome? Navidrome is lighter, faster, and has a more modern UI. Airsonic-Advanced has DLNA, podcasts, jukebox mode, and internet radio built in. See our Navidrome vs Airsonic comparison for a detailed breakdown.

Can I migrate from Subsonic to Airsonic-Advanced? Yes. Airsonic-Advanced reads Subsonic’s database format. Copy your Subsonic data directory to Airsonic-Advanced’s config volume and start the container. Playlists, users, and play counts will be preserved.

Related

• Funkwhale vs Airsonic-Advanced: Self-Hosted Music
• Best Self-Hosted Music Streaming
• How to Self-Host Navidrome
• Navidrome vs Airsonic
• How to Self-Host Funkwhale
• Self-Hosted Alternatives to Spotify
• Self-Hosted Alternatives to Apple Music
• Music Server Hardware Guide
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy