Skip to main content

Application Settings

The Settings page allows you to configure global settings for Headendarr.

UI Settings​

These settings control the behaviour and appearance of the Headendarr web interface.

  • Highlight channels with source issues: When enabled, the UI will display a warning highlight for channels that are linked to disabled sources or have failed TVHeadend muxes. This helps in quickly identifying problematic channels.
  • Start page after login: Choose the default page that users will land on immediately after signing in.
    • Options: Dashboard, Sources, EPGs, Channels, TV Guide, DVR, Audit

Connections​

These settings define how Headendarr interacts with external services and how clients connect to Headendarr.

  • Headendarr Host: Callback base URL used when TVHeadend is external (Lite deployment). Headendarr writes this into TVHeadend for XMLTV and stream callback URLs.
    • Availability: shown only for Lite/external-TVHeadend deployments.
    • In AIO/local-TVHeadend deployments this setting is hidden/ignored.
    • Purpose: provide the callback base URL written into TVHeadend for XMLTV and stream callback URLs when TVHeadend is external.
    • Client-facing playlist/XMLTV/HDHomeRun URLs are derived from the request host in AIO mode.
  • Transcoding behavior is controlled per profile in Stream Profiles. Disable a transcoding profile there to prevent its use.
  • Enable periodic channel stream health checks: Runs CSO-managed background diagnostics for channel streams when sources are idle.
    • Scheduler cadence: every 5 minutes.
    • Per-stream cooldown: 6 hours (a stream is skipped if it was checked within the last 6 hours).
    • Background sample window: 7 seconds of media sampling after first media bytes are received.
    • Startup guard: sampling does not begin until first media data arrives; checks abort if no media arrives within 30 seconds.
    • Parallelism: checks run in bounded parallel workers (default 2), capped per run (default 10 streams).
    • Playback priority: any background diagnostic using source capacity is pre-empted when real playback needs that capacity.
    • No-overlap worker: a new scheduler tick does not start a second worker while the previous health-check worker is still running.
  • Cache channel logos: Controls whether Headendarr rewrites channel logos to cached /tic-api/channels/<id>/logo/... URLs.
    • Enabled (default): channel logos are served from Headendarr cache/proxy URLs.
    • Disabled: original source logo URLs are emitted in channel payloads, XMLTV, and generated playlists. Consider using a source like github.com/tv-logo/tv-logos for logos.
  • Stream Profiles table:
    • Enable/disable each supported profile value exposed on stream and playlist URLs.
    • Configure per-profile hardware acceleration preference (HW Accel, VAAPI encode path) for transcoding profiles.
    • Configure per-profile Deinterlace for transcoding profiles.
    • Profiles cover remux targets (mpegts, matroska, mp4, webm, hls), audio-only transforms, and full video/audio transcodes including H.264, H.265, VP8, and AV1 variants.
    • Deinterlace adds a small processing overhead when enabled.
    • If a stream is not interlaced, enabling Deinterlace does not materially change visual output.
    • If a client requests a disabled profile, Headendarr falls back to default.

Routing Toggles Explained​

Headendarr exposes two routing toggles here because they control different traffic families. They are designed to be combined based on your playback setup.

  1. Use CSO for combined playlists, XC, & combined HDHomeRun
  • Scope: combined endpoints only (/tic-api/playlist/combined.m3u, XC combined output, combined HDHomeRun lineups).
  • Use this when clients connect directly to Headendarr and you want CSO channel ordering/failover behaviour on combined outputs.
  • This is useful for Plex, Emby, Jellyfin, and playlist clients that should use one combined entrypoint without relying on TVHeadend.
  1. Route per-source playlists & per-source HDHomeRun via TVHeadend
  • Scope: per-source endpoints only (for example /tic-api/playlist/<id>.m3u and /tic-api/hdhr_device/<stream_key>/<id>/...).
  • Use this when your playback stack is TVHeadend-centric and you want TVHeadend to be the main streaming client.
  • Benefit: TVHeadend applies its own buffering/scanning behaviour and centralises stream handling for TVH clients.
  • Trade-off: adds an extra hop (client -> TVH -> Headendarr/upstream) and depends on TVHeadend reachability.

How To Choose​

  • Direct clients, no TVHeadend required:

    • Enable combined-through-CSO.
    • Disable per-source-through-TVHeadend.
  • TVHeadend-first deployment (most clients connect to TVHeadend):

    • Enable per-source-through-TVHeadend.
    • Then configure mux stream handling on TVHeadend Settings -> Stream Buffer.
    • Combined-through-CSO is optional for direct combined endpoints.
  • Mixed clients (TVHeadend + direct combined playlists/HDHomeRun):

    • Enable combined-through-CSO and per-source-through-TVHeadend together.
    • Choose TVHeadend Settings -> Stream Buffer = CSO if you want TVH pulls and direct CSO paths to share CSO-side limit enforcement behaviour.

Connection-Limit Behaviour Notes​

  • Without TVHeadend routing, direct per-source/combined clients are governed by Headendarr routing and CSO/source checks.
  • With per-source-through-TVHeadend enabled, per-source client playback is mediated by TVHeadend.
  • With TVHeadend Settings -> Stream Buffer = CSO, TVHeadend pulls go through CSO stream handling, improving consistency for mixed-client limit enforcement.

User Agents​

This section allows you to define and manage custom User-Agent headers. These User-Agents are used by Headendarr when fetching data from your IPTV sources and EPG providers. Some providers may require a specific User-Agent to prevent blocking.

  • Add User Agent: Click this button to add a new custom User-Agent entry.
  • Name: A descriptive name for your User-Agent (e.g., "VLC Player", "My Custom UA").
  • User-Agent: The actual User-Agent string (e.g., VLC/3.0.23 LibVLC/3.0.23).

DVR Settings​

These settings control the default behaviour for Digital Video Recorder (DVR) functionalities.

  • Pre-recording padding (minutes): Specify the number of minutes to begin recording before a scheduled programme's start time. This helps ensure that the beginning of a programme is not missed due to scheduling inaccuracies.
  • Post-recording padding (minutes): Specify the number of minutes to continue recording after a scheduled programme's end time. This is useful for capturing content that runs slightly over its scheduled slot.
  • Default recording retention: Choose how long recorded programmes will be kept by default before being automatically deleted. This policy applies to TVHeadend recording profiles synced by Headendarr.
    • Options: 1 day, 3 days, 5 days, 1 week, 2 weeks, 3 weeks, 1 month, 2 months, 3 months, 6 months, 1 year, 2 years, 3 years, Maintained space, Forever.
  • Recording Profiles: These profiles define the file and folder naming conventions for your recorded content. The first profile in the list is treated as the default for users and as a fallback for scheduling.
    • Add Recording Profile: Click this button to create a new recording profile.
    • Profile Name: A friendly name for the recording profile (e.g., "Movies", "Kids Shows").
    • Pathname Format: A format string that determines the directory and filename structure for recordings saved by this profile. Variables can be used to dynamically insert programme details. (e.g., $Q$n.$x for [Episode Name].[Extension]).

Recording Profiles and Pathname Format​

Headendarr stores recording profiles in Application Settings -> DVR Settings and syncs them to TVHeadend recorder profiles when recordings are scheduled.

  • One required profile always exists: Default.
  • Additional profiles can be added (for example Shows, Movies).
  • When creating a one-time recording or series rule, users can choose the profile.
  • If no profile is selected (or a saved key is invalid), Headendarr falls back to default.

Default Profiles​

KeyNameDefault Pathname
defaultDefault%F_%R $u$n.$x
showsShows$Q$n.$x
moviesMovies$Q$n.$x

Retention Policy Values​

These are the values shown in the DVR retention dropdowns (global default and per-user override). They control how long recordings are kept before automatic cleanup.

Time-based options:

  • 1 day, 3 days, 5 days
  • 1 week, 2 weeks, 3 weeks
  • 1 month, 2 months, 3 months, 6 months
  • 1 year, 2 years, 3 years

Special options:

  • Maintained space: Keep recordings, but allow automatic cleanup when space management requires it. This is useful when you want to retain as much history as possible while still protecting free disk space.
  • Forever: Do not auto-delete recordings by age. Use this only if you have enough storage and your own process for pruning old recordings.

Storage considerations:

  • Shorter retention windows reduce disk usage growth.
  • Longer retention windows require more storage capacity.
  • Forever can fill disks over time if not manually managed.
  • Maintained space is typically a safer default for systems with limited or shared storage.

Optional post-processing workflow:

  • If you want to process recordings after completion (for example transcode, rename, or move to another location), consider using Unmanic: https://docs.unmanic.app.

TVHeadend Pathname Tokens​

TokenDescriptionExample
$tEvent titleTennis - Wimbledon
$sEvent subtitle or summaryLive Tennis Broadcast from Wimbledon
$uEvent subtitleTennis
$mEvent summaryLive Tennis Broadcast from Wimbledon
$eEvent episode nameS02-E06
$AEvent season number2
$BEvent episode number6
$cChannel nameSkySport
$gContent typeMovie : Science fiction
$QScraper-friendly name layoutGladiator (2000) / Bones - S02E06
$qScraper-friendly name with directoriestvshows/Bones/Bones - S05E11
$nUnique suffix if file exists-1
$xOutput extension from muxermkv
%FISO date (strftime)2011-03-19
%R24-hour time (strftime)14:12

Common baseline pattern:

  • $t$n.$x -> title + uniqueness + extension

Delimiter Variants​

Tokens like $t and $s support delimiter forms where the delimiter is only emitted when a value exists.

Examples:

  • $ t
  • $-t
  • $_t
  • $.t
  • $,t
  • $;t

Length limits can be applied for some tokens:

  • $99-t limits output length to 99 characters.

Scraper-Friendly Modes ($q, $Q)​

$q and $Q support numeric variants:

VariantBehaviour
1Force movie formatting ($1q, $1Q)
2Force TV-series formatting ($2q, $2Q)
3Alternative directory layout ($3q, $3Q)

Examples:

  • $3q -> tvmovies/Gladiator (2000)/Gladiator (2000)
  • $3q -> tvshows/Bones/Season 5/Bones - S05E11
  • $3Q -> Gladiator (2000)/Gladiator (2000)
  • $3Q -> Bones/Season 5/Bones - S05E11

Season/Episode Padding​

$A and $B support zero-padding modifiers:

TokenMeaningExample
$ASeason number (raw)2
$2ASeason number padded to 2 digits02
$BEpisode number (raw)6
$3BEpisode number padded to 3 digits006

Example:

  • Format: $t/Season $A/$2B-$u$n.$x
  • Output: /recordings/Bones/Season 2/06-The Girl in Suite 2103.ts

Audit Logging​

These settings control the retention of audit logs within the Headendarr database.

  • Audit log retention (days): Define the number of days that audit log entries will be stored in the database. Older entries will be automatically purged to manage database size.