EPG & Program Guides

Electronic Program Guides (EPG) provide schedule information for your IPTV channels, showing what's currently playing and what's coming up. StreamSweeper automatically processes and caches EPG data to power features like post-processing rules and program information in your IPTV player.

What is EPG?

EPG stands for Electronic Program Guide. It's the digital equivalent of a TV guide, containing information about:

Program Titles: The name of the show, movie, or event
Descriptions: Detailed information about the program
Start/End Times: When programs begin and end
Channel Information: Which channel is broadcasting the program
Categories/Genres: Sports, News, Movies, etc.
Episode Information: Season and episode numbers for series

Why EPG Matters: EPG data enables your IPTV player to show "what's on now" and "what's next." It also powers StreamSweeper's intelligent post-processing rules that organize channels based on program content.

How EPG Works with IPTV

EPG data works alongside your M3U playlist to provide a complete viewing experience:

The EPG Flow

Provider Creates EPG: Your IPTV provider generates program guide data for their channels
StreamSweeper Fetches EPG: When you add a connection, StreamSweeper retrieves the EPG data
EPG is Cached: Data is stored in StreamSweeper's database for fast access
XMLTV URL Generated: StreamSweeper creates an XMLTV URL for your playlist
Player Uses EPG: Your IPTV player downloads the EPG to show program information

EPG Sources

EPG data comes from different sources depending on your connection type:

Xtream Codes: EPG is automatically included with the API connection
M3U Playlists: EPG availability depends on whether your provider includes guide data
External EPG: Some providers offer separate EPG URLs

Provider-Dependent: Not all IPTV providers include EPG data with their service. Some may have limited or incomplete program information. This is determined by your provider, not StreamSweeper.

XMLTV Format Explained

XMLTV is the standard format for electronic program guides. StreamSweeper generates XMLTV-compliant EPG files that work with all major IPTV players and media servers.

What is XMLTV?

XMLTV is an XML-based format for TV listings. It contains structured data about programs including:

Channel identifiers
Program schedules
Titles and descriptions
Categories and ratings
Episode information

Why XMLTV?

XMLTV is the universal standard supported by:

VLC, TiviMate, and other IPTV players
Media servers (Plex, Emby, Jellyfin)
DVR software
Third-party EPG tools

Automatic Format: StreamSweeper automatically converts your provider's EPG data into XMLTV format. You don't need to do anything - just copy the XMLTV URL and add it to your player.

EPG Caching in StreamSweeper

To ensure fast performance and reduce load on your IPTV provider, StreamSweeper caches EPG data locally.

7-Day EPG Cache

StreamSweeper maintains an EPG cache with the following characteristics:

Cache Duration: EPG data is cached for up to 7 days
Automatic Refresh: StreamSweeper re-fetches guide data from your provider roughly every 12 hours
Rolling Window: Only upcoming programs within the next 7 days are stored
Database Storage: EPG is stored in StreamSweeper's database for instant access

Why Cache EPG?

Caching provides several benefits:

Fast Playlist Generation: No need to fetch EPG data from your provider every time
Reduced Provider Load: Minimizes API calls to your IPTV service
Reliable Post-Processing: Rules can evaluate EPG data instantly
Database Efficiency: 7-day limit prevents unlimited database growth

Recent Change: StreamSweeper previously cached EPG data indefinitely, which caused database size issues. The 7-day limit was implemented to improve performance and reduce storage requirements while maintaining all essential functionality.

Manual EPG Refresh

You can manually refresh EPG data at any time:

Navigate to Connections
Find your connection
Click Refresh Connection
StreamSweeper will fetch the latest channel list and EPG data

EPG Update Frequency

StreamSweeper actively pulls fresh guide data from your providers on a regular schedule:

Automatic Updates

Scheduled Refresh: StreamSweeper fetches new guide data from your provider roughly every 12 hours
Connection Refresh: EPG updates when you manually refresh a connection
Stale-Data Recovery: If guide data looks stale when a playlist is served, StreamSweeper triggers a background refresh

How Fresh the Data Is

Guide freshness ultimately depends on how often your provider publishes new data:

Daily: Most providers update EPG once per day, usually overnight
Weekly: Some providers release full 7-day guides weekly
Real-Time: Live events and breaking news may get immediate updates

Provider Differences: StreamSweeper's refresh schedule picks up whatever your provider has published. If your guide looks outdated, it's usually because the provider hasn't released new data yet - not because StreamSweeper hasn't checked.

Using EPG URLs in Players

Every StreamSweeper playlist includes a corresponding XMLTV/EPG URL that you can add to your IPTV player or media server.

Finding Your EPG URL

Go to Live TV
Find your playlist
Look for the EPG/XMLTV URL field
Click Copy URL

Adding EPG to Popular Players

TiviMate

Open TiviMate and go to Settings
Select your playlist
Tap EPG Source
Select Remote EPG
Paste your StreamSweeper EPG URL
Set Update EPG to automatic (recommended)

VLC

VLC doesn't support EPG natively, but you can use the playlist with program titles in channel names (enable this option in StreamSweeper playlist settings).

Emby/Jellyfin/Plex

Add your M3U playlist as a Live TV source
When prompted for EPG/Guide data, paste your StreamSweeper XMLTV URL
Set the refresh schedule (daily recommended)
Save and let the media server fetch the guide

Matched Channels: Your IPTV player or media server will attempt to match EPG data to channels based on channel names and IDs. StreamSweeper ensures proper matching by including the correct channel identifiers in both the M3U and XMLTV files.

EPG Timeframe Settings

When using EPG-based post-processing rules, you can control how far ahead StreamSweeper looks for matching programs.

Time Window Options

Available timeframes for post-processing rules:

Current Programs Only: Only what's airing right now
15 Minutes: Programs starting in the next 15 minutes
30 Minutes: Next half hour
1 Hour: Next hour
2 Hours: Next 2 hours
4 Hours: Next 4 hours
24 Hours: Full day ahead
Up to 7 Days: Week-long planning

Choosing the Right Timeframe

Live Sports: Use 1-4 hours to see upcoming games
Event Planning: Use 24 hours or 7 days to plan ahead
Current Content Only: Use "Current Programs" to show only what's on now

Performance Consideration: Longer timeframes (7 days) require more EPG data processing. For most use cases, 24 hours provides an excellent balance of planning capability and performance.

EPG-Based Features

StreamSweeper uses EPG data to power several intelligent features:

Post-Processing Rules

Create dynamic channel organization based on EPG content:

Team Following: Match team names in program titles
Event Tracking: Find championship games, finals, playoffs
Genre Filtering: Organize by program type (sports, news, movies)
Time-Based Rules: Show programs airing within specific timeframes

Channel Renaming

Use EPG data to dynamically rename channels:

Show current program name in channel title
Display game matchups (e.g., "Lakers vs Celtics")
Include time information

Smart Categories

Automatically move channels to categories based on EPG content:

Group all channels showing your team's games
Separate live events from replays
Create "What's On Now" categories

Learn More: See the Post-Processing Rules documentation for detailed examples of EPG-based channel organization.

Troubleshooting EPG Issues

EPG Data Not Showing in Player

Symptom: Channels work but no program information appears.

Solutions:

Verify you've added the EPG/XMLTV URL to your player (M3U alone doesn't include guide data)
Check that your IPTV provider includes EPG data - not all providers offer it
Manually refresh your connection in StreamSweeper to update EPG cache
Allow time for your player to download the EPG (can take several minutes for large guides)
Check if your player has an EPG update schedule and force a manual update

Missing or Incomplete Program Information

Symptom: Some channels have EPG, others don't.

Solutions:

This usually indicates your IPTV provider has incomplete EPG data
Some providers only include EPG for popular channels
Try refreshing the connection to get latest updates
Contact your IPTV provider if EPG is consistently missing

EPG Shows Wrong Time Zone

Symptom: Program times are offset by several hours.

Solutions:

Check your IPTV player's timezone settings
Verify your device's system time is correct
Some providers send EPG in UTC - your player should convert to local time
Check player documentation for timezone override options

Post-Processing Rules Not Matching Programs

Symptom: EPG-based rules aren't finding expected programs.

Solutions:

Verify your provider includes EPG data (rules can't match if no EPG exists)
Check that program titles are spelled correctly in your match criteria
Try using "Contains" instead of "Exact Match" for more flexible matching
Expand the time window to include more upcoming programs
Manually refresh connection to update EPG cache

EPG Data is Outdated

Symptom: Program guide shows old or expired programs.

Solutions:

Refresh your connection to fetch latest EPG data
Check if your IPTV provider has updated their guide
Some providers are slow to update EPG - this is not a StreamSweeper issue
Enable automatic refresh in your IPTV player to get updates regularly

EPG Quality: StreamSweeper can only provide EPG data that your IPTV provider supplies. If your provider has poor, incomplete, or missing EPG, StreamSweeper cannot add information that doesn't exist in the source.

Large EPG Files Take Long to Load

Symptom: EPG takes a long time to download in your player.

Solutions:

This is normal for playlists with thousands of channels
Configure your player to cache EPG locally
Set automatic EPG updates to overnight when you're not using the player
Consider creating smaller, filtered playlists for faster EPG downloads
The 7-day EPG cache limit in StreamSweeper helps keep file sizes manageable

EPG Best Practices

Optimize EPG Performance

Filtered Playlists: Create smaller playlists with only the channels you watch to reduce EPG download size
Automatic Updates: Configure your player to update EPG during off-hours
Local Caching: Enable EPG caching in your player to avoid repeated downloads
Regular Refreshes: Refresh connections weekly to ensure fresh EPG data

Maximize Post-Processing Accuracy

Verify EPG Availability: Before creating EPG-based rules, confirm your provider includes guide data
Test Match Criteria: Preview rules to see which programs currently match
Use Flexible Matching: "Contains" matching is more reliable than exact matches for EPG data
Set Appropriate Timeframes: Match your time window to how far ahead you plan

Media Server Integration

Match Refresh Schedules: Set your media server to refresh EPG on the same schedule as your IPTV provider updates
Monitor Guide Gaps: Check for missing EPG data and report to your provider
Use EPG for DVR: Accurate EPG enables scheduled recordings in media servers

Technical Details

EPG Storage & Processing

Database Storage: EPG data is stored in StreamSweeper's PostgreSQL database
7-Day Rolling Cache: Only programs within the next 7 days are retained
Automatic Cleanup: Expired programs are automatically removed from cache
Fast Retrieval: Database indexes enable instant EPG lookups for post-processing rules

XMLTV Generation

On-Demand: XMLTV files are generated when your player requests the EPG URL
Filtered Content: Only EPG for channels in your playlist is included
Standard Compliance: Full XMLTV DTD compliance ensures compatibility
Compressed Output: EPG data is compressed for faster downloads

Channel Matching

Channel IDs: StreamSweeper maintains consistent channel identifiers between M3U and XMLTV
Multiple Formats: Supports various ID formats (numeric, string, UUID)
Fallback Matching: Players can match by name if ID matching fails

Next Steps

Now that you understand EPG in StreamSweeper, explore these related topics:

Post-Processing Rules - Use EPG data to automatically organize channels
Media Server Integration - Set up EPG in Emby, Jellyfin, or Plex
Managing Connections - Refresh connections to update EPG data
Troubleshooting Guide - Solutions to common EPG problems