Skip to content

Loomarr configuration reference

Every setting resolves env > database > default (config-design §3). An env var that is set pins the value and locks its UI field. Secrets are encrypted before database persistence, masked on read, and never echoed (config-design §4).

Bootstrap — Database secret protection

LOOMARR_ENCRYPTION_KEY supplies a 32-byte installation key as unpadded base64url; LOOMARR_ENCRYPTION_KEY_FILE points to a file containing the same value. Set only one. When neither is set, Loomarr creates /data/encryption.key with mode 0600. Every PostgreSQL replica must use the same key, and database backups require it to recover stored credentials.

To replace the installation key, supply the new current key and provide the old key for one boot through LOOMARR_ENCRYPTION_KEY_PREVIOUS or LOOMARR_ENCRYPTION_KEY_PREVIOUS_FILE. Remove the previous-key input after Loomarr starts successfully.

Connections — Media server

Setting (env)Owner taskKindDefaultNotes
library.flavor (LIBRARY_FLAVOR)Connectionsenum—Which media server you run, Emby or Jellyfin. They sign in differently, so Loomarr needs to know which one you run. (one of: emby | jellyfin)
library.url (LIBRARY_URL)Connectionsurl—The address of your media server. For example http://emby:8096.
library.token (LIBRARY_TOKEN)Connectionssecret(secret)An API key from your media server. It lets Loomarr read your library and set up the TV guide.
library.path_map (LIBRARY_PATH_MAP)Playbackstring—Where your media server’s folders are on this machine, so Loomarr can find your media folders. Your media server names each folder by its OWN path (e.g. /data/tv); if the same folder is mounted somewhere else on the machine running Loomarr (e.g. /mnt/media/tv), map one to the other as “/data=>/mnt/media”. Multiple rules are separated by commas or newlines. Leave empty when the paths already match, or add your folders by hand in Settings → Library. (advanced)
library.scanner.enabled (LIBRARY_SCANNER_ENABLED)ConnectionsbooltrueWhether Loomarr reads your media folders itself to learn what each file is. Turn this off to stop it reading them; what it already learned is kept. (advanced)

Connections — Requester

Setting (env)Owner taskKindDefaultNotes
requester.provider (REQUESTER_PROVIDER)ConnectionsenumseerrHow Loomarr downloads missing titles: through Seerr, or Sonarr and Radarr directly. (one of: seerr | arr)
seerr.url (SEERR_URL)Connectionsurl—Your Seerr address, which is how Loomarr downloads missing titles. For example http://seerr:5055. (required for acquisition)
seerr.api_key (SEERR_API_KEY)Connectionssecret(secret)Your Seerr API key.
sonarr.quality_profile (SONARR_QUALITY_PROFILE)Connectionsstring—Which Sonarr quality profile new shows use, or blank for Sonarr’s first. Optional Sonarr quality profile (name or id). Blank = Sonarr’s first profile. (advanced)
sonarr.root_folder (SONARR_ROOT_FOLDER)Connectionsstring—Which Sonarr folder new shows go in, or blank for Sonarr’s first. Optional Sonarr root folder path. Blank = Sonarr’s first root folder. (advanced)
radarr.quality_profile (RADARR_QUALITY_PROFILE)Connectionsstring—Which Radarr quality profile new movies use, or blank for Radarr’s first. Optional Radarr quality profile (name or id). Blank = Radarr’s first profile. (advanced)
radarr.root_folder (RADARR_ROOT_FOLDER)Connectionsstring—Which Radarr folder new movies go in, or blank for Radarr’s first. Optional Radarr root folder path. Blank = Radarr’s first root folder. (advanced)

Connections — Sonarr

Setting (env)Owner taskKindDefaultNotes
sonarr.url (SONARR_URL)Connectionsurl—Your Sonarr address. For example http://sonarr:8989. Loomarr learns your shows from it and hears about new episodes.
sonarr.api_key (SONARR_API_KEY)Connectionssecret(secret)Your Sonarr API key (Settings → General in Sonarr).

Connections — Radarr

Setting (env)Owner taskKindDefaultNotes
radarr.url (RADARR_URL)Connectionsurl—Your Radarr address. For example http://radarr:7878. Loomarr learns your movies from it and hears about new ones.
radarr.api_key (RADARR_API_KEY)Connectionssecret(secret)Your Radarr API key (Settings → General in Radarr).

Connections — Tunarr

Setting (env)Owner taskKindDefaultNotes
tunarr.url (TUNARR_URL)Connectionsurl—Your Tunarr address, where Loomarr builds your channels. For example http://tunarr:8000.
tunarr.transcode_config_id (TUNARR_TRANSCODE_CONFIG_ID)Connectionsstring—Which Tunarr transcode profile new channels use. Leave empty to use Tunarr’s default. (advanced)

Playout

Setting (env)Owner taskKindDefaultNotes
server.public_url (SERVER_PUBLIC_URL)Playbackurl—The address your media server and Tunarr use to reach Loomarr’s channel streams. Loomarr’s own address as your media server and Tunarr can reach it, e.g. http://loomarr:8080. Your media server and Tunarr fetch every stream URL from this base, so a wrong value means channels appear in the guide there and never play. Loomarr’s own in-app playback does not use it (it reaches itself on its listen address), and Current Health flags an address this server cannot reach. Also used for uploaded channel icons.
playout.backend (PLAYOUT_BACKEND)PlaybackenuminternalWhether Loomarr streams your channels itself or hands them to Tunarr. Who streams a channel. Internal playout is the default: it supports mid-roll breaks, reports real transcode telemetry, and needs no extra service. Tunarr is an optional backend for an install that already runs Tunarr — not a requirement. An unrecognised value falls back to internal. Overridable per channel. (one of: internal | tunarr)
playout.encoder (PLAYOUT_ENCODER)Playbackstring—Forces a particular video encoder instead of the one Loomarr picked. ffmpeg encoder for internal playout (e.g. libx264, h264_vaapi, h264_nvenc). Empty = pick the best one the transcode check found. Set it only to override that choice. (advanced)
playout.audio_language (PLAYOUT_AUDIO_LANGUAGE)PlaybackstringenWhich audio language channels play when a film has more than one. Preferred audio language for internal playout. Any ISO 639 code saves (en, eng and fra all work). A preference, not a requirement: a film with no track in this language plays its first track rather than failing. Empty = play whichever track comes first in the file, which is how a foreign-language dub ends up playing instead of the original. A channel can override this on its Channel info page.
playout.quality_tier (PLAYOUT_QUALITY_TIER)PlaybackenumbalancedThe best picture quality channels aim for, traded against bandwidth. The picture-versus-bandwidth target. Efficient is 720p and roughly half the bitrate — the right answer for a NAS running several channels, or for watching away from home. Balanced is 1080p and the default. Quality is 1080p at a higher frame rate and bitrate, which on grainy or dark film can be visibly cleaner but costs noticeably more bandwidth per channel. Whichever you pick, playout still steps down automatically as more channels start, so the choice is a ceiling rather than a promise. (one of: efficient | balanced | quality)
playout.tone_curve (PLAYOUT_TONE_CURVE)PlaybackenumhableHow HDR films are adjusted to look right on an ordinary screen. How an HDR film is turned into the SDR picture a channel broadcasts. Hable (the default) rolls bright highlights off gently, like film; Mobius and Reinhard keep more of the mid-tones and highlights. These three run on the GPU on Intel and NVIDIA, about 0.1 CPU cores per HDR stream on Intel. BT.2390, BT.2446 Method A and Spline come from libplacebo. On Intel the picture makes a trip through system memory for them, which roughly doubles the CPU cost to about 0.25 cores per HDR stream. Where libplacebo cannot run (no Vulkan GPU, for example an NVIDIA container without NVIDIA’s Vulkan driver), those three use the CPU tone-mapper’s Mobius curve instead. Without a GPU tone-mapper at all, every curve runs on the CPU after the GPU has scaled the picture down; the picture is correct but costs more CPU. A change applies to streams that start afterwards; a channel already playing keeps its curve until it restarts. (one of: hable | mobius | reinhard | bt2390 | bt2446a | spline)
playout.watermark_opacity_pct (PLAYOUT_WATERMARK_OPACITY_PCT)Playbackint40How solid the on-screen logo in the corner of every programme looks, from 10 (faint) to 100 (fully opaque). A channel with its own opacity keeps it. A change shows from each channel’s next programme.
playout.watermark_look (PLAYOUT_WATERMARK_LOOK)PlaybackenumtextHow the on-screen logo Loomarr draws from a channel’s name looks. Coloured styles use each channel’s colour (by default, colours from the channel’s decade). A channel with its own style keeps it, and an uploaded logo keeps its own shape. A change shows from each channel’s next programme. (one of: plate | text | outline | small-plate | tint | twotone | badge | lockup | glass | stripe)
playout.ffmpeg_path (PLAYOUT_FFMPEG_PATH)PlaybackstringffmpegWhere the ffmpeg program lives. The default works whenever ffmpeg is on the system PATH; set it only if yours is somewhere unusual. (advanced)
playout.hls_dir (PLAYOUT_HLS_DIR)Playbackstring<data dir>/hlsWhere watching in the browser keeps a few minutes of temporary video. Directory where in-app browser playback writes its temporary HLS segments. Defaults to a directory beside the database (/data/hls in the container). Each channel being watched keeps up to 15 minutes of video here (about 1 GB), deleted when you stop watching, so use a disk, not a RAM-backed tmpfs like /dev/shm. Only affects in-app playback; your media server’s streams never use it. Changing it takes effect after restart. (advanced)
playout.state_dir (PLAYOUT_STATE_DIR)Playbackstring<data dir>/playout-stateWhere Loomarr keeps what it learned about this server’s video power. Where Loomarr keeps what it measured about this server’s transcoding: the chosen encoder, the cost of each kind of stream and a few seconds of generated test video (about 20 MB). Defaults to a directory beside the database (/data in the container). Deleting it makes Loomarr measure again at the next start. Changing it takes effect after restart. (advanced)
playout.max_channels (PLAYOUT_MAX_CHANNELS)Playbackint0The most channels Loomarr may stream at the same time, or 0 to decide for itself. Optional safety cap for simultaneous internal transcodes. Leave at 0 for Loomarr to use measured capacity automatically. A positive value can lower that measurement but cannot raise it.
playout.memory_reserve_mb (PLAYOUT_MEMORY_RESERVE_MB)Playbackint2048Memory that channel streaming always leaves free for the rest of the machine. Host memory, in MiB, that hardware encoding must leave available. Loomarr does not start a hardware transcode that would take free memory below this. Set 0 to disable the host-memory check. Changes apply to the next encode without restart. (advanced)
playout.encode_memory_mb (PLAYOUT_ENCODE_MEMORY_MB)Playbackint0How much memory one streaming channel is expected to use, or 0 to work it out. Host memory, in MiB, one hardware encode is expected to use. Leave at 0 to use 1024 MiB, or more if the encoder capability check measured more on this machine; set it when real encodes here use more, for example 4K or HDR tone mapping. Changes apply to the next encode without restart. (advanced)
playout.gpu_cpu_millicores (PLAYOUT_GPU_CPU_MILLICORES)Playbackint1000How much processor time all channels together may use when a graphics card does the encoding. On a host that encodes on its GPU, the CPU all live channels together may use, in thousandths of a core (1000 = one core). Loomarr admits no more channels than fit this allowance at each channel’s measured CPU cost. Never more than the container’s CPU limit. Changes apply to the next channel start without restart. (advanced)
playout.app_reserve_millicores (PLAYOUT_APP_RESERVE_MILLICORES)Playbackint1000Processor time kept free for the rest of Loomarr when channels are encoded without a graphics card. On a host with no hardware encoder, the CPU kept free for the rest of Loomarr, in thousandths of a core (1000 = one core). Live channels may use the container’s CPU limit (or the CPU count) minus this reserve. Changes apply to the next channel start without restart. (advanced)
guide.timezone (GUIDE_TIMEZONE)Playbackstring—The timezone the TV guide shows times in and each channel’s day starts in. Which timezone the TV guide’s times are shown in, as an IANA name like America/New_York, and where each channel’s day starts: a daily schedule turns over at midnight in this timezone. Leave empty to show each viewer’s own device timezone; the schedule then turns over at midnight in the server’s timezone. Only the zones in the list are accepted: a name that is not one of them, “Local”, and the old aliases such as US/Eastern or EST5EDT are refused, so a name means the same on every server.
guide.retention_hours (GUIDE_RETENTION_HOURS)Playbackint24How far back the TV guide lets you scroll. Past listings are recomputed from each channel’s current lineup, so going too far back would show a schedule that never actually aired.

General

Setting (env)Owner taskKindDefaultNotes
access.public_url (ACCESS_PUBLIC_URL)Sharing addressurl—The address people open from an invitation or sign-in recovery link. The absolute browser address invitation and recovery recipients can reach, e.g. https://loomarr.example.com. General suggests the current browser origin when this is empty; save a different address when recipients reach Loomarr elsewhere. The server never infers it from request headers.

Backup

Setting (env)Owner taskKindDefaultNotes
backup.schedule (BACKUP_SCHEDULE)Backupscron0 30 3 * * *When Loomarr backs up its settings, channels and people. When to write the nightly database backup. It contains settings, channels, people, encrypted secrets, and wrapped data keys, but not the external installation key. It does not contain filler, cached artwork, or operator image uploads.
backup.retain (BACKUP_RETAIN)Backupsint7How many backups to keep before pruning the oldest.
backup.dir (BACKUP_DIR)Backupsstring<data dir>/backupsWhere backups are written. Defaults to a directory beside the database (/data in the container) so its volume carries them; point it elsewhere to keep backups off the same disk as the database.

Images

Setting (env)Owner taskKindDefaultNotes
images.dir (IMAGES_DIR)Storagestring<data dir>/imagesWhere Loomarr stores images, both originals and the resized copies it serves. Defaults to a directory beside the database (/data in the container) so its volume carries it. Not covered by the database backup: back up the volume.
images.max_upload_bytes (IMAGES_MAX_UPLOAD_BYTES)Storageint8388608The largest image someone may upload. In bytes (8 MiB by default). Enforced while reading the upload, not from the size the client declares.
images.remote_fetch_enabled (IMAGES_REMOTE_FETCH_ENABLED)StoragebooltrueWhether Loomarr may download artwork from TMDB and your media server. Turn this off to keep to locally-produced images only — no outbound image requests are made.
images.cache_budget_mb (IMAGES_CACHE_BUDGET_MB)Storageint2048How much disk the resized copies of images may use. Past this, Loomarr starts removing the least recently used ones. They are always regenerable, so this costs a little latency, never an image. (advanced)

Connections — TMDB

Setting (env)Owner taskKindDefaultNotes
tmdb.api_key (TMDB_API_KEY)Connectionssecret(secret)Your own TMDB API key, which most households can leave empty. Your own TMDB API key, if you have one. Loomarr comes with its own, so most households can leave this empty. TMDB powers title search, channel icon suggestions, and grounding for AI channel suggestions. (required for suggestions)
metadata.language (METADATA_LANGUAGE)Advanced settingsstring—The language titles, overviews and trailers are shown in. As a language code (en, fr, pt-BR). Empty uses your media server’s metadata language, or English. Changing it fetches every title’s details again. (advanced)
metadata.country (METADATA_COUNTRY)Advanced settingsstring—The country whose content ratings Loomarr uses. Only US ratings are supported for now, so this can be empty or US. (advanced)

AI

Setting (env)Owner taskKindDefaultNotes
llm.provider (LLM_PROVIDER)AIenumollamaWhich AI to use: a local Ollama, or an OpenAI-compatible service. You can also pick a model in the AI settings. (required for suggestions; one of: ollama | openai)
llm.url (LLM_URL)AIurl—The address of your AI service. For Ollama, its host such as http://ollama:11434. For a hosted provider, the exact OpenAI-compatible API base; Loomarr fills this for OpenRouter, while Custom remains editable.
llm.model (LLM_MODEL)AIstring—The AI model that builds channel lineups. The active model used to build channel lineups. Prefer the guided picker on the AI page; OpenRouter ids use provider/model (for example openai/gpt-4o-mini). (required for suggestions)
llm.api_key (LLM_API_KEY)AIsecret(secret)The API key for your hosted AI service. Never shown again after saving.
llm.keep_alive (LLM_KEEP_ALIVE)AIduration2mHow long the local AI model stays loaded between requests. How long to keep the local AI model loaded in memory between requests. Loading it takes several seconds, so keeping it ready makes suggestions much faster — but the model shares GPU memory with channel playback, so the default is short (2m) to free that memory for streaming. Raise it if you rarely stream and want faster suggestions; set 0 to free memory as soon as each request finishes. (advanced)
asr.provider (ASR_PROVIDER)AIenumwhisperHow Loomarr understands speech in clips. The built-in option stays on this device; a connected service is faster on low-power hardware and can use a separate address and key under Advanced. (one of: whisper | hosted)
asr.url (ASR_URL)AIurl—The address of a separate speech service, or blank to use your AI service. OpenAI-compatible speech-to-text API base, such as http://ai-server:8083/v1. Leave blank to reuse the active hosted AI service. (advanced)
asr.api_key (ASR_API_KEY)AIsecret(secret)The API key for the separate speech service. It is never shown again after saving and the main AI key is never sent to a custom speech address. (advanced)
asr.model (ASR_MODEL)AIstringopenai/whisper-large-v3The speech model the connected service uses. Speech-to-text model used by the connected service. It is separate from the lineup model because it must return timed transcript segments and the detected language. (advanced)
suggest.max_acquisitions (SUGGEST_MAX_ACQUISITIONS)AIint10The most titles a single suggestion may download.
recurate.min_score_pct (RECURATE_MIN_SCORE_PCT)AIint60How good a match a title you don’t have must be before auto-curate downloads it. Quality bar (0–100) a not-in-library title must clear for auto-curate to REQUEST it. In-library matches are added regardless. A per-channel override may be stricter or looser. (advanced)
recurate.max_titles (RECURATE_MAX_TITLES)AIint40The most titles an auto-curate channel may grow to. Re-curation won’t request net-new titles past this cap. A per-channel override may be stricter or looser. (advanced)

Advanced

Setting (env)Owner taskKindDefaultNotes
job.recurate.schedule (JOB_RECURATE_SCHEDULE)Background taskscron0 0 4 * * 0How often auto-curate channels look again at what your library offers. How often auto-curate channels re-evaluate their intent against the library (cron). Weekly by default — this runs the AI, so keep it infrequent. (advanced)
job.growth.schedule (JOB_GROWTH_SCHEDULE)Background taskscron0 5 0 * * *When channels take in new library titles that fit them. When each channel adds the library titles inside the line its own picks draw, up to its target (cron). Nightly just after midnight by default; it uses no AI. (advanced)
job.growth_review.schedule (JOB_GROWTH_REVIEW_SCHEDULE)Background taskscron0 */5 * * * *How often the AI checks the titles channels took in by themselves. How often the AI reviews a few of the titles channels added by themselves, and the unclear ones they held back (cron). Each run asks about at most four titles and waits while someone is using the AI. (advanced)
request.ttl (REQUEST_TTL)Advanced settingsduration48hHow long Loomarr keeps trying to request a title before giving up.
downloading.ttl (DOWNLOADING_TTL)Advanced settingsduration12hHow long a downloading title waits to finish before Loomarr gives up on it.
job.system_health.schedule (JOB_SYSTEM_HEALTH_SCHEDULE)Background taskscron*/30 * * * * *How often Loomarr checks its database and connections for Current Health. A cron schedule.
job.notification_delivery.schedule (JOB_NOTIFICATION_DELIVERY_SCHEDULE)Background taskscron*/15 * * * * *How often Loomarr sends waiting invitation and recovery messages. Claims queued messages for delivery, on a cron schedule.
job.reconcile.schedule (JOB_RECONCILE_SCHEDULE)Background taskscron0 */5 * * * *How often Loomarr checks on in-progress downloads. A cron schedule.
job.channel_maintenance.schedule (JOB_CHANNEL_MAINTENANCE_SCHEDULE)Background taskscron0 */10 * * * *How often Loomarr refreshes series episodes and brings live channels up to date. Also reconciles live channels with Tunarr, on a cron schedule.
job.filler_sync.schedule (JOB_FILLER_SYNC_SCHEDULE)Background taskscron0 */15 * * * *How often Loomarr syncs the filler catalog. A cron schedule.
job.filler_split_sweep.schedule (JOB_FILLER_SPLIT_SWEEP_SCHEDULE)Background taskscron0 45 4 * * *How often Loomarr checks for split suggestions you never reviewed. A cron schedule. What it does when it finds them is set by filler.split.review_window.
job.filler_identity.schedule (JOB_FILLER_IDENTITY_SCHEDULE)Background taskscron0 20 * * * *How often Loomarr looks for copies of the same ad and keeps the best one. It also links shorter or alternate versions, on a cron schedule.
job.filler_defects.schedule (JOB_FILLER_DEFECTS_SCHEDULE)Background taskscron0 */5 * * * *How often Loomarr checks ads’ picture and sound against the standard for their era. A cron schedule. A new ad waits for this check before it airs, and an ad that fails is removed and a better copy sought.
job.filler_pipeline.schedule (JOB_FILLER_PIPELINE_SCHEDULE)Background taskscron0 */2 * * * *How often Loomarr prepares new filler clips. A cron schedule. Preparation means measuring, re-encoding, splitting, listening to and identifying them.
job.images_fetch.schedule (JOB_IMAGES_FETCH_SCHEDULE)Background taskscron0 * * * * *How often Loomarr downloads artwork it knows about but hasn’t fetched yet. A cron schedule. Until this runs, those images show as placeholders.
job.images_adopt_artwork.schedule (JOB_IMAGES_ADOPT_ARTWORK_SCHEDULE)Background taskscron0 */5 * * * *How often Loomarr copies clip thumbnails and previews into the shared image library. Covers thumbnails and hover previews, on a cron schedule. Until a clip has been copied over, its older thumbnail is still what you see.
job.images_avif.schedule (JOB_IMAGES_AVIF_SCHEDULE)Background taskscron0 20 * * * *How often Loomarr makes the smallest copies of images in the background. Encodes the AVIF copies of images that don’t have them yet, on a cron schedule. AVIF is the smallest format and the most expensive to produce, so it is made in the background; until it exists browsers take WebP.
job.images_maintenance.schedule (JOB_IMAGES_MAINTENANCE_SCHEDULE)Background taskscron0 0 5 * * *When Loomarr restores recoverable artwork, enforces retention, and cleans up image storage.
job.library_scan.schedule (JOB_LIBRARY_SCAN_SCHEDULE)Background taskscron0 */5 * * * *How often Loomarr looks for new titles on the media server. Scans for newly-added titles to mark requested items available, on a cron schedule.
job.library_full_scan.schedule (JOB_LIBRARY_FULL_SCAN_SCHEDULE)Background taskscron0 0 3 * * *How often Loomarr does a full media-server sweep to catch anything the quick scan missed. The quick scan is the incremental one above. A cron schedule.
job.library_scan.lookback (JOB_LIBRARY_SCAN_LOOKBACK)Background tasksduration1hHow far back the incremental library scan looks for newly-added titles (should exceed the scan interval).
job.arr_queue_poll.schedule (JOB_ARR_QUEUE_POLL_SCHEDULE)Background taskscron0 * * * * *How often Loomarr checks download progress in Sonarr and Radarr. A cron schedule. Only used when titles are requested from Sonarr and Radarr directly.
job.seerr_queue_poll.schedule (JOB_SEERR_QUEUE_POLL_SCHEDULE)Background taskscron0 * * * * *How often Loomarr asks Seerr how downloads are going. Polls Seerr for coarse acquisition status, on a cron schedule. Only used when titles are requested through Seerr.
job.workers (JOB_WORKERS)Advanced settingsint1How many channel suggestions can be worked on at once. One is the appliance-safe default; raise it deliberately for larger or hosted-model deployments.
job.timeout (JOB_TIMEOUT)Advanced settingsduration10mHow long one channel suggestion may run before it’s stopped.
jobs.retention (JOBS_RETENTION)Advanced settingsduration720hHow long finished suggestion jobs are kept before they’re cleaned up.
proposals.retention (PROPOSALS_RETENTION)Advanced settingsduration2160hHow long suggested lineups are kept before they’re cleaned up.
activity.retention (ACTIVITY_RETENTION)Advanced settingsduration720hHow long the Dashboard’s recent-activity entries are kept before they’re cleaned up.
diagnostics.dir (DIAGNOSTICS_DIR)Diagnosticsstring<data dir>/diagnosticsWhere Loomarr keeps the logs of its video and streaming programs. Where Loomarr keeps bounded ffmpeg and streaming-process output. The directory must be persistent if logs should survive a restart. A change applies to the next process; output already written stays where it was. (advanced)
diagnostics.retention (DIAGNOSTICS_RETENTION)Diagnosticsduration168hHow long diagnostic events and finished process logs are kept. How long Diagnostic events and completed Process runs are kept. Active Process runs are never removed by age.
diagnostics.max_storage_mb (DIAGNOSTICS_MAX_STORAGE_MB)Diagnosticsint512How much disk diagnostic events and process logs may use. Soft global storage budget in MiB for retained Diagnostic events and bounded Process output. Active Process runs remain protected.
job.housekeeping.schedule (JOB_HOUSEKEEPING_SCHEDULE)Background taskscron0 30 4 * * *When Loomarr removes expired sessions and operational records beyond their retention periods.
setup.completed (SETUP_COMPLETED)Advanced settingsboolfalseWhether first-run setup is done. Until it is, Loomarr opens the setup wizard. (advanced)

Channels & playback

Setting (env)Owner taskKindDefaultNotes
channel.reconcile_every (CHANNEL_RECONCILE_EVERY)Channel defaultsduration10mHow long a channel rests after a rebuild before it can be rebuilt again. Minimum delay after a successful rebuild before that channel is eligible for another scheduled sweep. Change the sweep cadence under System → Tasks. (advanced)
sched.window_hours (SCHED_WINDOW_HOURS)Channel defaultsduration24hHow far ahead each channel plans its schedule. How far ahead each channel schedules — the rolling window it materializes and rolls forward, instead of the whole series run (per-channel/-rule overridable; 0 = schedule everything).

Filler / commercials

Setting (env)Owner taskKindDefaultNotes
filler.home_country (FILLER_HOME_COUNTRY)Locationstring—The country your channels are watched in, for holidays and filler. Where your channels are watched. Loomarr uses this country for channels and filler sources, and keeps its holidays on its dates (Canada’s Thanksgiving in October, Britain’s Mothering Sunday in spring). Empty, or a country Loomarr has no holidays for yet, keeps the US calendar.
filler.home_place (FILLER_HOME_PLACE)Locationstring—Your city, so local station news and weather can air between programmes. Optional. Pick your city to get local TV material, such as station news and weather, from stations near you. Without it, only national filler airs.
filler.local_radius_km (FILLER_LOCAL_RADIUS_KM)Locationint100How far from your city a TV station can be and still count as local, in kilometres.
filler.region_fallback (FILLER_REGION_FALLBACK)Filler — Automatic downloadsstring_list—Other countries whose commercials may fill in when your own run short. Optional, in order of preference: countries whose national commercials may air and whose sources may download after your own country’s, such as GB, CA, AU. Your country’s commercials always come first within an era; these fill in when its supply for that era runs thin.
filler.dir (FILLER_DIR)Filler — Clip foldersstring<data dir>/fillerWhere Loomarr stores clips. Each is filed under its content hash with its metadata beside it. Defaults to a directory beside the database (/data in the container) so its volume carries it; point it elsewhere to use an existing clip library. (required for filler; applies after restart)
filler.watch_dir (FILLER_WATCH_DIR)Filler — Clip foldersstring—A folder where any clip you drop in is added to your library. Folder Loomarr watches for new clips. Anything dropped here is filed into your clip folder and then removed. Leave blank to use a ‘_watch’ folder inside the clip folder. (applies after restart)
filler.sync_every (FILLER_SYNC_EVERY)Filler — Clip foldersduration15mHow often Loomarr drains the drop folder and reconciles its own clip library. (advanced)
filler.source.folder.enabled (FILLER_SOURCE_FOLDER_ENABLED)Filler — Clip foldersbooltruePick up clips dropped into the drop folder. Scan the drop-folder for clips. Switching it off stops the catalog sync; clips already in the catalog stay.
filler.transcribe.enabled (FILLER_TRANSCRIBE_ENABLED)Filler — Clip reviewbooltrueListen to clips with little description for spoken brand and product names. When a source provides very little information, listen for spoken brand and product details. Loomarr skips this for clips that already have enough context. Choose the speech service under Settings → AI. (advanced)
filler.vision.enabled (FILLER_VISION_ENABLED)Filler — Clip reviewboolfalseLook at clips Loomarr still can’t identify to read logos and on-screen text. Look at a few frames of clips Loomarr still can’t identify — reading on-screen logos and text — to work out the brand, even for clips with no speech. Needs a vision-capable AI model. (advanced)
filler.vision.model (FILLER_VISION_MODEL)AIstring—Which AI model looks at clip pictures, or empty to use your main model. Which AI model reads clip frames (must be vision-capable). Leave empty to reuse your main model — set it only when that model can’t see images. (advanced)
filler.vision.provider (FILLER_VISION_PROVIDER)AIenuminheritWhich AI service looks at clip pictures. Leave as “same as your main AI” unless your vision model lives somewhere else — a local Ollama, say, while your main AI is a hosted service. (advanced; one of: inherit | ollama | openai)
filler.vision.url (FILLER_VISION_URL)AIurl—The address of that picture service. Leave empty for a local Ollama on this machine. (advanced)
filler.vision.api_key (FILLER_VISION_API_KEY)AIsecret(secret)The API key for that picture service, if it needs one. Your main AI’s key is never reused here. Never shown again after saving. (advanced)
filler.defects.judge_look_cents (FILLER_DEFECTS_JUDGE_LOOK_CENTS)Filler — Processing limitsint2The most one picture-quality check on a paid AI service may cost. Ads whose picture is close to the quality limit are shown to the vision model above for a ruling. This is the most one look may cost on a hosted model. 0 stops hosted looks, and those ads wait. (advanced)
filler.defects.judge_daily_cents (FILLER_DEFECTS_JUDGE_DAILY_CENTS)Filler — Processing limitsint50The most Loomarr’s background checks on a paid AI service may cost in one day. Picture-quality checks on ads and the review of titles channels took in by themselves stop for the day (UTC) on a hosted model once Loomarr’s paid background AI spend that day would pass this. What is past the limit waits for the next day. (advanced)
filler.autosplit.enabled (FILLER_AUTOSPLIT_ENABLED)Filler — Clip reviewbooltrueCut up recordings of several ads without asking when Loomarr is sure of every cut. Accept the cuts automatically when Loomarr is confident about every one of them. Anything less certain still waits for you under Filler → Incoming.
filler.autosplit.min_confidence (FILLER_AUTOSPLIT_MIN_CONFIDENCE)Filler — Clip reviewint85How sure Loomarr must be about every advert it found inside a recording before cutting it up without asking (50–95).
filler.autosplit.max_duration (FILLER_AUTOSPLIT_MAX_DURATION)Filler — Clip reviewduration120sThe longest a single advert is expected to be. Recordings longer than this are treated as compilations worth splitting, and any piece longer than this is one Loomarr will ask you about.
filler.structure_window_authority_path (FILLER_STRUCTURE_WINDOW_AUTHORITY_PATH)Filler — Clip reviewstring—A reviewed file that allows certain long recordings to be split, for advanced installs. Optional absolute path to a separately reviewed long-reel materialization authority. Empty or invalid evidence enables no certified slice; a valid authority may create held children but cannot make them airable. A change applies to the next split; a split already running finishes under the files it started with. (advanced)
filler.structure_window_deployment_path (FILLER_STRUCTURE_WINDOW_DEPLOYMENT_PATH)Filler — Clip reviewstring—A reviewed file naming the paid AI route long-recording splits may use, for advanced installs. Optional absolute path to the reviewed authority’s OpenRouter route and spend deployment. Empty, invalid, or mismatched evidence performs no structure inference and enables no certified slice. A change applies to the next split; a split already running finishes under the files it started with. (advanced)
filler.pipeline.max_clips (FILLER_PIPELINE_MAX_CLIPS)Filler — Processing limitsint25How many new clips Loomarr prepares at a time. How many clips Loomarr advances through preparation in one pass. A large import drains over several passes rather than occupying the machine in one. (advanced)
filler.transcode.max_per_run (FILLER_TRANSCODE_MAX_PER_RUN)Filler — Processing limitsint3How many clips Loomarr converts to its standard format at a time. How many clips Loomarr re-encodes to its standard format in one pass. Set to 0 to never re-encode — clips then play in whatever format they arrived in. (advanced)
filler.pipeline.max_whisper (FILLER_PIPELINE_MAX_WHISPER)Filler — Processing limitsint10How many clips Loomarr listens to at a time. How many clips Loomarr listens to in one pass, for language and transcription together. Listening is slow — minutes per clip on some machines — so this keeps a pass from running away. (advanced)
filler.pipeline.max_vision (FILLER_PIPELINE_MAX_VISION)Filler — Processing limitsint5How many clips Loomarr looks at with AI at a time. How many clips Loomarr looks at with a vision model in one pass. The smallest budget, because on a hosted model each one is a charge. (advanced)
filler.pipeline.max_split_vision (FILLER_PIPELINE_MAX_SPLIT_VISION)Filler — Processing limitsint60How many pieces of one long recording Loomarr looks at a time. How many segments of one recording Loomarr looks at in a single pass. A longer recording is judged over several passes rather than made to wait for you — this bounds how much looking happens at once, not how big a recording can be. (advanced)
filler.pipeline.max_splits (FILLER_PIPELINE_MAX_SPLITS)Filler — Processing limitsint3How many long recordings Loomarr looks inside at a time. How many long recordings Loomarr looks inside in one pass. Finding the adverts in one recording takes minutes. (advanced)
filler.fetch.every (FILLER_FETCH_EVERY)Filler — Automatic downloadsduration6hHow often Loomarr checks enabled sources for new clips. Never stops sources that use this default; you can still check one yourself.
filler.fetch.max_per_run (FILLER_FETCH_MAX_PER_RUN)Filler — Automatic downloadsint10The most clips each enabled source may add in one automatic check.
filler.acquisition.compilations (FILLER_ACQUISITION_COMPILATIONS)Filler — Automatic downloadsboolfalseAlso download recordings of several adverts in one video. Off until Loomarr can split them without asking you; sources then add single adverts only. Your drop folder is never affected.
filler.fetch.max_catalog_clips (FILLER_FETCH_MAX_CATALOG_CLIPS)Filler — Storage limitsint2000Stop fetching automatically once your catalog reaches this many clips. You can still add more by hand. (advanced)
filler.storage.library_budget_gb (FILLER_STORAGE_LIBRARY_BUDGET_GB)Filler — Storage limitsint0How much disk space Loomarr may use for filler, or 0 to choose a safe amount. In GiB. Leave at 0 to choose a safe allowance automatically. Loomarr always keeps a protected amount of free space for the rest of the system.
filler.research.enabled (FILLER_RESEARCH_ENABLED)Filler — Clip detailsbooltrueLook up a clip’s likely time period and place in public sources. This does not affect whether the clip can play.
filler.research.wikidata_enabled (FILLER_RESEARCH_WIKIDATA_ENABLED)Filler — Clip detailsbooltrueSearch Wikidata for public facts that may help identify a clip’s era or location. (advanced)
filler.research.wikipedia_enabled (FILLER_RESEARCH_WIKIPEDIA_ENABLED)Filler — Clip detailsbooltrueSearch Wikipedia for public background that may help identify a clip’s era or location. (advanced)
filler.research.archive_enabled (FILLER_RESEARCH_ARCHIVE_ENABLED)Filler — Clip detailsbooltrueSearch the Internet Archive’s public catalog for related historical items. Searches Archive.org’s public catalog for related historical items and metadata. (advanced)
filler.research.loc_enabled (FILLER_RESEARCH_LOC_ENABLED)Filler — Clip detailsbooltrueSearch the Library of Congress public catalog for related historical records. (advanced)
filler.research.web_provider (FILLER_RESEARCH_WEB_PROVIDER)Filler — Clip detailsenumnoneA general web search Loomarr may try when public sources can’t identify a clip. Optional last-resort search after trusted public sources cannot identify a clip. Search is automatic and never decides safety, readiness, or scheduling. (advanced; one of: none | brave | searxng)
filler.research.brave_api_key (FILLER_RESEARCH_BRAVE_API_KEY)Filler — Clip detailssecret(secret)Your Brave Search API key. Installation-wide Brave Search key. Loomarr sends the public clip title and search terms, never the media file. The key is encrypted and never shown again. (advanced)
filler.research.searxng_url (FILLER_RESEARCH_SEARXNG_URL)Filler — Clip detailsurl—The address of your SearXNG search server. HTTPS address of your SearXNG server. Loomarr requests its bounded JSON search API and does not fetch result pages. (advanced)
filler.research.monthly_limit (FILLER_RESEARCH_MONTHLY_LIMIT)Filler — Clip detailsint100The most web searches Loomarr may make in a month. Most general-web searches Loomarr may make in one UTC calendar month. Trusted public-source lookups do not count toward this limit. (advanced)
filler.incoming.ready_window (FILLER_INCOMING_READY_WINDOW)Filler — Incoming historyduration24hHow long clips stay under Ready in Incoming. They remain in your Library after they leave this view. (advanced)
filler.breaks_per_hour (FILLER_BREAKS_PER_HOUR)Channel defaultsint4How many commercial breaks an hour of programmes gets, unless a channel sets its own. Default commercial-break frequency for channels that follow it. Set 0 to disable breaks by default; each channel can choose its own frequency.
filler.break_duration (FILLER_BREAK_DURATION)Filler — Break assemblyduration2mHow long each commercial break lasts, unless a channel sets its own. How long each commercial break lasts by default, with the commercials rotated so recently shown ones wait their turn. Channels can choose their own length. Use breaks per program hour to turn breaks off.
filler.pod_max (FILLER_POD_MAX)Filler — Break assemblyint4How many clips a break usually holds. Preferred clip count per break. Loomarr automatically exceeds it when shorter clips need more slots to fill the requested break length.
filler.cooldown_seconds (FILLER_COOLDOWN_SECONDS)Filler — Clip eligibility and soundint14400How long before a commercial you’ve seen can air again on any channel. Default seconds before a commercial seen on any channel airs again (14400 is 4 hours). Only watched airings count. Loomarr first reaches for commercials from a nearby era, and repeats one sooner only when that would otherwise leave a break short. Each channel can choose its own spacing. (advanced)
filler.min_quality (FILLER_MIN_QUALITY)Filler — Clip eligibility and soundint0The lowest picture size a commercial may have and still air, or 0 for any. Minimum clip height in pixels for a commercial to be eligible (480 excludes 240p rips). 0 disables the floor, which is the default — era accuracy beats resolution. (advanced)
filler.weight (FILLER_WEIGHT)Filler — Clip eligibility and soundint1How heavily this commercial set is drawn from, relative to others. (advanced)
filler.min_duration (FILLER_MIN_DURATION)Filler — Clip eligibility and soundduration10sFiles shorter than this are turned away as broken downloads. Clips shorter than this are rejected on sight and never enter the catalog — a truncated download is not a short commercial. Set to 0s to accept anything with a readable duration. (advanced)
filler.split.review_window (FILLER_SPLIT_REVIEW_WINDOW)Filler — Clip eligibility and soundduration720hHow long cuts you haven’t reviewed wait before Loomarr gives up on them. When the time is up it drops the leftover cuts and DELETES the original recording to reclaim the space — but only for recordings that already produced clips, so nothing is lost that was never used. The clips themselves are never touched. Set to 0s to keep everything forever. (advanced)
filler.min_clip_duration (FILLER_MIN_CLIP_DURATION)Filler — Clip eligibility and soundduration0sCommercials shorter than this are not picked for breaks automatically. 0s disables the floor. Unlike the minimum clip length above, this never rejects a clip — it stays in the catalog and can still be pinned to a channel. (advanced)
filler.max_clip_duration (FILLER_MAX_CLIP_DURATION)Filler — Clip eligibility and soundduration0sCommercials longer than this are not picked for breaks automatically. This is the guard against a three-minute infomercial filling a thirty-second gap. 0s disables the ceiling. Never rejects a clip; it stays in the catalog and can still be pinned. (advanced)
filler.target_lufs (FILLER_TARGET_LUFS)Filler — Clip eligibility and soundstring-23How loud every filler clip plays, so breaks don’t jump in volume. Loudness every filler clip is normalised to, in LUFS (-23 is the broadcast standard). Clips are measured at ingest; at playout a clip that misses the target gets a small constant gain (never a live filter, so no volume swell at clip starts). Empty disables it and clips play at whatever level they were recorded. (advanced)
filler.language (FILLER_LANGUAGE)Filler — Clip eligibility and soundenumenThe language commercials are in, unless a channel sets its own. Every channel’s commercial language unless the channel sets its own. New clips are kept when their speech is in a language some channel uses and rejected when it is confidently in none of them; a clip with no speech at all is always kept. A clip whose language could not be determined airs only on channels that use this language. (one of: en | zh | de | es | ru | ko | fr | ja | pt | tr | pl | ca | nl | ar | sv | it | id | hi | fi | vi | he | uk | el | ms | cs | ro | da | hu | ta | no | th | ur | hr | bg | lt | la | mi | ml | cy | sk | te | fa | lv | bn | sr | az | sl | kn | et | mk | br | eu | is | hy | ne | mn | bs | kk | sq | sw | gl | mr | pa | si | km | sn | yo | so | af | oc | ka | be | tg | sd | gu | am | yi | lo | uz | fo | ht | ps | tk | nn | mt | sa | lb | my | bo | tl | mg | as | tt | haw | ln | ha | ba | jw | su | yue)
ingest.ytdlp_path (INGEST_YTDLP_PATH)Filler — Processing toolsstring—Where the yt-dlp download program lives. The Loomarr image sets this; empty means clip downloading is off. (advanced)
ingest.ffmpeg_path (INGEST_FFMPEG_PATH)Filler — Processing toolsstring—Where the ffmpeg program lives (yt-dlp needs it to combine video and audio). (advanced)
ingest.timeout (INGEST_TIMEOUT)Filler — Processing toolsduration30mHow long one download may run before it’s stopped, so a stuck fetch can’t block others. (advanced)
ingest.whisper_path (INGEST_WHISPER_PATH)Filler — Processing toolsstring—Where the whisper-cli speech program lives. The image sets this; empty means over-long compilation segments can’t be transcribed for hidden ad breaks. (advanced)
ingest.whisper_model (INGEST_WHISPER_MODEL)Filler — Processing toolsstring—The speech model file used to transcribe long recordings. The whisper model file whisper-cli transcribes with. Size is a correctness property, not a quality preference — too small drops audio and the boundary detector then invents breaks. (advanced)
filler.language_model (FILLER_LANGUAGE_MODEL)Filler — Clip eligibility and soundstring—The model file used to work out what language a clip is in. Must be a MULTILINGUAL whisper model — an English-only one reports every clip as English, so the check would never reject anything. The image ships one; leave empty to turn local detection off. (advanced)

Users & security

Setting (env)Owner taskKindDefaultNotes
session.ttl (SESSION_TTL)Access and devicesduration720hHow long you stay signed in before needing to log in again.
cookie.secure (COOKIE_SECURE)Access and devicesenumautoWhen to mark the login cookie secure: auto (match the request), always, or never (for local dev only). (advanced; one of: auto | always | never)
security.trusted_proxies (TRUSTED_PROXIES)Access and devicesstring_list127.0.0.0/8,::1/128The addresses of the reverse proxies in front of Loomarr, whose forwarding headers it believes. Addresses or ranges separated by commas, such as 192.0.2.10 or 192.0.2.0/24, as the proxy connects to Loomarr (inside Docker, the proxy container’s network address). Only a connection from one of these has its X-Forwarded-For, X-Forwarded-Proto and location headers believed; from anyone else they are ignored, so a client can’t forge them to bypass the sign-in rate limit or downgrade its cookie. The default trusts only the machine Loomarr runs on. Behind a proxy on another machine or container, list its address here, or every visitor shares the proxy’s address. Empty trusts no one. (advanced; applies after restart)

Single sign-on

Setting (env)Owner taskKindDefaultNotes
auth.sso.enabled (AUTH_SSO_ENABLED)Access and devicesboolfalseLet people sign in with your identity provider. They still need an account here — signing in with your provider does not create one.
auth.sso.issuer (AUTH_SSO_ISSUER)Access and devicesurl—Your identity provider’s address. For example https://auth.example.home. Loomarr reads its published configuration from there.
auth.sso.client_id (AUTH_SSO_CLIENT_ID)Access and devicesstring—The client ID your provider issued for Loomarr.
auth.sso.client_secret (AUTH_SSO_CLIENT_SECRET)Access and devicessecret(secret)The client secret your provider issued for Loomarr.