Server Documentation

Overview

PlayOnTV Server is a lightweight, cross-platform personal media server that turns your local media collection into a streaming service. It scans your media folders, organizes content, and exposes it via standard IPTV protocols that any compatible player can connect to.

Key Features:

Scans local directories for video files (MP4, MKV, AVI, etc.)
Imports existing M3U playlists
Exposes content via M3U playlist URLs
Full Xtream Codes API compatibility
Embedded SQLite database - no external dependencies
Web-based admin interface
Cross-platform: Windows, macOS, Linux

Requirements

Platform	Requirements
Windows	Windows 10 or later (64-bit)
macOS	macOS 10.15 (Catalina) or later
Linux	64-bit distribution with glibc 2.17+

No additional software or databases required. PlayOnTV Server uses an embedded SQLite database.

Getting Started

1. Download and Run

Download the appropriate version for your platform and run the executable. On first launch, the server will:

Create a data directory for the database
Start the web interface on port 8080
Redirect you to the setup page to create an admin account

2. Initial Setup

Open your browser and navigate to:

http://localhost:8080

Create your admin account with a username and password. This will be used to access the admin interface and generate credentials for IPTV players.

3. Add Content Sources

In the admin interface, add your content sources:

Local Directory: Point to a folder containing your media files
M3U Playlist: Import an existing M3U/M3U8 playlist URL

After adding a source, click "Sync" to scan and import the content.

4. Connect Your Player

Go to "Credentials" in the admin interface to get your connection details. Use these to connect PlayOnTV app or any compatible IPTV player.

Configuration

Create a config.yaml file in the same directory as the server executable to customize settings:

        
# Server settings
server:
  host: "0.0.0.0"      # Listen on all interfaces
  port: 8080             # HTTP port
  base_url: ""          # External URL (for remote access)

# Security settings
security:
  max_connections_per_user: 0  # 0 = unlimited

# Database settings
database:
  path: "./data/iptv.db"
        
      

Note: For LAN streaming, set max_connections_per_user: 0 to allow unlimited connections. Video players often open multiple connections for seeking and buffering.

Connecting IPTV Players

PlayOnTV Player

In the PlayOnTV Player, add a new playlist using the Xtream Codes option:

Server URL: http://YOUR_SERVER_IP:8080
Username: Your admin username
Password: The stream token from the Credentials page

Other IPTV Players

PlayOnTV Server is compatible with any IPTV player that supports:

M3U Playlists: Use the M3U URL from the Credentials page
Xtream Codes API: Use the server URL, username, and token

Besides PlayOnTV Player, other compatible players include: TiviMate, IPTV Smarters, GSE Smart IPTV, VLC, and many others.

API Reference

Authentication

POST /api/auth/login

Authenticate and receive a JWT token for API access.

Content Sources

GET /api/sources

List all configured content sources.

POST /api/sources

Add a new content source (local directory or M3U URL).

POST /api/sources/:id/sync

Sync/scan a content source to import media.

Media Library

GET /api/library

List all media items in the library.

Playlist & Credentials

GET /api/playlist/credentials

Get M3U URL and Xtream credentials for connecting players.

GET /api/playlist/m3u?token=TOKEN

Download the M3U playlist.

Xtream Codes API

Full Xtream Codes API compatibility for IPTV players:

GET /player_api.php?username=X&password=Y&action=ACTION

Main Xtream API endpoint. Supported actions: get_live_categories, get_live_streams, get_vod_categories, get_vod_streams, get_series_categories, get_series, etc.

GET /movie/USERNAME/PASSWORD/STREAM_ID.EXT

Stream VOD content (movies, series episodes).

GET /live/USERNAME/PASSWORD/STREAM_ID.ts

Stream live content.

Supported Media Formats

PlayOnTV Server supports common video container formats:

Format	Extension	Notes
MP4	.mp4, .m4v	Recommended for best compatibility
Matroska	.mkv	Full support including multiple audio/subtitle tracks
AVI	.avi	Legacy format, fully supported
QuickTime	.mov	Apple QuickTime format
WebM	.webm	Open web media format
MPEG-TS	.ts, .m2ts	Transport stream format

Troubleshooting

Cannot connect from other devices

Ensure the server is running with host: "0.0.0.0"
Check your firewall allows connections on port 8080
Use your computer's LAN IP address (e.g., 192.168.1.x), not localhost

Video won't play / Error 429

Set max_connections_per_user: 0 in config.yaml
Restart the server after changing configuration

Media not showing after sync

Ensure files have supported extensions (.mp4, .mkv, etc.)
Check that the directory path is correct and accessible
Try syncing the source again

Legal Notice

PlayOnTV Server is designed for personal use with your own legally obtained media. You are responsible for ensuring you have the right to use, store, and stream any content you add to the server.

See our Terms of Use for complete details.