Skip to content

Configuration ​

All configuration is via environment variables using the FunkArr__ prefix. The double underscore (__) separates nested sections - this is standard ASP.NET Core configuration binding.

Defaults work out of the box for local development. For production, you typically only need to set FunkArr__ApiKey and FunkArr__Download__Path.

General ​

VariableDefaultDescription
FunkArr__ApiKeyfunkarr-default-api-keyAPI key for Prowlarr/Sonarr/Radarr
FunkArr__DataPathdataBase path for database, rulesets, temp files
FunkArr__BaseUrl(empty)Base URL for FunkArr (used by setup API for auto-configuration)

API Key ​

The API key authenticates all requests from Prowlarr, Sonarr, and Radarr. Both the indexer API (/index/api) and download client API (/download/api) require this key. Use the same value when configuring FunkArr in your *arr apps.

WARNING

Change the default API key in production. Anyone with the key can search and download through your FunkArr instance.

Data Path ​

The data path is the root directory for all persistent state. FunkArr creates the following structure inside it:

data/
  funkarr.db            # SQLite database (when not using PostgreSQL)
  rulesets/
    community/          # Auto-synced community rulesets
    local/              # Your custom rulesets
    version.txt         # Currently installed community ruleset version
  temp/                 # Temporary files during download/remux

Downloads ​

VariableDefaultDescription
FunkArr__Download__Pathdata/downloadsRoot download directory
FunkArr__Download__ConcurrentDownloads3Max parallel downloads
FunkArr__Download__RetryEnabledfalseAutomatically retry failed downloads
FunkArr__Download__MaxRetries3Max retry attempts per download
FunkArr__Download__RetryBackoffBase00:00:30Base backoff between retries (TimeSpan, HH:mm:ss)
FunkArr__Download__MaxHistoryRecords1000Max download history records to retain

Download Path ​

The download path contains two subdirectories that FunkArr manages automatically:

  • incomplete/ - active downloads and remux operations in progress
  • complete/ - finished downloads, organized by category subdirectories

Sonarr and Radarr monitor the complete/ directory for finished files. Make sure this path is accessible to both FunkArr and your *arr apps (typically via a shared Docker volume mount).

Concurrent Downloads ​

Controls how many videos are downloaded and remuxed simultaneously. Each download uses one FFmpeg process. Increase on fast connections with available CPU; decrease if you see timeouts or resource issues.

Retries ​

When RetryEnabled is true, failed downloads are retried up to MaxRetries times. RetryBackoffBase is the base delay between attempts; it doubles with each attempt, capped at 5 minutes (with 00:00:30: 30 s, 1 min, 2 min, ...). MaxHistoryRecords caps how many finished downloads are kept in the download history.

Categories ​

Categories map Sonarr/Radarr download categories to subdirectories inside complete/. Configure one category per *arr app type:

FunkArr__Download__Categories__0__Name=tv
FunkArr__Download__Categories__0__Dir=tv
FunkArr__Download__Categories__1__Name=movies
FunkArr__Download__Categories__1__Dir=movies
VariableDefaultDescription
FunkArr__Download__Categories__N__Name-Category name as configured in Sonarr/Radarr
FunkArr__Download__Categories__N__Dir-Subdirectory inside complete/ for this category

The defaults in appsettings.json already define the categories tv and movies (each with a matching directory). Configure your own entries only if you need different names.

When Sonarr sends a download request with category tv, the finished file ends up in complete/tv/. The N in the variable name is a zero-based index - use 0, 1, 2, etc. for each category.

Download Schedule ​

Optional time windows during which downloads are allowed to start. Outside these windows, downloads remain in the queue and start automatically when the next window opens. Without configured time slots, downloads run around the clock.

VariableDefaultDescription
FunkArr__Download__DownloadSchedule__N__Start-Start time of the window (format: HH:mm)
FunkArr__Download__DownloadSchedule__N__End-End time of the window (format: HH:mm)

The N is a zero-based index. Time windows can span midnight (e.g. 23:00 to 02:00). Multiple windows are supported.

FunkArr__Download__DownloadSchedule__0__Start=23:00
FunkArr__Download__DownloadSchedule__0__End=06:00

Network Routes ​

FunkArr can reach different Mediatheken via different network paths. This is necessary to access geo-restricted content from ORF (Austria) or SRF (Switzerland). FunkArr only supports HTTP proxies - VPN infrastructure (e.g. WireGuard + AirVPN) runs outside of FunkArr in Docker.

Route Definitions ​

Named network paths with an optional HTTP proxy:

VariableDefaultDescription
FunkArr__Routes__Definitions__N__NameDirectRoute name
FunkArr__Routes__Definitions__N__Proxy(empty)HTTP proxy URI (empty = direct connection)
FunkArr__Routes__DefaultDirectDefault route for unmapped channels

Channel Mapping ​

Glob patterns map Mediathek channels to a route. The first matching pattern wins. Channels without a match use the default route.

VariableDefaultDescription
FunkArr__Routes__ChannelRoutes__N__Pattern-Glob pattern for the channel name (e.g. ORF*)
FunkArr__Routes__ChannelRoutes__N__Route-Name of the assigned route

Patterns use simple glob matching (* for any characters). MediathekViewWeb returns these channel names: ARD, ARD-alpha, BR, ZDF, ZDFneo, ZDFinfo, 3Sat, ARTE.DE, ORF, SRF, Funk.net, KiKA, DW, and more.

Example configuration:

FunkArr__Routes__Definitions__0__Name=Direct
FunkArr__Routes__Definitions__1__Name=Austria
FunkArr__Routes__Definitions__1__Proxy=http://gluetun-at:8888
FunkArr__Routes__Definitions__2__Name=Switzerland
FunkArr__Routes__Definitions__2__Proxy=http://gluetun-ch:8888

FunkArr__Routes__ChannelRoutes__0__Pattern=ORF*
FunkArr__Routes__ChannelRoutes__0__Route=Austria
FunkArr__Routes__ChannelRoutes__1__Pattern=SRF*
FunkArr__Routes__ChannelRoutes__1__Route=Switzerland

FunkArr__Routes__Default=Direct

With this configuration, ORF content is downloaded through an Austrian proxy, SRF content through a Swiss proxy, and all other channels (ARD, ZDF, 3Sat, ...) connect directly.

WARNING

If a proxy is unreachable, the download fails - there is no automatic fallback to a direct connection. This is intentional: a silent fallback would bypass the geo-restriction you explicitly configured.

The route applies to the entire download pipeline: both subtitle downloads and FFmpeg use the configured proxy.

Docker Compose with Proxy Infrastructure ​

A complete example with FunkArr and gluetun VPN gateways, each exposing an HTTP proxy:

yaml
services:
  funkarr:
    image: ghcr.io/st0o0/funkarr:latest
    restart: unless-stopped
    ports:
      - "8080:6969"
    volumes:
      - funkarr-data:/app/data
      - /path/to/media:/media
    environment:
      - FunkArr__Download__Path=/media/downloads
      # Route definitions
      - FunkArr__Routes__Definitions__0__Name=Direct
      - FunkArr__Routes__Definitions__1__Name=Austria
      - FunkArr__Routes__Definitions__1__Proxy=http://gluetun-at:8888
      - FunkArr__Routes__Definitions__2__Name=Switzerland
      - FunkArr__Routes__Definitions__2__Proxy=http://gluetun-ch:8888
      # Channel mapping
      - FunkArr__Routes__ChannelRoutes__0__Pattern=ORF*
      - FunkArr__Routes__ChannelRoutes__0__Route=Austria
      - FunkArr__Routes__ChannelRoutes__1__Pattern=SRF*
      - FunkArr__Routes__ChannelRoutes__1__Route=Switzerland
      - FunkArr__Routes__Default=Direct

  # Austria: gluetun WireGuard gateway with built-in HTTP proxy
  gluetun-at:
    image: qmcgaw/gluetun:latest
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=<your provider>
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=<your key>
      - WIREGUARD_ADDRESSES=<your address>
      - SERVER_COUNTRIES=Austria
      - HTTPPROXY=on

  # Switzerland: gluetun WireGuard gateway with built-in HTTP proxy
  gluetun-ch:
    image: qmcgaw/gluetun:latest
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=<your provider>
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=<your key>
      - WIREGUARD_ADDRESSES=<your address>
      - SERVER_COUNTRIES=Switzerland
      - HTTPPROXY=on

volumes:
  funkarr-data:

TIP

Each gluetun container tunnels its traffic through WireGuard and serves the HTTP proxy itself (HTTPPROXY=on, port 8888). FunkArr reaches it via the internal Docker network - the proxies don't need to be publicly accessible.

WARNING

Use a gluetun image built on Go 1.26.9 / 1.27.2 or newer. Older builds answer CONNECT with Transfer-Encoding: chunked, which makes FFmpeg fail the TLS handshake through the proxy (gluetun#3489). Any other HTTP proxy that supports CONNECT (e.g. tinyproxy) works as well.

Rulesets ​

VariableDefaultDescription
FunkArr__RuleSet__Repositoryst0o0/funkarrGitHub repository for community rulesets
FunkArr__RuleSet__VersionlatestRuleset version to use
FunkArr__RuleSet__RefreshEnabledtrueEnable automatic ruleset updates

Repository ​

The GitHub repository where community rulesets are published as release assets. Only change this if you're running a fork with your own ruleset releases.

Version ​

Set to latest to always use the newest community ruleset release. Pin to a specific version tag (e.g. rulesets-v0.2.0) to prevent automatic updates - useful if a new release breaks a mapping you depend on.

Refresh ​

When enabled, FunkArr checks for new ruleset releases every 30 minutes and automatically downloads updates. Disable this if you pin a specific version or run in an air-gapped environment.

Metadata ​

VariableDefaultDescription
FunkArr__Tmdb__ApiKey(empty)TMDB API key
FunkArr__Tvdb__ApiKey(empty)TVDB API key

TMDB ​

A TMDB API key enables metadata resolution for movies and series. FunkArr uses it to match Mediathek entries to the correct TMDB title, improving accuracy for Radarr and Sonarr.

Get a free API key at themoviedb.org/settings/api.

TVDB ​

A TVDB API key enables episode guide resolution. FunkArr uses TVDB data to map airdate-based Mediathek entries to season/episode numbers when the ruleset uses an airdate strategy.

Get an API key at thetvdb.com/api-information.

TIP

Both keys are optional but recommended. Without them, FunkArr relies solely on ruleset patterns for matching, which works but produces fewer results.

RSS Feed ​

VariableDefaultDescription
FunkArr__Feed__EnabledtrueCollect new Mediathek entries for the RSS sync of Sonarr and Radarr
FunkArr__Feed__Interval00:15:00Time between two crawl runs
FunkArr__Feed__InitialLookback2.00:00:00How far back the very first run looks
FunkArr__Feed__PageSize1000Entries per MediathekViewWeb page (1-1000)
FunkArr__Feed__MaxPages20Maximum pages per run (safety limit)
FunkArr__Feed__MaxCatchUp7.00:00:00How far a run catches up after an outage at most
FunkArr__Feed__Retention14.00:00:00How long published releases stay in the feed
FunkArr__Feed__MinConfidence0.7Minimum match score for publishing (0-1)

A run that finds no new Filmliste update costs a single small request. If a run cannot cover all new entries within MaxPages, the Feed page reports a gap; increase MaxPages if this happens regularly.

Scoring ​

VariableDefaultDescription
FunkArr__Scoring__PoolSize4Parallel scoring workers

The scoring pool processes Mediathek search results against rulesets in parallel. Each worker evaluates one ruleset match at a time. Increase for faster search responses on multi-core systems; the default of 4 works well for most setups.

Broadcast Variants ​

VariableDefaultDescription
FunkArr__Variants__AudioDescriptionExcludeAudio description versions ("Audiodeskription", "Hörfassung")
FunkArr__Variants__SignLanguageExcludeSign language versions ("Gebärdensprache", "DGS")
FunkArr__Variants__PlainLanguageExcludePlain language versions ("Einfache/Leichte/Klare Sprache")
FunkArr__Variants__OriginalVersionExcludeOriginal versions ("Originalfassung", "OV", "OmU")

Mediatheken often publish the same broadcast in several variants. FunkArr detects the variant from the title and topic of each entry. With Exclude, the variant never appears in search results, so Sonarr and Radarr cannot grab it automatically. With Allow, it is returned with a tag in the release title (AD, DGS, EinfacheSprache, OV), which you can match with a Custom Format, for example to prefer audio description. Original versions are released without the GERMAN language tag. The current policy is shown on the settings page.

Match History ​

VariableDefaultDescription
FunkArr__ScoringHistory__MaxSnapshots100Max match history snapshots to retain
FunkArr__ScoringHistory__MaxAgeDays30Days before old snapshots are pruned
FunkArr__ScoringHistory__SnapshotInterval20Interval between snapshots

Match history records which ruleset mappings were evaluated and their outcomes. The data is diagnostic — it powers the statistics and traces in the web UI but does not influence scoring. The scoring engine evaluates rules deterministically using only the ruleset's configured confidence values.

  • MaxSnapshots - limits storage for match history. Higher values retain more history for diagnostics but use more disk.
  • MaxAgeDays - removes snapshots older than this many days. Mediathek content changes regularly, so old match data becomes less relevant.
  • SnapshotInterval - journal checkpoint interval for faster recovery. A snapshot is saved every N recordings. Does not affect what data is captured.

Arr API ​

VariableDefaultDescription
FunkArr__ArrApi__SearchCacheTtlSeconds60Duration in seconds that search results are cached

The search cache applies to the external indexer API (/index/api) that Prowlarr, Sonarr and Radarr call. It prevents a pagination follow-up request from re-triggering the full search.

PostgreSQL ​

By default, FunkArr uses SQLite with the database file at {DataPath}/funkarr.db. Set FunkArr__Postgres__Host to switch to PostgreSQL.

VariableDefaultDescription
FunkArr__Postgres__Host(empty)PostgreSQL host - set to enable PostgreSQL
FunkArr__Postgres__Port5432PostgreSQL port
FunkArr__Postgres__User(empty)PostgreSQL user
FunkArr__Postgres__Password(empty)PostgreSQL password
FunkArr__Postgres__DatabasefunkarrPostgreSQL database name

INFO

When Host is empty or not set, FunkArr uses SQLite. This is the recommended default for single-instance setups. Use PostgreSQL when you need external database management or plan to scale.

Logging ​

FunkArr uses Serilog for structured logging. Log levels can be tuned per namespace:

VariableDefaultDescription
Serilog__MinimumLevel__DefaultInformationGlobal minimum log level
Serilog__MinimumLevel__Override__AkkaWarningAkka.NET actor system log level
Serilog__MinimumLevel__Override__Microsoft.AspNetCoreWarningASP.NET Core request log level
Serilog__MinimumLevel__Override__Microsoft.AspNetCore.HttpLoggingInformationASP.NET Core HTTP request logging log level

Valid levels: Verbose, Debug, Information, Warning, Error, Fatal.

Set the default to Debug for troubleshooting. The Akka and ASP.NET overrides are set to Warning by default to reduce noise from the actor system and HTTP pipeline.

Networking ​

FunkArr listens on port 6969 inside the container. Map it to any host port in your Docker Compose:

yaml
ports:
  - "8080:6969"   # Access via http://localhost:8080

FFmpeg ​

FFmpeg must be available on PATH - it is included in the official Docker image. FunkArr uses FFmpeg to:

  • Download video streams (including HLS .m3u8)
  • Remux to MKV (copies video/audio codecs without re-encoding)
  • Embed subtitles as SRT tracks with German language tag

When a network route with a proxy is configured for the channel, FFmpeg is automatically started with the corresponding HTTP proxy (-http_proxy). There are no separate configuration options for FFmpeg behavior. The setup health check (/api/system/setup) verifies FFmpeg is available.

Health Checks ​

FunkArr exposes three health endpoints, none of which are configurable:

EndpointPurpose
/healthzFull health check (data, complete and incomplete directories writable, FFmpeg on PATH, MediathekViewWeb reachable) - returns 503 if a directory or FFmpeg check fails; an unreachable MediathekViewWeb only reports Degraded (200)
/aliveSimple liveness probe - always returns 200
/api/system/setupSetup validation - checks API key, directories, FFmpeg, API connectivity

Use /healthz for container orchestration health probes and /api/system/setup in the web UI to verify your configuration.