Snappier Server

Latest version: v1.3.4

Install & Run Guide

This page covers how to download, install, and run Snappier Server in both GUI (Electron) and CLI‐only modes on Windows, macOS, and Linux, for both x86_64 and ARM64 architectures.

What is Snappier Server?

Snappier Server is a lightweight yet powerful service designed to run seamlessly on your machine 24/7 ideally - otherwise you may miss recordings. Built exclusively for the Snappier IPTV App, it acts as the brain behind all your media recording and downloading needs.

With the Snappier IPTV App, users can effortlessly schedule live TV recordings, save CatchupTV, and download movies or entire TV series from their IPTV provider. Movies can also be scheduled to download at a specific future date and time. Snappier Server takes care of these requests in the background—quietly, efficiently, and reliably.

Note: Each active recording or download uses one connection to your IPTV service. If your subscription only allows a single connection, you won’t be able to watch live TV or start another recording at the same time. However, once a recording has started, you can begin watching it from the server even while it’s still in progress—this does not use up a connection

By default, all your media is saved to the Current Working Directory (CWD) + snappierServer/ folder, but you're free to specify a custom location for folders to organize your recordings and downloads your way. The downloaded content is fully compatible with the Snappier IPTV app and can also be played in any media player that supports the formats.

Note: Live TV and CatchupTV recordings are saved in the .ts (MPEG Transport Stream) format. While widely compatible, this format may not work with certain players—such as Infuse. However, if you enable remuxing the .ts file will be converted to .mkv format making it more compatible.

Once a recording or download begins through the Snappier IPTV App, Snappier itself can be closed. Snappier Server continues the task independently, ensuring everything completes smoothly—even while you're away.

Need help? Join our friendly community on Discord! You’ll find the invite link directly in the Snappier IPTV app.

Notice: Snappier Server is currently a beta feature of the Snappier IPTV App. While it's designed to work for most users, it may not be compatible with all systems or network setups. Installation is the responsibility of the user, and while we may not be able to assist with every individual setup, we’ll always try our best to help in the Discord server if possible. We welcome feedback as we continue to improve it.

1. GUI App (Tray)

The GUI App provides a system‐tray icon and Preferences window with full EPG (Electronic Program Guide) configuration support. Through the Preferences window, you can easily:

• Configure server settings (port, remux, download paths)
• Enable and manage EPG sources with a user-friendly interface
• Add multiple EPG URLs with priority settings
• Set EPG refresh intervals
• Generate Xtream Codes EPG URLs automatically

Pick the right package for your OS and CPU:

⚠️ If you're installing on a computer with a graphical user interface (GUI) — such as Windows, macOS, or Linux — the GUI app is recommended. For headless systems (without a GUI), please use the CLI-only binary provided in Section 2 below.

# Debian/Ubuntu:
sudo apt update && sudo apt install ffmpeg

# Fedora/RHEL:
sudo dnf install ffmpeg

# Arch Linux:
sudo pacman -S ffmpeg
  

2. CLI-Only Binary

🔧 This CLI‐Only Binary is designed for headless/server environments without any GUI.

The CLI package is a single native executable (no GUI), suitable for servers or Docker. It listens on port 8000 by default.

Download

• Windows x64: Download
• Windows ARM64: Download
• macOS x64: Download
• macOS ARM64: Download
• Linux x64: Download
• Linux ARM64: Download

Prerequisite: FFmpeg

Ensure FFmpeg is installed for full recording, remuxing, and optional movie/series downloading support:

# Debian/Ubuntu:
sudo apt update && sudo apt install ffmpeg

# Fedora/RHEL:
sudo dnf install ffmpeg

# Arch Linux:
sudo pacman -S ffmpeg

Note: If you're running the CLI version in a desktop environment and want notifications, install and activate a Linux notification daemon such as dunst or xfce4-notifyd:

• Ubuntu/Debian:
  sudo apt install dunst
  or
  sudo apt install xfce4-notifyd
• Fedora:
  sudo dnf install dunst
  or
  sudo dnf install xfce4-notifyd
• Arch Linux:
  sudo pacman -S dunst
  or
  sudo pacman -S xfce4-notifyd

After installation, ensure the daemon is started or enabled in your session (e.g., by adding dunst & to your autostart script).

Installation & Run

1. Place the binary in a directory on your PATH, or run it directly:

chmod +x snappier-server-cli-‹platform›-‹arch›
./snappier-server-cli-‹platform›-‹arch›

2. To change the default listening port (8000), set the PORT environment variable before launching the server.
   See the section below titled How to Set Environment Variables for step-by-step instructions.
3. All API endpoints (schedules, recordings, movies, series) are available at:

   http://localhost:8000

4. Connect the App: In the Snappier IPTV app, go to Settings → Snappier Server and enter the IP address and port number of the machine running Snappier Server (e.g., 192.168.1.100 and 8000). Do not include http:// or https://

Environment Variables

You can configure the server by setting the following environment variables before launch:

• PORT
  Set the port the server listens on (default is 8000).
• ENABLE_REMUX
  Set to true to convert .ts files to .mkv format automatically.
• RECORDINGS_FOLDER
  Path to store live TV recordings.
• MOVIES_FOLDER
  Path to store downloaded movies.
• SERIES_FOLDER
  Path to store downloaded TV series.
• DOWNLOAD_SPEED_LIMIT_MBS
  Set max download speed for curl-based downloads (in MB/s). Use 0 to disable limit.
• USE_CURL_TO_DOWNLOAD
  Set to true to force using Curl for all downloads (movies/series) instead of FFmpeg.
• ENABLE_EPG
  Set to true to enable EPG (Electronic Program Guide) support.
• EPG_URL
  Single EPG XML URL (e.g., http://example.com/epg.xml).
• EPG_URLS
  Multiple EPG sources as JSON array (e.g., [{"url":"http://source1.com/epg.xml","name":"Main","priority":1}]).
• EPG_REFRESH_INTERVAL
  How often to refresh EPG data in hours (default is 24).

Command-Line Arguments (Alternative to Environment Variables)

The CLI binary also supports command-line arguments for easier configuration. Use --help to see all available options:

./snappier-server-cli --help

EPG Configuration Examples

Single EPG Source:

# Basic EPG setup
./snappier-server-cli --enable-epg --epg-url "http://example.com/epg.xml"

# With custom port and refresh interval
./snappier-server-cli --port 8080 --enable-epg \
  --epg-url "http://provider.com/epg.xml" \
  --epg-interval 12

Multiple EPG Sources:

# Multiple sources with priority (lower number = higher priority)
./snappier-server-cli --enable-epg --epg-urls '[
  {"url":"http://primary.com/epg.xml","name":"Primary","priority":1,"enabled":true},
  {"url":"http://backup.com/epg.xml","name":"Backup","priority":2,"enabled":true}
]'

Complete Configuration Example:

./snappier-server-cli \
  --port 8080 \
  --enable-epg \
  --epg-url "http://provider.com/epg.xml" \
  --epg-interval 24 \
  --enable-remux \
  --recordings ~/Recordings \
  --movies ~/Movies \
  --series ~/TVShows

Verifying EPG Status

Once running with EPG enabled, check the status using curl:

# Check EPG status
curl http://localhost:8000/epg/status

# View channels
curl http://localhost:8000/epg/channels

# Force EPG refresh
curl -X POST http://localhost:8000/epg/refresh

How to Set Environment Variables

If you prefer environment variables over command-line arguments, here's how to set them on each platform:

Windows (Command Prompt)

set PORT=9000
set ENABLE_REMUX=true
set ENABLE_EPG=true
set EPG_URL=http://example.com/epg.xml
snappier-server-cli.exe

Windows (PowerShell)

$env:PORT = "9000"
$env:ENABLE_REMUX = "true"
$env:ENABLE_EPG = "true"
$env:EPG_URL = "http://example.com/epg.xml"
.\snappier-server-cli.exe

macOS / Linux (Bash/Zsh)

export PORT=9000
export ENABLE_REMUX=true
export ENABLE_EPG=true
export EPG_URL="http://example.com/epg.xml"
./snappier-server-cli

To make variables permanent on macOS/Linux, add them to your shell's startup file, like ~/.bashrc or ~/.zshrc.

3. Common Notes

• Configuration: GUI mode stores prefs in config.json under your user‐data folder (%APPDATA% on Windows, ~/Library/Application Support/… on macOS, ~/.config/… on Linux).
• FFmpeg: The macOS and Windows builds bundle FFmpeg, so you don’t need to install it separately on those platforms. On Linux, you must install FFmpeg manually.
• Docker: Use the CLI binary in a Docker image for headless deployments.
• Finding Your IP Address: To connect the Snappier IPTV app to the server, you'll need the local IP address of the machine running Snappier Server:
  • Windows: Open Command Prompt and run ipconfig. Look for the "IPv4 Address" under your active network adapter.
  • macOS: Open Terminal and run ipconfig getifaddr en0 (or en1 depending on your network). Alternatively, go to System Settings → Network → select your network → look for “IP address”.
  • Linux: Open Terminal and run hostname -I or ip a. Look for your active interface’s IP address (e.g., eth0 or wlan0).
• Network Access: Make sure any firewalls or routers allow traffic on the selected port if you want to access the server from another device.
• VPN Configuration: If using a VPN, ensure that both Snappier and the Snappier Server are on the same LAN/subnet to communicate properly.

Understanding and Using the EPG Feature

What is EPG?

EPG stands for Electronic Program Guide. It's like a TV guide that shows you what's currently playing and what's coming up next on your IPTV channels. With EPG enabled, you can see program titles, descriptions, air times, and more—making it much easier to find and schedule recordings of your favorite shows.

Why Use EPG?

• See what's on: View current and upcoming programs for all your channels
• Schedule recordings: Pick shows from the guide and record them automatically
• Better navigation: Find content by browsing the program schedule instead of channel surfing
• Program information: Get details like show descriptions, episode info, and air times

How to Get Your EPG URL

Your EPG data comes from your IPTV provider. There are two common ways to get your EPG URL:

Method 1: From Your IPTV Provider

Most IPTV providers offer an EPG URL (also called XMLTV URL). This is usually provided when you sign up for service. Check:

• Your welcome email or setup instructions from your provider
• Your provider's customer portal or dashboard
• Contact your provider's support team to request the EPG URL

The URL typically looks like: http://provider.com/xmltv.php?username=yourname&password=yourpass

Method 2: Xtream Codes Format (Most Common)

If your IPTV service uses Xtream Codes (most do), you can generate the EPG URL yourself using this format:

http://your-server:port/xmltv.php?username=USERNAME&password=PASSWORD

Example: If your IPTV login details are:

• Server: iptv.example.com
• Port: 8080
• Username: johndoe
• Password: secretpass123

Your EPG URL would be:

http://iptv.example.com:8080/xmltv.php?username=johndoe&password=secretpass123

Setting Up EPG (GUI App)

If you're using the GUI (Tray) app, setting up EPG is simple:

1. Open Preferences: Click the Snappier Server tray icon and select "Preferences"
2. Navigate to EPG Settings: You'll find the EPG section in the Preferences window
3. Enable EPG: Check the "Enable EPG" checkbox
4. Add Your EPG Source:
   • Click "Add EPG Source" or similar button
   • Paste your EPG URL (from Method 1 or 2 above)
   • Give it a friendly name (e.g., "Main Provider EPG")
   • Set priority (1 is highest priority)
5. Set Refresh Interval: Choose how often to update the guide (24 hours is recommended)
6. Save: Click Save or Apply to activate EPG

Advanced: You can add multiple EPG sources. If you have backup providers or different EPG feeds, add them with different priorities. The server will merge data from all sources, with lower priority numbers taking precedence when there are conflicts.

Setting Up EPG (CLI Binary)

If you're using the CLI-only binary, you have two options:

Option A: Command-Line Arguments (Easiest)

When you start the server, add EPG parameters:

# Basic single EPG source
./snappier-server-cli --enable-epg --epg-url "http://iptv.example.com:8080/xmltv.php?username=johndoe&password=secretpass123"

# With custom refresh interval (12 hours instead of default 24)
./snappier-server-cli --enable-epg --epg-url "http://provider.com/epg.xml" --epg-interval 12

# Multiple EPG sources with priorities
./snappier-server-cli --enable-epg --epg-urls '[
  {"url":"http://primary.com/epg.xml","name":"Primary","priority":1,"enabled":true},
  {"url":"http://backup.com/epg.xml","name":"Backup","priority":2,"enabled":true}
]'

Option B: Environment Variables

Set environment variables before launching:

Windows (Command Prompt):

set ENABLE_EPG=true
set EPG_URL=http://iptv.example.com:8080/xmltv.php?username=johndoe&password=secretpass123
set EPG_REFRESH_INTERVAL=24
snappier-server-cli.exe

macOS/Linux (Terminal):

export ENABLE_EPG=true
export EPG_URL="http://iptv.example.com:8080/xmltv.php?username=johndoe&password=secretpass123"
export EPG_REFRESH_INTERVAL=24
./snappier-server-cli

Verifying EPG is Working

After enabling EPG, verify it's working properly:

1. Check Status: Open your browser or use curl to check:

   http://localhost:8000/epg/status

   You should see information about your EPG sources and when they were last updated.
2. View Channels: Check that channel data is loading:

   http://localhost:8000/epg/channels

   This shows all channels detected from your EPG.
3. Check in Snappier App: Open the Snappier IPTV app on your device (phone, tablet, or TV). Make sure you've connected it to your Snappier Server first (see steps below). If EPG is working, you should now see program information when browsing channels and be able to access the TV guide feature.

Connecting Snappier IPTV App to the Server

To use EPG (and all other Snappier Server features) in the Snappier IPTV app, you need to connect the app to your server:

1. Find Your Server's IP Address: Get the local IP address of the computer running Snappier Server:
   • Windows: Open Command Prompt and run ipconfig. Look for the "IPv4 Address" under your active network adapter (usually starts with 192.168.x.x or 10.0.x.x)
   • macOS: Open Terminal and run ipconfig getifaddr en0 (or en1). Or go to System Settings → Network → select your network → look for "IP address"
   • Linux: Open Terminal and run hostname -I or ip a. Look for your active interface's IP address (e.g., eth0 or wlan0)
2. Open Snappier IPTV App: Launch the Snappier IPTV app on your phone, tablet, or TV device
3. Go to Settings: Navigate to Settings (usually a gear icon in the menu)
4. Find Snappier Server Settings: Look for "Snappier Server" section
5. Enter Server Details:
   • IP Address: Enter the IP address you found in step 1 (e.g., 192.168.1.100)
   • Port: Enter the port number (default is 8000 unless you changed it)
   • Important: Do NOT include http:// or https://—just enter the numbers
6. Save & Test Connection: Save the settings. The app should test the connection and confirm if it's successful
7. Verify EPG: Once connected, navigate to your channels. You should see program titles, times, and descriptions if EPG is enabled and working

Troubleshooting Connection:

• Make sure both your device (phone/tablet/TV) and the computer running Snappier Server are on the same WiFi network/subnet
• Check that any firewall on the computer running Snappier Server allows connections on port 8000 (or your custom port)
• If using a VPN, ensure both devices are on the same local network
• Try accessing http://YOUR-IP:8000/health in a web browser on your phone/tablet—if it shows a response, the server is reachable

Troubleshooting EPG

EPG Not Showing Up in the App

• Make sure EPG is enabled in Snappier Server settings
• Verify the EPG URL is correct—test it by pasting it in a web browser (it should download an XML file)
• Check that the server had time to download EPG data (the first download happens when you enable it)
• Restart both Snappier Server and the Snappier IPTV app

EPG Data is Outdated

• Manually trigger a refresh: curl -X POST http://localhost:8000/epg/refresh
• Reduce the refresh interval if programs update more frequently than 24 hours
• Check that your IPTV provider's EPG is up to date

EPG URL Not Working

• Test the URL in a browser—it should download an XML file
• Make sure username and password in the URL are correct
• Check with your IPTV provider that the EPG service is active
• Some providers require special EPG URLs—contact support if the standard Xtream format doesn't work

EPG Refresh Schedule

By default, EPG data refreshes every 24 hours automatically. You can customize this interval:

• GUI: Set in Preferences → EPG Settings → Refresh Interval
• CLI: Use --epg-interval 12 (for 12 hours) or set EPG_REFRESH_INTERVAL=12

Note: Frequent refreshes (every hour) may slow down your server or exceed provider limits. 12-24 hours is typically sufficient since TV schedules don't change that often.

PVR: Automatic Recording Rules

What is PVR?

PVR (Personal Video Recorder) allows you to create automatic recording rules that watch your EPG data and schedule recordings whenever matching programmes appear. Think of it like setting up your DVR to "record all new episodes of EastEnders" instead of manually scheduling each episode.

Why Use PVR?

• Automatic series recording: Record every episode of your favorite show without manual scheduling
• Never miss an episode: The server scans EPG data and automatically schedules new episodes
• Set it and forget it: Create a rule once, and the server handles the rest
• Smart exclusions: Exclude specific episodes you don't want to record

Using PVR in the Snappier IPTV App

The Snappier IPTV app makes it easy to create and manage PVR rules directly from your device:

• Dedicated PVR Section: Access all your PVR rules, upcoming recordings, and exclusions through the "Server" section in the Snappier IPTV app. Here you can create new rules, edit existing ones, view scheduled recordings, and manage exclusions.
• Quick Recording from EPG: When viewing the EPG Grid, simply long press on any programme to bring up recording options. You can instantly create a series rule, schedule a one-time recording, or record just that episode—all without leaving the EPG view.

Note: While the Snappier IPTV app provides a user-friendly interface for managing PVR, this documentation focuses on the API endpoints, which are useful for advanced users, automation, or troubleshooting.

Prerequisites

Before using PVR features, you must have:

• EPG enabled: PVR requires EPG data to find matching programmes (see EPG section above)
• Server running: Snappier Server must be running 24/7 to scan EPG and schedule recordings

PVR Rule Types

Series Recording

Records all future matching episodes continuously. The rule stays active and schedules new episodes every time the EPG updates.

Best for: TV series, daily news shows, ongoing programmes

One-Time Recording

Records only the next matching programme, then automatically disables itself.

Best for: Special episodes, one-off events, movies

API Endpoints Reference

Create a PVR Rule

Endpoint: POST /pvr/rules

Creates a new automatic recording rule.

Example: Series Recording

curl -X POST http://localhost:8000/pvr/rules \
  -H "Content-Type: application/json" \
  -d '{
    "programme_name": "EastEnders",
    "channel_id": "bbc.one",
    "channel_url": "http://192.168.1.100:8000/stream/channel/bbc-one",
    "rule_type": "series",
    "match_type": "contains",
    "channel_logo": "http://example.com/bbc-one-logo.png",
    "playlist_name": "UK Channels"
  }'

Example: One-Time Recording

curl -X POST http://localhost:8000/pvr/rules \
  -H "Content-Type: application/json" \
  -d '{
    "programme_name": "FA Cup Final",
    "channel_id": "itv1",
    "channel_url": "http://192.168.1.100:8000/stream/channel/itv1",
    "rule_type": "one-time",
    "match_type": "exact"
  }'

Required Fields:

• programme_name - Programme title to match
• channel_id - EPG channel ID (must match your EPG data exactly)
• channel_url - Stream URL for recording

Optional Fields:

• rule_type - "series" (default) or "one-time"
• match_type - "contains" (default) or "exact"
• channel_logo - Channel logo URL
• playlist_name - Playlist name for organization

List All PVR Rules

Endpoint: GET /pvr/rules

Returns all PVR rules with optional filtering.

Examples:

# Get all rules
curl http://localhost:8000/pvr/rules

# Get only enabled rules
curl http://localhost:8000/pvr/rules?enabled=true

# Get only series rules
curl http://localhost:8000/pvr/rules?rule_type=series

# Get rules for specific channel
curl http://localhost:8000/pvr/rules?channel_id=bbc.one

Get Specific PVR Rule

Endpoint: GET /pvr/rules/:rule_id

curl http://localhost:8000/pvr/rules/550e8400-e29b-41d4-a716-446655440000

Update PVR Rule

Endpoint: PUT /pvr/rules/:rule_id

Updates an existing rule. Only provided fields are updated.

Examples:

# Disable a rule temporarily
curl -X PUT http://localhost:8000/pvr/rules/RULE_ID \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Change from series to one-time
curl -X PUT http://localhost:8000/pvr/rules/RULE_ID \
  -H "Content-Type: application/json" \
  -d '{"rule_type": "one-time"}'

# Update channel URL
curl -X PUT http://localhost:8000/pvr/rules/RULE_ID \
  -H "Content-Type: application/json" \
  -d '{"channel_url": "http://new.stream.url"}'

Delete PVR Rule

Endpoint: DELETE /pvr/rules/:rule_id

Deletes a rule and optionally cancels all associated scheduled recordings.

Examples:

# Delete rule only (keep scheduled recordings)
curl -X DELETE http://localhost:8000/pvr/rules/RULE_ID

# Delete rule and cancel all its recordings
curl -X DELETE "http://localhost:8000/pvr/rules/RULE_ID?cancel_schedules=true"

Trigger Manual EPG Scan

Endpoint: POST /pvr/scan

Manually triggers an EPG scan to find and schedule matching programmes. The server automatically scans after EPG updates, but this allows you to force a scan immediately.

curl -X POST http://localhost:8000/pvr/scan

Response:

{
  "success": true,
  "scheduled": 5,
  "rules_processed": 3,
  "errors": []
}

Get Upcoming PVR Recordings

Endpoint: GET /pvr/upcoming

Returns all upcoming scheduled PVR recordings, sorted by start time.

curl http://localhost:8000/pvr/upcoming

PVR Exclusions

Exclusions allow you to permanently prevent specific programme instances from being automatically scheduled. This is useful when a PVR rule keeps recording episodes you don't want.

How Exclusions Work

When you delete a PVR-scheduled recording with the exclude=true parameter, that specific programme instance (channel + date/time + title) will never be re-created during future EPG scans.

Delete Schedule with Exclusion

Endpoint: DELETE /schedules/:job_id?exclude=true

Example:

# Delete a scheduled recording and exclude it from future scans
curl -X DELETE "http://localhost:8000/schedules/JOB_ID?exclude=true"

Response:

{
  "status": "canceled",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "excluded": true,
  "message": "Schedule cancelled and excluded from future scans"
}

List All Exclusions

Endpoint: GET /pvr/exclusions

Examples:

# Get all exclusions
curl http://localhost:8000/pvr/exclusions

# Get exclusions for specific rule
curl "http://localhost:8000/pvr/exclusions?rule_id=RULE_ID"

# Get exclusions for specific channel
curl "http://localhost:8000/pvr/exclusions?channel_id=bbc.one"

Remove Exclusion

Endpoint: DELETE /pvr/exclusions/:exclusion_id

Removes an exclusion, allowing the programme to be scheduled again.

curl -X DELETE http://localhost:8000/pvr/exclusions/EXCLUSION_ID

Clear Old Exclusions

Endpoint: POST /pvr/exclusions/clear

Removes exclusions for programmes that have already aired.

Examples:

# Clear all past exclusions
curl -X POST http://localhost:8000/pvr/exclusions/clear

# Clear exclusions older than 7 days
curl -X POST "http://localhost:8000/pvr/exclusions/clear?days=7"

# Clear exclusions older than 30 days
curl -X POST "http://localhost:8000/pvr/exclusions/clear?days=30"

Complete Workflow Example

Setting Up a Series Recording

# 1. Create a series rule for EastEnders
curl -X POST http://localhost:8000/pvr/rules \
  -H "Content-Type: application/json" \
  -d '{
    "programme_name": "EastEnders",
    "channel_id": "bbc.one",
    "channel_url": "http://192.168.1.100:8000/stream/bbc-one",
    "rule_type": "series",
    "match_type": "contains"
  }'

# Response will include: {"success": true, "rule_id": "abc-123-..."}

# 2. Trigger a scan to immediately schedule available episodes
curl -X POST http://localhost:8000/pvr/scan

# 3. Check upcoming recordings
curl http://localhost:8000/pvr/upcoming

# 4. View all your rules
curl http://localhost:8000/pvr/rules

# 5. If you want to temporarily pause the rule
curl -X PUT http://localhost:8000/pvr/rules/abc-123 \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# 6. Re-enable it later
curl -X PUT http://localhost:8000/pvr/rules/abc-123 \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Excluding Unwanted Episodes

# 1. Get upcoming recordings to find the job_id
curl http://localhost:8000/pvr/upcoming

# 2. Delete a specific episode and exclude it
curl -X DELETE "http://localhost:8000/schedules/job-id-here?exclude=true"

# 3. View all exclusions
curl http://localhost:8000/pvr/exclusions

# 4. If you change your mind, remove the exclusion
curl -X DELETE http://localhost:8000/pvr/exclusions/exclusion-id-here

# 5. Trigger a scan to re-schedule the episode
curl -X POST http://localhost:8000/pvr/scan

Important Notes

Channel ID Matching

Critical: The channel_id in PVR rules must exactly match the channel IDs in your EPG data. To find the correct channel IDs:

# List all channels from your EPG
curl http://localhost:8000/epg/channels

Use the exact id value from this response when creating PVR rules.

Match Types

• exact: Programme title must match exactly (case-insensitive)
  • Rule: "EastEnders" → Matches: "EastEnders" only
• contains: Programme title can contain the search term (case-insensitive)
  • Rule: "EastEnders" → Matches: "EastEnders", "EastEnders Special", etc.

Recommendation: Use contains for most rules to catch special episodes and variations.

Automatic Scanning

The server automatically scans EPG data:

• After EPG refresh: When EPG data updates
• On server startup: 2 seconds after the server starts
• Manual trigger: Via POST /pvr/scan

Storage Locations

All PVR data is stored in:

• Rules: ~/SnappierServer/PVR/pvr_rules.json
• Exclusions: ~/SnappierServer/PVR/pvr_exclusions.json
• Recordings: ~/SnappierServer/PVR/*.ts (or .mkv if remux enabled)
• Metadata: ~/SnappierServer/PVR/metaData/*.meta.json

Troubleshooting

PVR Rule Not Scheduling Recordings

• Verify EPG is enabled and working: curl http://localhost:8000/epg/status
• Check that the channel_id matches exactly: curl http://localhost:8000/epg/channels
• Ensure the programme name appears in EPG data
• Try using match_type: "contains" instead of "exact"
• Manually trigger a scan: curl -X POST http://localhost:8000/pvr/scan

Excluded Programme Keeps Getting Scheduled

• Verify the exclusion was created: curl http://localhost:8000/pvr/exclusions
• Check that channel_id, programme name, and start time match exactly
• Exclusions are instance-specific (same episode at different times are different instances)

One-Time Rule Didn't Disable

• One-time rules only disable after successfully scheduling a programme
• If no matching programme was found, the rule stays enabled
• Check upcoming recordings to see if it scheduled: curl http://localhost:8000/pvr/upcoming

HTTPS/SSL Setup

What is HTTPS/SSL?

HTTPS (HTTP Secure) encrypts all communication between your Snappier IPTV app and Snappier Server, protecting your data from eavesdropping and tampering. SSL/TLS certificates are used to enable this encryption.

Why Use HTTPS?

• Security: Encrypts all data transmission (login credentials, stream URLs, etc.)
• Privacy: Prevents network monitoring and man-in-the-middle attacks
• Remote Access: Required for secure access over the internet
• Modern Standards: Many browsers and apps prefer or require HTTPS

How SSL Mode Works

Snappier Server automatically detects SSL certificates and switches to HTTPS mode. If no certificates are found, it falls back to standard HTTP. This means:

• Zero configuration: No code changes or settings needed
• Automatic detection: Server checks for certificates on startup
• Graceful fallback: Works with HTTP if no certificates present
• Hot-swap support: Add certificates anytime and restart

Certificate Locations

The server automatically checks these locations for SSL certificates (in order):

1. Project directory: ./certs/ (recommended for CLI deployments)
2. User data directory: (GUI mode only)
   • Windows: %APPDATA%\snappierServer-electron\certs\
   • macOS: ~/Library/Application Support/snappierServer-electron/certs/
   • Linux: ~/.config/snappierServer-electron/certs/

Required Certificate Files

Place these two files in the certs/ directory:

• privkey.pem - Your private key
• fullchain.pem - Your full certificate chain

Setup Options

Option 1: Let's Encrypt (Recommended for Production)

Best for: Servers accessible from the internet with a domain name

Pros: Free, trusted by all browsers, auto-renewable

Requirements: Domain name, internet-accessible server, port 80 open

Quick Setup:

# Install Certbot
# macOS:
brew install certbot

# Ubuntu/Debian:
sudo apt install certbot

# Get certificates
sudo certbot certonly --standalone -d yourdomain.com

# Copy to Snappier Server
mkdir -p ./certs
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ./certs/
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ./certs/
sudo chown $USER:$USER ./certs/*.pem

# Restart Snappier Server
# The server will now automatically use HTTPS

Auto-Renewal: Let's Encrypt certificates expire every 90 days. Set up automatic renewal:

# Test renewal
sudo certbot renew --dry-run

# Add to crontab (runs daily, renews when needed)
(crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet && cp /etc/letsencrypt/live/yourdomain.com/*.pem /path/to/certs/") | crontab -

Option 2: Reverse Proxy with Caddy (Easiest!)

Best for: Production servers, users who want zero SSL management

Pros: Automatic HTTPS, automatic renewal, zero configuration

How it works: Caddy handles all SSL, your Snappier Server stays on HTTP

Complete Setup (3 steps):

# 1. Install Caddy
# macOS:
brew install caddy

# Ubuntu/Debian:
sudo apt install caddy

# 2. Create Caddyfile
cat > Caddyfile << 'EOF'
yourdomain.com {
    reverse_proxy localhost:8000
}
EOF

# 3. Run Caddy
caddy run

That's it! Caddy automatically:

• Gets Let's Encrypt certificates
• Renews them at 75 days
• Redirects HTTP to HTTPS
• Handles all TLS encryption

Your Snappier Server continues running on HTTP at localhost:8000 without any changes.

Option 3: Self-Signed Certificates (Development/Testing)

Best for: Local testing, home networks, development

Pros: Instant setup, no domain needed, works offline

Cons: Browser warnings, not trusted by default

Quick Setup:

# Create certs directory
mkdir -p ./certs

# Generate self-signed certificate (valid 1 year)
openssl req -x509 -newkey rsa:4096 \
  -keyout ./certs/privkey.pem \
  -out ./certs/fullchain.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"

# Restart Snappier Server
# Server will now use HTTPS

Note: Browsers will show security warnings for self-signed certificates. You'll need to click "Advanced" and accept the certificate.

Verifying HTTPS Mode

After placing certificates and restarting, check the server logs:

✅ HTTPS Enabled:

SSL certificates found in ./certs - starting HTTPS server
Server listening on https://localhost:8000

ℹ️ HTTP Fallback:

No SSL certificates found - starting HTTP server
To enable HTTPS, place privkey.pem and fullchain.pem in ./certs/ directory
Server listening on http://localhost:8000

Test in browser:

https://YOUR-SERVER-IP:8000/health

Connecting Snappier App with HTTPS

When HTTPS is enabled, connect the Snappier IPTV app using:

• IP Address: Your server's IP (e.g., 192.168.1.100)
• Port: Your server port (e.g., 8000)
• SSL/HTTPS: Enable the HTTPS/SSL toggle in app settings

Important: For self-signed certificates, you may need to accept the certificate on your device first by visiting https://SERVER-IP:8000 in your mobile browser and accepting the security warning.

Troubleshooting

Server Not Starting in HTTPS Mode

• Verify certificate files exist:

  ls -la ./certs/

• Check file permissions:

  chmod 600 ./certs/privkey.pem
  chmod 644 ./certs/fullchain.pem

• Verify certificate validity:

  openssl x509 -in ./certs/fullchain.pem -text -noout

Browser Shows "Not Secure" Warning

This is expected for:

• Self-signed certificates (click "Advanced" → "Proceed anyway")
• Expired certificates (renew them)
• Certificates issued for different domain

For production, use Let's Encrypt or Caddy for trusted certificates.

Connection Refused on Port 443

By default, Snappier Server uses port 8000 (or your configured port), not 443. To use standard HTTPS port 443:

1. Change port to 443 in server settings
2. Run server with elevated privileges (required for ports < 1024):

   sudo ./snappier-server-cli --port 443

Or use a reverse proxy (Caddy, nginx) on port 443 forwarding to your server on 8000.

Removing HTTPS

To disable HTTPS and return to HTTP mode:

# Remove or rename certificates
rm -rf ./certs/

# Or move them
mv ./certs/ ./certs.backup/

# Restart server - it will automatically fall back to HTTP

Security Best Practices

• Protect private keys:

  chmod 600 ./certs/privkey.pem

• Never commit certificates to git: The certs/ directory is already in .gitignore
• Keep certificates updated: Set up automatic renewal for Let's Encrypt
• Use strong keys: Minimum 2048-bit RSA (4096-bit recommended)
• Monitor expiration: Let's Encrypt certs expire every 90 days

© 2025 Sarah Bainbridge