General
Configure timezone, time format, and display preferences.Timezones
Teamarr uses two separate timezone settings.UI display timezoneThe timezone used for displaying times in the web interface. Set via the TZ environment variable — it cannot be changed in the UI.# docker-compose.yml
environment:
- TZ=America/New_York
{game_time}. Configurable in the UI.If both timezones differ, the UI shows an info box explaining which timezone applies where.
Show timezone abbreviation
Toggle whether to display timezone abbreviations (EST, PST, etc.) alongside times.Event Groups
Configure defaults for event-based EPG generation.Event lookahead
How far ahead to match streams to sporting events. Streams are matched to events within this window.| Option |
|---|
| 1 day |
| 3 days (default) |
| 7 days |
| 14 days |
| 30 days |
Exception keywords
Exception keywords apply when Consolidate mode is active. They allow special handling for certain streams — matched streams are sub-consolidated or separated instead of following the default consolidation behavior.The Exception Keywords section only appears when consolidation mode is set to Consolidate in Settings > Channels.
| Field | Description |
|---|
| Label | Display name, available as {exception_keyword} in templates |
| Match Terms | Comma-separated terms to match in stream names |
| Behavior | How matching streams are handled |
| Behavior | Description |
|---|
| Sub-Consolidate | Group matching streams together, separate from the main consolidated channel |
| Separate | Each matching stream gets its own channel |
| Ignore | Skip matching streams entirely |
EPG
Configure EPG output, scheduled generation, channel reset, and default game durations.Output settings
| Setting | Default | Description |
|---|
| Output Path | ./data/teamarr.xml | Where to write the generated XMLTV file |
| Output Days Ahead | 14 days | How many days of EPG data to include |
| EPG Start (Hours Ago) | 6 hours | Include events that started up to this many hours ago — useful for catching games in progress |
| Include Final Events | — | Toggle whether completed events appear in EPG output |
Scheduled generation
Enable automatic EPG generation on a schedule using a standard cron expression.Common presets| Preset | Expression | Description |
|---|
| Every hour | 0 * * * * | Run at the top of every hour |
| Every 2 hours | 0 */2 * * * | Run every 2 hours |
| Every 4 hours | 0 */4 * * * | Run every 4 hours |
| Every 6 hours | 0 */6 * * * | Run every 6 hours |
| Daily at midnight | 0 0 * * * | Run once daily at midnight |
| Daily at 6 AM | 0 6 * * * | Run once daily at 6 AM |
Scheduled channel reset
For users experiencing stale channel logos in Jellyfin. Schedule a periodic purge of all Teamarr channels before your media server’s guide refresh.| Setting | Description |
|---|
| Enable Scheduled Channel Reset | Toggle periodic channel reset on/off |
| Reset Schedule | Cron expression for when to reset |
| Preset | Expression |
|---|
| Daily 2:30 AM | 30 2 * * * |
| Daily 3:30 AM | 30 3 * * * |
| Daily 4:30 AM | 30 4 * * * |
| Daily 5:30 AM | 30 5 * * * |
Set the reset schedule to run shortly before your media server’s scheduled guide refresh. Channels are recreated on the next EPG generation run.
Default durations
Default event durations (in hours) used when the actual event duration is unknown.| Sport | Default |
|---|
| Basketball | 3.0 h |
| Football | 3.5 h |
| Hockey | 3.0 h |
| Baseball | 3.5 h |
| Soccer | 2.5 h |
| MMA | 5.0 h |
| Boxing | 4.0 h |
| Tennis | 3.0 h |
| Golf | 6.0 h |
| Racing | 3.0 h |
| Cricket | 4.0 h |
Channels
Configure channel lifecycle, numbering, consolidation, per-league overrides, feed separation, and stream ordering.Channel lifecycle
Controls when event channels are created and deleted in Dispatcharr.Create timing| Mode | Description |
|---|
| Same day | Create channels on the day of the event |
| Before event + buffer | Create channels a configurable number of hours before the event starts |
| Mode | Description |
|---|
| Same day | Delete channels at midnight on the day of the event |
| After event + buffer | Delete channels a configurable number of hours after the event ends |
Create and delete timing work together with EPG generation. Channels are only created or deleted when a generation run executes — the timing determines eligibility, not the exact moment.
Channel numbering and consolidation
Numbering mode| Mode | Description |
|---|
| Auto | Sequential numbering from the start of the channel range. Sport/league priority determines order. |
| Manual | Per-league starting channel numbers — each league gets its own block. |
| Field | Description |
|---|
| Channel Range Start | First channel number Teamarr can use |
| Channel Range End | Last channel number (optional — leave empty for no upper limit) |
| Mode | Description |
|---|
| Consolidate | Merge multiple streams for the same event into a single channel with multiple sources. Exception keywords (in Settings > Event Groups) can override this per-stream. |
| Separate | Each stream gets its own channel, even for the same event. |
Per-league channel config
Override channel profiles, channel groups, and group modes on a per-league basis. Click a league row to expand its configuration.| Setting | Options | Description |
|---|
| Channel Profiles | Default, None, or specific profiles | Which Dispatcharr profiles this league’s channels appear in |
| Channel Group | Default or specific group | Which Dispatcharr channel group to assign channels to |
| Group Mode | Default, Static, Dynamic by Sport, Dynamic by League, Custom | How the channel group name is determined |
{sport} - {league} to dynamically create groups.Per-league overrides take precedence over the defaults in Settings > Dispatcharr. Use the X button to clear an override and revert to the default.
Feed separation
When multiple IPTV providers carry separate home and away broadcast feeds for the same event, feed separation detects these and creates distinct channels for each.How it works
- Literal token detection — Stream names containing terms like “HOME” or “AWAY” are detected before team matching. The token is stripped so it doesn’t interfere with team name parsing.
- Team name detection — If enabled, stream names are scanned for team names (e.g., “Orioles Feed”) and matched against the event’s home and away teams.
- Channel discrimination — Streams resolved to different teams get separate channels. Unlabeled streams go to their own channel as usual.
Settings| Setting | Default | Description |
|---|
| Enable Feed Separation | Off | Master toggle for the feature |
| Home Terms | HOME | Comma-separated terms that indicate a home feed |
| Away Terms | AWAY | Comma-separated terms that indicate an away feed |
| Detect Team Names | On | Also match team names in stream names (e.g., “Orioles Feed”) |
| Label Style | Team Name | How feed channels are labeled — see below |
| Style | Example |
|---|
| Team Name | NYY @ BAL (Baltimore Orioles) |
| Short Name | NYY @ BAL (Orioles) |
| Home/Away | NYY @ BAL (Home) |
MLB: NYY @ BAL HOME → home feed → channel: NYY @ BAL (Orioles)MLB: NYY @ BAL AWAY → away feed → channel: NYY @ BAL (Yankees)MLB: NYY @ BAL → no feed detected → channel: NYY @ BAL
Stream ordering
Configure priority rules for ordering streams within consolidated channels. When multiple streams are consolidated into a single channel, these rules determine which stream is listed first.| Rule type | Description | Example |
|---|
| M3U Account | Prioritize streams from a specific M3U account | ”Premium IPTV” = priority 1 |
| Event Group | Prioritize streams from a specific event group | ”ESPN+ Group” = priority 2 |
| Regex Pattern | Prioritize streams matching a regex | (?i)1080p = priority 1 |
Dispatcharr
Configure the connection to Dispatcharr for automatic channel management.Connection settings
| Field | Description |
|---|
| Enable | Toggle Dispatcharr integration on/off |
| URL | Dispatcharr server URL (e.g., http://localhost:9191) |
| Username | Dispatcharr login username |
| Password | Dispatcharr login password |
| Status | Description |
|---|
| Connected | Successfully communicating with Dispatcharr |
| Disconnected | Configured but unable to connect |
| Error | Connection failed — hover for error details |
| Not Configured | Integration not yet set up |
EPG source
Select which EPG source in Dispatcharr to associate with Teamarr-managed channels. This links your channels to the correct guide data.If you haven’t created an EPG source in Dispatcharr yet, you need to do that first. Copy the XMLTV URL from the EPG page in Teamarr and add it in Dispatcharr’s EPG sources.Default channel profiles
Select which channel profiles to assign to Teamarr-managed channels by default.| Selection | Effect |
|---|
| All profiles selected | Channels appear in all profiles |
| None selected | Channels don’t appear in any profile |
| Specific profiles | Channels appear only in selected profiles |
| Wildcard | Description | Example |
|---|
{sport} | Creates/assigns a profile named after the sport | football, basketball |
{league} | Creates/assigns a profile named after the league | nfl, nba, epl |
[1, {sport}] assigns all channels to profile 1, plus dynamically creates and assigns a sport-specific profile.Profile assignment is enforced on every EPG generation run. Wildcard profiles are created in Dispatcharr automatically if they don’t exist.
Default stream profile
Select which stream profile to assign to streams on Teamarr-managed channels. Stream profiles in Dispatcharr control transcoding and quality settings. If no stream profile is selected, streams are added without a profile assignment.Default channel group
Configure which Dispatcharr channel group to assign Teamarr-managed channels to by default.| Setting | Description |
|---|
| Channel Group | Select a specific group, or leave as “None” to skip group assignment |
| Group Mode | How the group name is determined |
| Mode | Description | Example |
|---|
| Static | All channels go to the selected group | All in “Sports” |
| Dynamic by Sport | Auto-create groups per sport | ”Football”, “Basketball”, “Hockey” |
| Dynamic by League | Auto-create groups per league | ”NFL”, “NBA”, “NHL” |
| Custom | Use a template pattern | {sport} - {league} → “Football - NFL” |
{sport} and {league} variables in your pattern. Groups are created automatically in Dispatcharr if they don’t exist.Per-league overrides in Settings > Channels take precedence over these defaults.
Logo cleanup
When enabled, removes all unused logos from Dispatcharr after EPG generation.Logo cleanup affects all unused logos in Dispatcharr, not just ones uploaded by Teamarr. Use with caution if you have manually uploaded logos that are not actively assigned to channels.
System
Update notifications, backup/restore, local caching, TheSportsDB API configuration, and XMLTV metadata.Update notifications
Teamarr can check for new versions and notify you when updates are available.The Current Version card displays your running version and the latest available version. For dev builds, commit hashes are shown; for stable builds, version numbers are shown.| Setting | Description |
|---|
| Enable Automatic Update Checks | Toggle update checking on/off |
| Notify about stable releases | Get notified about new stable versions |
| Notify about dev builds | Get notified about new dev commits (if running the dev image) |
Backup and restore
Download backupDownload a complete backup of your Teamarr database. The backup includes:
- All teams and their configurations
- Templates and presets
- Event groups
- Settings
Restore backupUpload a .db backup file to restore. A backup of your current data is automatically created before restoring.Restoring a backup replaces all current data. The application needs to be restarted after restore.
Local caching
Teamarr caches team and league data from ESPN and TheSportsDB to improve performance and enable offline matching.Cache status| Field | Description |
|---|
| Leagues | Number of leagues cached |
| Teams | Number of teams cached |
| Last Refresh Duration | How long the last refresh took |
| Last Refresh | When the cache was last updated |
Cache refresh runs automatically on first startup. Manual refresh is useful after adding new leagues or when team rosters change significantly.
TheSportsDB API key
Optional premium API key for TheSportsDB. The card header shows your current tier.| Tier | Rate limit | Events per query | Cost |
|---|
| Free | 30 req/min | 5 per day per league | Free |
| Premium | 100 req/min | Full coverage | ~$9/mo |
| Field | Default |
|---|
| Generator Name | Teamarr |
| Generator URL | https://github.com/Pharaoh-Labs/teamarr |