Setup Guide

Teamarr v2
Setup & Walkthrough

How to set up and use Teamarr v2 with integration with Dispatcharr — from installation to a fully configured sports EPG.

GitHub → Dispatcharr
1

Installation

Create a docker-compose.yml file with the following content:

services:
  teamarr:
    image: ghcr.io/pharaoh-labs/teamarr:latest
    container_name: teamarr
    restart: unless-stopped
    ports:
      - 9195:9195
    volumes:
      - ./data:/app/data
    environment:
      - TZ=America/New_York

Then start Teamarr:

docker compose up -d

Once started, open Teamarr by navigating to http://localhost:9195.

2

First Time Setup

The main menu is broken into the following sections:

Dashboard

Overview of your Teams, Event Groups, EPG and channels at a glance.

Templates

Create and edit templates for team and event channels.

Teams

Set up sports and teams to create a team EPG.

Event Groups

Configure groups for event channels.

Channels

View event channel details created in Dispatcharr.

Settings

Global settings — where we begin the walkthrough.

Teamarr Getting Started
3

Settings

General Settings

Confirm your timezone and format, and choose whether the timezone is displayed.

General Settings

Teams Settings

Configure settings for team channel EPG generation.

Schedule Days Ahead
How many days of EPG to generate (7 or 14 recommended).
Midnight Crossover
If there's no game the next day, choose whether previous postgame entries continue or use "Idle Day" filler.
Channel ID Format
Default: {team_name_pascal}.{league_id} — e.g. kansascitychiefs.nfl or newyorkmets.mlb.
Teams Settings

Event Groups Settings

Channel Lifecycle

Event Lookahead
How many days to look in the future to match an event to a stream.
Channel Create Timing
When a matched event's channel is created in Dispatcharr. "Same day" = midnight on the event day (or when the event appears if later).
Channel Delete Timing
When the channel is removed. "Same day" = 11:59 PM local time (late games ending at midnight extend to 11:59 PM the next day). If the stream is removed earlier, the channel is removed at that time.
Duplicate Handling
Consolidate — one channel with failover streams. Separate — additional channels per duplicate. Ignore — skip duplicates entirely.
Channel Range Start / End
The channel number range for Dispatcharr. Can also be overridden per group.
Event Groups Settings — Lifecycle

Exception Keywords

If a stream has certain keywords, you can Sub-consolidate into a new channel, Separate into individual channels, or Ignore them entirely. Delete included keywords or add new ones (e.g. Manningcast, Prime Vision).

Event Groups Settings — Exception Keywords

Default Team Filter

Disabled by default. Use this to include or exclude specific teams from event channel creation, filtered by sport and league.

Event Groups Settings — Team Filter

EPG Generation Settings

Output Path
Where the XML file is saved in the container.
Output Days Ahead
Similar to the EPG generation timeframe.
Lookback Hours
Hours to include prior to the current EPG generation.
Include Completed / Final Events
Continue generating EPG entries after a game finishes.
Enable Schedule Integration
Updates hourly at the top of each hour by default.
Game Durations
Default timeframes per sport — generally includes a 30-minute buffer.
EPG Generation Settings

Integrations

Dispatcharr Integration

Enter your Dispatcharr URL, Username and Password, then click Test (top right) to verify connectivity. Teamarr uses this to create/delete managed channels, access M3U's to find events, and refresh EPG. Once you create your first EPG, also add it as an EPG Source for auto-refresh.

Default Channel Profile
Select specific profile(s) for Teamarr channels in Dispatcharr and save.
Integration Settings — Dispatcharr

Local Caching & API

Local Caching
Teams are cached on startup for speed. You can do a manual refresh if needed.
TheSportsDB API Key
Advanced users may purchase and add an API key. Most users will not need this.
Integration Settings — Caching

Advanced Settings

Updates the XML Generator Info at the top of the XML file.

Advanced Settings
4

Templates

On first setup you can Import a template or Create New Template. Creating new prompts you to choose Team or Event. You can also import starter templates to edit:

Download Team Template Download Event Template
Templates

Editing a Team Template

Basic Info

Name the template and set the duration of events — per-sport or global default from Settings.

Template Basic Info

Template Defaults — Title & Subtitle

Title & Subtitle
The program title used in the EPG. {gracenote_category} uses the standard Gracenote title (e.g. "NFL Football", "Women's College Basketball"). Subtitle populates the subtitle field.
Default Description Templates
The program description — customizable with template variables.
Template Defaults

Program Art

Create a custom URL for program art using variables. You can use your own Docker-hosted version of Game-Thumbs Dynamic Sports Match Logos or a hosted instance.

Program Art

Template Conditions

Team templates only — set custom descriptions for specific conditions such as a winning or losing streak.

Template Conditions

Template Fillers

Pregame

Filler programs before a game/event. For Team templates, use the .next suffix to reference the upcoming game. Works the same as the program using template variables.

Pregame Filler

Postgame

EPG entries after a game until midnight (or the next game day). Team templates use the .last suffix; Event templates do not use .next or .last suffixes.

Conditional descriptions — Set custom descriptions for events that haven't ended at the last EPG generation, or have ended (to include outcomes).
Postgame Filler

Idle Day

Team Channels only — filler for days with no game. Includes conditionals for subtitle/description if there are no games in the next 30 days (off-season). Use .last for previous game outcomes, .next for the next scheduled game. Program art defaults to the team logo if left blank.

Idle Day Filler 1
Idle Day Filler 2

Other EPG Options

Categories
Adds <category> tags to EPG programs for player identification.
Apply Categories To
Events only, or events + filler items.
Tags
Adds <new/> and/or <live/> tags. Date adds the <date> tag of the current local time.
Video Quality
Adds a <video> section with SDTV, HDTV, or 4K/UHD quality.
Note: Teamarr does not test video quality — this is a self-reported tag and may not reflect your actual stream quality.
Other EPG Options

Click Save Template to save all changes and return to the Templates list.

Event Templates

Similar to team templates, but require a Channel Name & Logo. You may use a different logo style in Game Thumbs. This becomes the channel name and logo in Dispatcharr and players. Event templates do not use .next or .last suffixes and do not have an Idle Day template.

Event Template Channel
5

Teams

Important: Teamarr provides EPG only for team channels — it does not create them. Create your own channels in Dispatcharr and assign the Teamarr EPG.

Click Import Teams to get started.

Teams Empty

Import Teams

  1. Select a sport from the left side, then a league.
  2. Check which teams to import (or click Select All).
  3. Repeat for each sport/league combination.
  4. Click Import Selected Teams.
Import Teams

Assign Templates

After import, teams show as Unassigned under Template. Select individual teams or all, then click Assign Template at the bottom.

Teams List

Choose a Team template you created/imported earlier and click Assign.

Assign Template
6

Event Groups

On the Event Groups page, click Import to get started.

Event Groups Empty

Your M3U accounts from Dispatcharr are listed on the left. Select an account to see available groups. Use the eye icon to preview streams; press + to import a group.

Event Group Import

Group Type

Single League
All streams are for a single league (e.g. NFL).
Multi-Sport / Multi-League
Streams contain multiple different leagues.
Configure Event Group

Single League Import

Select the sport type, then the league.

Basic Settings
Change the group name or display in Teamarr.
Event Template
Select the Event Template to use for EPG.
Channel Settings
Auto assigns numbers from global settings; Manual starts at a number you specify.
Duplicate Event Handling
Consolidate, Duplicate, or Ignore — same as Settings.
Single League Config 1
Single League Config 2

Dispatcharr Settings

Channel Group
The group for event channels.
Channel Profiles
Override global profile settings per group.
Custom Regex
Advanced option for custom stream-finding regex.
Team Filtering
Include or exclude teams if not set globally.
Single League Config 3
Tip: To import another group for the same league, select the previously imported group as the Parent Group — all other settings will be inherited.

Multi-Sport Groups

Start the import process, select a group, and choose Multi-Sport / Multi-League.

Multi-Sport Config

Select any or all sports/leagues from the group. Click Select All at the top. Remaining settings are the same as single-league import.

Multi-Sport Selection

Once complete, you'll see all groups including Parent/Child and Multi-Sport groups.

Event Groups Configured
7

EPG

With everything configured, you're ready to generate your EPG.

Add EPG Source to Dispatcharr

  1. Copy the EPG URL (default: http://localhost:9195/api/v1/epg/xmtv, may vary by config).
  2. In Dispatcharr, go to M3U & EPG Manager → Add EPG → Standard EPG.
  3. Name the source, paste the URL, and click Create EPG Source.
  4. In Teamarr Settings → Integrations, select the new EPG to link for auto-refresh.
EPG Link

Generate EPG

Click Generate to create your first EPG and event channels. Generation time varies depending on the number of teams and event groups — progress is shown in the lower right corner.

EPG Generate

Once complete, you'll see the status with the number of events, channels, etc. This info is also available on the Dashboard.

EPG Generated
8

Channels

The Channels page shows all created channels and their details.

Find Orphans
Locate leftover channels in Dispatcharr that should have been deleted.
Reset All
Delete all Teamarr-created channels until the next EPG generation.

Newly created channels will appear in Dispatcharr, assigned to the guide data.

Channels in Dispatcharr

View the TV Guide in Dispatcharr to see the results:

Dispatcharr EPG
Need help? Ask in the Dispatcharr Discord. Found a bug? Open an issue on GitHub.