Snappier Server

• PORT — Listening port (default: 8000)
• HOST — Bind address (default: 0.0.0.0)
• ENABLE_REMUX — Convert .ts to .mkv after recording (default: false)
• ENABLE_COMSKIP — Run Comskip on finished recordings to write a sidecar .edl with commercial-break markers (default: false)
• COMSKIP_PATH — Override path to an external comskip binary (e.g. /usr/local/bin/comskip). Useful when the bundled binary is missing or you've built a newer version. Falls back to the bundled binary if the override isn't usable
• COMSKIP_INI — Override path to a comskip.ini tuning file. Takes precedence over <config-dir>/comskip.ini and the bundled ini
• RECORDINGS_FOLDER — Live TV recording output path (default: ~/SnappierServer/Recordings)
• MOVIES_FOLDER — Movie download output path (default: ~/SnappierServer/Movies)
• SERIES_FOLDER — TV series download output path (default: ~/SnappierServer/TVSeries)
• PVR_FOLDER — PVR data path (default: ~/SnappierServer/PVR)
• HLS_FOLDER — HLS transcoding temp directory (default: ~/SnappierServer/hls)
• EPG_FOLDER — EPG cache data path (default: ~/SnappierServer/epg)
• LOGS_FOLDER — Log file directory (default: ~/SnappierServer/logs/)
• DOWNLOAD_SPEED_LIMIT_MBS — Max curl download speed in MB/s (default: 0 = unlimited)
• MAX_CURL_RETRIES — Max retry attempts for curl downloads (default: 5)
• USE_CURL_TO_DOWNLOAD — Force curl for all downloads instead of FFmpeg (default: false)
• ENABLE_EPG — Enable EPG support (default: false)
• EPG_URL — Single EPG XML URL (deprecated — use EPG_URLS instead). If both are set, EPG_URLS takes precedence
• EPG_URLS — Multiple EPG sources as JSON array (takes precedence over EPG_URL)
• EPG_REFRESH_INTERVAL — Refresh interval in hours (default: 24)
• LOG_ROTATE_DAYS — Log rotation interval in days (default: 3)
• LOG_ROTATE_SIZE_MB — Max log file size before rotation in MB (default: 10)
• KEEP_ALIVE_TIMEOUT — HTTP keep-alive timeout in ms (default: 65000)
• HEADERS_TIMEOUT — HTTP headers timeout in ms (default: 66000)
• HLS_USE_HW — Enable hardware acceleration for HLS transcoding (default: false). Uses platform-specific encoders: VideoToolbox on macOS, VAAPI/NVENC on Linux
• HLS_VIDEO_ENCODER — Override the video encoder for HLS (e.g. h264_videotoolbox, h264_vaapi, h264_nvenc). If unset, uses libx264 or the hardware encoder when HLS_USE_HW is enabled

Setting Variables

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

# Windows (PowerShell)
$env:PORT = "9000"
$env:ENABLE_REMUX = "true"
.\snappier-server-cli.exe

# Windows (cmd)
set PORT=9000
set ENABLE_REMUX=true
snappier-server-cli.exe

To persist, add to ~/.bashrc, ~/.zshrc, or the systemd service file.

All arguments override environment variables. Run --help for the full list.

./snappier-server-cli --help

Server

--port 8080                          # Override listening port
--host 127.0.0.1                     # Bind address (default: 0.0.0.0)
--enable-remux                       # Convert .ts to .mkv after recording
--enable-comskip                     # Run Comskip on finished recordings (writes sidecar .edl)
--comskip-path /usr/local/bin/comskip  # Use an external comskip binary instead of the bundled one
--comskip-ini  /etc/snappier/comskip.ini  # Use a custom comskip.ini for detection tuning
--speed-limit 50                     # Download speed limit in MB/s

Config & Data Paths

--config /etc/snappier/config.json   # Custom config file (default: ~/SnappierServer/config.json)
--pvr-folder /mnt/data/pvr
--epg-folder /mnt/data/epg
--logs-folder /var/log/snappier
--recordings ~/Recordings
--movies ~/Movies
--series ~/TVShows

Logging

--log-rotate-days 7    # Rotate every N days (default: 3)
--log-rotate-size 20M  # Rotate at N MB (default: 10)

EPG

# Single source
--enable-epg --epg-url "http://example.com/epg.xml" --epg-interval 12

# Multiple sources (JSON)
--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}
]'

Full Example

./snappier-server-cli \
  --config /path/to/config.json \
  --port 8080 \
  --enable-epg \
  --epg-url "http://provider.com/epg.xml" \
  --epg-interval 24 \
  --enable-remux \
  --recordings ~/Recordings \
  --movies ~/Movies \
  --series ~/TVShows \
  --logs-folder /var/log/snappier \
  --log-rotate-days 7 \
  --log-rotate-size 20M \
  --epg-folder /mnt/data/epg \
  --pvr-folder /mnt/data/pvr

Snappier Server ships with a built-in browser-based dashboard. It runs on the same port as the API and requires no extra install — just point a browser at:

http://YOUR-SERVER-IP:8000/dashboard

The dashboard is the primary way to manage the server when you're not using the desktop app or the Snappier IPTV mobile app. It works on phones, tablets, and desktops, and supports both light and dark themes (toggle in the top nav).

Authentication

On first load you'll be prompted for the API token (auto-generated on first server launch — find it in the desktop Preferences window, the CLI console output, or ~/SnappierServer/config.json). The token is stored in localStorage so you only enter it once per browser. To rotate it, use Settings → Authentication → Regenerate.

Overview Cards

The home screen shows a live grid of count cards, each opening a detail modal:

• Scheduled Programs: upcoming one-shot and PVR recordings with start/stop times. Cancel from here.
• Recordings: completed live-TV recordings, organised into a browsable folder library (see Recordings Library below). Play in-browser, download, or delete.
• Streaming Devices: active HLS sessions (transcoding) and remux sessions, plus connected client info.
• Movies / TV Series: downloaded VOD content with metadata, posters, and play/delete actions.
• PVR Rules: active series/one-time rules and the next match found in the EPG.
• Reminders: programme reminders and their fire times.
• System stats: CPU, memory, and per-folder disk usage updated live over SSE.

Recordings Library

Recordings are grouped into a folder library rather than one long list, so a large back catalogue stays browsable. Click Recordings on the home screen, then drill down:

1. Programme folders. One folder per programme name, each showing its total size and a badge with the number of recordings it holds. A programme currently being recorded shows a REC badge instead and sorts to the front; otherwise the most recently recorded programme comes first.
2. The recordings. Opening a programme lists all of its recordings newest first, each with channel, date, size, and Watch / Delete buttons. The list is broken up by month headings that stay pinned as you scroll, so a daily show is still easy to read without a second folder to open.

Use the breadcrumb button at the top to go back to the folders. The search box filters at whatever level you're on, and it matches filenames and channel names as well as programme names — so searching for a file still surfaces the folder it lives in.

TV Guide (EPG Grid)

An interactive XMLTV-driven grid view. Browse channels by category, jump to "Now", scroll forward/back in time, and long-press / right-click any programme cell for actions: Watch live, Record once, Create PVR rule, or Set reminder. Live channel previews open in a built-in HLS player. Setup:

1. Dashboard → Settings → EPG → add or edit a source.
2. Tick Use for TV Guide (Xtream Codes). If your EPG URL is a standard Xtream xmltv.php URL, the hint below the tickbox turns green and reads "Xtream credentials auto-detected from URL" — you don't need to enter anything else. If it doesn't parse, fill in the host, username, and password fields that appear.
3. Click Save in the source editor, then Save again on the main Settings screen. Both are required — see the warning below.
4. Click TV Guide in the top nav.

When the toggle is set correctly the guide's first dropdown shows your source name and a second dropdown appears beside it listing your provider's categories, opening on the first category rather than every channel at once. Categories whose channels have no programme data are hidden automatically.

Settings Modal

Tabbed configuration UI — everything writes to config.json and most options apply without a restart (port changes are picked up live by the watcher):

• Server: port; toggles for Remux, Commercial Skipping (Comskip), and the alternative download engine; download speed limit; log rotation.
• Folders: per-purpose paths for Recordings, Movies, TV Series, PVR data, Logs, and EPG cache, with a folder browser.
• EPG: enable/disable EPG, manage multiple XMLTV sources with priorities, set refresh interval, mark a source for TV Guide use, and an Xtream URL helper.
• Auth: view, copy, and regenerate the API token.

Live Updates (SSE)

The dashboard subscribes to the server's Server-Sent Events stream, so you don't need to refresh. Job progress, recording starts/stops, remux completion, Comskip status, EPG refresh, PVR scans, and reminder fires all update the UI in real time. If the connection drops the dashboard reconnects automatically.

Mobile / Tablet

The layout collapses to a stacked card view on narrow screens; modals become full-screen sheets. The TV Guide grid is touch-scrollable with momentum.

Headless Servers

If you're running the CLI binary on a NAS or server with no GUI, the dashboard is your only management UI — everything the desktop Preferences window can do is also available here, plus the runtime panels (active jobs, logs, stats) that the desktop app doesn't have.

EPG (Electronic Programme Guide) provides programme listings for scheduling recordings and browsing the TV guide. Your IPTV provider supplies the EPG URL — look for "XMLTV URL", "EPG URL", or "TV Guide URL" in your provider's welcome email, customer portal, or app setup instructions. If you can't find it, contact your provider.

EPG URL Format

If your provider uses Xtream Codes (a common IPTV management system), construct the EPG URL from your provider's server details (not your Snappier Server):

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

GUI Setup

1. Tray icon → Preferences → EPG section
2. Enable EPG, paste your URL, name the source, set priority (1 = highest)
3. Set refresh interval (24h recommended), Save

Use for TV Guide (Xtream Codes)

Programme listings alone are enough to schedule recordings and create PVR rules. The Use for TV Guide (Xtream Codes) tickbox on a source does something extra: it fetches the live stream URLs and the channel category list from your provider's Xtream API. Without it the TV Guide has no categories to filter by, so it lists every channel at once and the category dropdown stays hidden.

Tick it on any source whose EPG URL is a standard Xtream xmltv.php URL — the host, username, and password are read straight from that URL, so there is nothing extra to type. For a non-Xtream EPG URL, tick it and fill in the host, username, and password fields that appear.

Once saved, the server fetches the category data immediately — no restart needed. To confirm it worked, check that the source has the flag set:

curl -H "X-API-Token: YOUR_TOKEN" http://localhost:8000/config | grep -o '"tvGuide":[^,}]*'

and look for a line like [Xtream] Total: 1234 channel URLs, 56 categories, … in the server log. If you instead see [Xtream] No EPG source is marked "Use for TV Guide", the flag didn't save.

CLI Setup

# Single source
./snappier-server-cli --enable-epg \
  --epg-url "http://iptv.example.com:8080/xmltv.php?username=user&password=pass"

# Multiple sources
./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}
]'

Verify

curl -H "X-API-Token: YOUR_TOKEN" http://localhost:8000/epg/status     # Source info & update times
curl -H "X-API-Token: YOUR_TOKEN" http://localhost:8000/epg/channels   # Detected channels
curl -H "X-API-Token: YOUR_TOKEN" -X POST http://localhost:8000/epg/refresh  # Force refresh

Troubleshooting

• No data: Verify URL returns XML in a browser. Check EPG is enabled. Wait for initial download.
• Stale data: POST /epg/refresh or reduce refresh interval.
• URL not working: Verify credentials. Try standard Xtream format. Contact your provider.
• TV Guide shows every channel with no category dropdown: no source has Use for TV Guide (Xtream Codes) ticked, or the change was never saved on the main Settings screen. See above.

PVR (Personal Video Recorder) creates rules that automatically schedule recordings when matching programmes appear in your EPG data. Like a DVR — set it once and the server records every matching episode.

Requirements

• EPG must be enabled and working
• Server should be running 24/7 for automatic scheduling

Rule Types

• Series: Records all future matching episodes continuously. Best for TV series and daily shows.
• One-time: Records only the next match, then auto-disables. Best for special events or one-off recordings.

How to Create Rules

• Snappier IPTV app: Long-press any programme in the EPG grid for recording options. Manage rules in the Server section.
• Web Dashboard: Open Settings → PVR Rules to create and manage rules.

How It Works

The server scans EPG data for matching programmes after each EPG refresh, on startup (2-second delay), or when you trigger a manual scan. Matched programmes are automatically scheduled for recording. You can exclude specific episodes you don't want.

Data Storage

PVR data is stored in the PVR_FOLDER (default: ~/SnappierServer/PVR/):

• pvr_rules.json — Recording rules
• pvr_exclusions.json — Excluded episodes
• Recordings saved as .ts (or .mkv with remuxing enabled)

Snappier Server bundles Comskip to detect commercial breaks in finished recordings. It is non-destructive — the original recording is untouched. Comskip writes a sidecar .edl file (Edit Decision List) next to the recording, and players that understand EDL (Kodi, MythTV, NextPVR, Jellyfin with the appropriate plugin) will skip those segments automatically on playback.

Enabling

• Web Dashboard: Settings → Server → Enable Commercial Skipping (Comskip).
• Desktop Preferences: Tick Enable Commercial Skipping.
• Environment: ENABLE_COMSKIP=true
• CLI: --enable-comskip

How It Works

When a live TV recording finishes (and remuxing completes if enabled), Comskip runs against the finished file. On completion the sidecar files are written next to the recording:

• recording.edl — commercial-break time ranges (used by players)
• recording.txt, recording.log, recording.logo.txt — diagnostic output (safe to delete)

Detection runs in the background — the recording is immediately playable, and EDL data appears once Comskip finishes. The recording's metadata (and dashboard listing) shows a comskip status of running, done, none, or failed. Live progress is also broadcast over the SSE event stream as comskipStarted / comskipDone / comskipFailed.

Platform Support

• macOS: Bundled binary for Apple Silicon (arm64). Intel Macs are not bundled — build from source if needed.
• Windows: Bundled comskip.exe (x86; runs on both 32-bit and 64-bit Windows).
• Linux: Bundled binaries for both x86_64 and aarch64 (ARM64). To rebuild from source: apt install autoconf libtool build-essential libargtable2-dev libavformat-dev, then ./autogen.sh && ./configure --without-sdl && make.

Tuning

Comskip's detection behaviour is controlled by comskip.ini, shipped alongside the binary. The bundled config produces standard EDL output; for fine-tuning (logo detection, channel-specific aspect ratios, sensitivity) consult the upstream sample ini.

Overriding the bundled binary or ini

You can point Snappier at an external comskip binary (e.g. a system-installed build) or a custom comskip.ini. Resolution order, highest precedence first:

1. Config file: comskip_path / comskip_ini in config.json (also accepts camelCase comskipPath / comskipIni). Picked up live when the config is saved — no restart needed.
2. Environment: COMSKIP_PATH / COMSKIP_INI.
3. CLI: --comskip-path <path> / --comskip-ini <path>.
4. Config-dir ini fallback: If no ini override is set, a comskip.ini placed next to your config.json is used in preference to the bundled one.
5. Bundled: The platform/arch-appropriate binary and ini shipped with Snappier.

If an override path is unreadable or non-executable, Snappier logs a warning and falls back to the next candidate. Example config.json snippet:

{
  "enable_comskip": true,
  "comskip_path": "/usr/local/bin/comskip",
  "comskip_ini": "/etc/snappier/comskip.ini"
}

Caveats

• Commercial detection is heuristic — expect occasional false positives or misses, especially on channels without clear ad breaks.
• Sidecar files are deleted automatically when you delete the recording from the dashboard.
• Detection runtime is roughly 5–15× faster than realtime depending on hardware.

The server auto-detects SSL certificates on startup and switches to HTTPS. The port stays the same (default 8000) — only the protocol changes. No certs = standard HTTP.

Certificate Paths (checked in order)

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

Required: privkey.pem and fullchain.pem

Let's Encrypt

sudo certbot certonly --standalone -d yourdomain.com

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

Reverse Proxy (Caddy)

# Caddyfile
yourdomain.com {
    reverse_proxy localhost:8000
}

caddy run

Caddy handles certificates, renewal, and HTTP-to-HTTPS redirect automatically.

Self-Signed (dev only)

mkdir -p ./certs
openssl req -x509 -newkey rsa:4096 \
  -keyout ./certs/privkey.pem \
  -out ./certs/fullchain.pem \
  -days 365 -nodes -subj "/CN=localhost"

Verify

# Check server logs:
# HTTPS: "SSL certificates found in ./certs - starting HTTPS server"
# HTTP:  "No SSL certificates found - starting HTTP server"

Certificate Reload

Certificates are read on startup only. After updating or renewing certificates, restart the server for changes to take effect.

App Connection

Enable the HTTPS/SSL toggle in Snappier IPTV settings. For self-signed certs, visit https://SERVER-IP:8000 in mobile Safari/Chrome first to accept the certificate.

• Config location: Desktop app stores config in the OS user-data directory (%APPDATA% / ~/Library/Application Support/ / ~/.config/). CLI defaults to ~/SnappierServer/config.json.
• CLI binary: The CLI is a standalone executable with Node.js bundled in. No runtime dependencies — just download and run.
• FFmpeg: Bundled on macOS/Windows (desktop app). Install separately on Linux and for all CLI installs.
• Recording format: .ts (MPEG Transport Stream). Enable remuxing to convert to .mkv for better compatibility with media players like Plex and VLC.
• Default storage: ~/SnappierServer/ (recordings, movies, series, PVR data). Override with env vars or CLI args.
• Port conflicts: If port 8000 is already in use, the server will fail to start with an EADDRINUSE error. Change the port with PORT=9000 or --port 9000.
• Firewall: Allow traffic on the configured port for cross-device access.
• VPN: The server and client must be able to reach each other over the network (same LAN, or routable via VPN).

Updating

Replace the binary or app with the new version. Your configuration, API token, and recordings are stored separately in ~/SnappierServer/ (CLI) or your OS user-data directory (desktop app) and persist across updates.

Uninstalling

• Windows: Delete the extracted folder. Remove %APPDATA%\snappierServer-electron if you want to clear config.
• macOS: Drag the app from Applications to Trash. Remove ~/Library/Application Support/snappierServer-electron for config.
• Linux: Delete the AppImage or CLI binary. Remove ~/.config/snappierServer-electron (desktop) or ~/SnappierServer (CLI) for config and data.

Desktop App vs CLI

Both share the same recording/download engine. The desktop app adds a Preferences UI, system tray with start/stop controls, a log viewer window, folder browser dialogs, and automatic port hot-reload when config changes. The CLI reads config once at startup.

Find Your IP

# Windows
ipconfig                    # Look for "IPv4 Address"

# macOS
ipconfig getifaddr en0      # Or check System Settings > Network

# Linux
hostname -I                 # Or: ip a

• hls.js — JavaScript HLS client using Media Source Extensions. Apache License 2.0. See THIRD_PARTY_LICENSES.txt.