commit 28cdada37f5bc5eb0d767eda919111f80532c0ba Author: worldofiptvcom Date: Wed Dec 24 10:08:26 2025 +0000 Initial commit: Xtream Codes API Documentation Comprehensive API documentation for Xtream Codes IPTV Panel v2.9.2 Includes: - Complete endpoint reference for all 8 APIs - Request/response examples with curl commands - Authentication methods documentation - IPTV-specific patterns and integrations - Data models and error codes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 diff --git a/ENDPOINT_REFERENCE.md b/ENDPOINT_REFERENCE.md new file mode 100644 index 0000000..7a3d29d --- /dev/null +++ b/ENDPOINT_REFERENCE.md @@ -0,0 +1,197 @@ +# Xtream Codes API - Quick Endpoint Reference + +## Player API (`/player_api.php`) + +| Action | Method | Required Params | Description | +|--------|--------|-----------------|-------------| +| (default) | GET | username, password | Get user info & server info | +| get_live_categories | GET | username, password | List live TV categories | +| get_live_streams | GET | username, password, [category_id] | List live channels | +| get_vod_categories | GET | username, password | List VOD/movie categories | +| get_vod_streams | GET | username, password, [category_id] | List movies | +| get_vod_info | GET | username, password, vod_id | Get movie details | +| get_series_categories | GET | username, password | List series categories | +| get_series | GET | username, password, [category_id] | List TV series | +| get_series_info | GET | username, password, series_id | Get series details & episodes | +| get_short_epg | GET | username, password, stream_id, [limit] | Get current EPG for channel | +| get_simple_data_table | GET | username, password, stream_id | Get EPG in table format | + +--- + +## Panel API (`/panel_api.php`) + +| Action | Method | Required Params | Description | +|--------|--------|-----------------|-------------| +| (default) | GET | username, password | Get full data (user, server, categories, channels) | +| get_epg | GET | username, password, stream_id | Get EPG for stream | + +--- + +## Admin API (`/api.php`) + +**Note:** IP-restricted to authorized server IPs only. + +### Server Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| server/list | - | List all servers | + +### Stream Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| stream/start | stream_id | Start stream | +| stream/stop | stream_id | Stop stream | +| stream/list | - | List all streams | +| stream/online | - | List online streams | +| stream/offline | - | List offline streams | + +### VOD Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| vod/start | stream_id | Start VOD encoding | +| vod/stop | stream_id | Stop VOD encoding | + +### User Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| user/info | user_id OR username | Get user info | +| user/create | username, password, [many optional] | Create user | +| user/edit | user_id, [fields to update] | Edit user | + +### STB/MAG Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| stb/info | mag_id OR mac | Get STB info | +| stb/create | mac, user_id | Create STB | +| stb/edit | mag_id, [fields to update] | Edit STB | + +### Reseller Management +| Sub-action | Required Params | Description | +|------------|-----------------|-------------| +| reg_user/list | - | List resellers | +| reg_user/credits | reg_user_id | Get reseller credits | + +--- + +## MAG Portal API (`/portal.php`) + +### STB Actions (`type=stb`) +| Action | Required Params | Description | +|--------|-----------------|-------------| +| handshake | mac | Initial handshake, get token | +| get_profile | - | Get device profile | +| get_modules | - | Get available modules | +| get_localization | - | Get language strings | +| get_locales | - | Get available locales | +| get_timezones | - | Get timezones | +| get_preload_images | gmode | Get theme images | +| get_settings_profile | - | Get settings | +| set_volume | vol | Set volume | +| set_locale | locale | Set locale | +| set_parent_password | pass, repeat_pass | Set parental password | +| set_playback_buffer | playback_buffer_bytes, playback_buffer_size | Set buffer | + +### ITV Actions (`type=itv`) +| Action | Required Params | Description | +|--------|-----------------|-------------| +| get_genres | - | Get live categories | +| get_ordered_list | [genre, sortby, fav] | Get channel list | +| get_all_channels | - | Get all channels | +| get_all_fav_channels | [genre] | Get favorite channels | +| create_link | cmd | Generate stream URL | +| get_short_epg | ch_id | Get EPG for channel | +| get_epg_info | [period] | Get full EPG | +| set_fav | fav_ch | Set favorites (comma-separated) | +| get_fav_ids | - | Get favorite IDs | +| set_last_id | id | Set last watched | + +### VOD Actions (`type=vod`) +| Action | Required Params | Description | +|--------|-----------------|-------------| +| get_categories | - | Get VOD categories | +| get_ordered_list | [category, sortby, search, abc, genre, years, fav] | Get movies | +| create_link | cmd, [series] | Generate VOD URL | +| set_fav | video_id | Add to favorites | +| del_fav | video_id | Remove from favorites | +| get_years | - | Get available years | +| get_abc | - | Get alphabet filter | + +### Series Actions (`type=series`) +| Action | Required Params | Description | +|--------|-----------------|-------------| +| get_categories | - | Get series categories | +| get_ordered_list | [category, sortby, search, movie_id] | Get series | +| set_fav | video_id | Add to favorites | +| del_fav | video_id | Remove from favorites | + +### Watchdog Actions (`type=watchdog`) +| Action | Required Params | Description | +|--------|-----------------|-------------| +| get_events | - | Get pending events | +| confirm_event | event_active_id | Confirm event | + +--- + +## Enigma2 API (`/enigma2.php`) + +| Type | Required Params | Description | +|------|-----------------|-------------| +| (default) | username, password | Main menu | +| get_live_categories | username, password | Live categories | +| get_live_streams | username, password, [cat_id] | Live streams | +| get_vod_categories | username, password | VOD categories | +| get_vod_streams | username, password, [cat_id] | VOD streams | +| get_series_categories | username, password | Series categories | +| get_series | username, password, [cat_id] | Series list | +| get_seasons | username, password, series_id | Season list | +| get_series_streams | username, password, series_id, season | Episodes | + +--- + +## Streaming Endpoints + +### Live Streaming +``` +GET /live/{username}/{password}/{stream_id}.ts +GET /live/{username}/{password}/{stream_id}.m3u8 +GET /{username}/{password}/{stream_id} +``` + +### VOD Streaming +``` +GET /movie/{username}/{password}/{stream_id}.{ext} +Extensions: mp4, mkv, avi, 3gp, flv, wmv, mov, ts +``` + +### Series Streaming +``` +GET /series/{username}/{password}/{stream_id}.{ext} +``` + +### Timeshift/Catchup +``` +GET /timeshift/{username}/{password}/{duration}/{start}/{stream_id} +GET /timeshift/{username}/{password}/{duration}/{start}/{stream_id}.m3u8 +Start format: YYYY-MM-DD:HH-MM or YYYYMMDD-HH +``` + +### HLS Segments +``` +GET /hls/{username}/{password}/{stream_id}/{segment}.ts +``` + +--- + +## Other Endpoints + +### XMLTV/EPG +``` +GET /xmltv.php?username={user}&password={pass}&prev_days=1&next_days=3 +``` + +### Playlist Generator +``` +GET /get.php?username={user}&password={pass}&type=m3u_plus&output=ts +Types: m3u, m3u_plus, m3u8 +Outputs: ts, m3u8, rtmp +``` diff --git a/IPTV_PATTERNS_AND_INTEGRATIONS.md b/IPTV_PATTERNS_AND_INTEGRATIONS.md new file mode 100644 index 0000000..be8685d --- /dev/null +++ b/IPTV_PATTERNS_AND_INTEGRATIONS.md @@ -0,0 +1,424 @@ +# Xtream Codes - IPTV Patterns & Integrations + +## 1. Stream URL Patterns + +### Live TV URL Structure +``` +http://{server}:{port}/live/{username}/{password}/{stream_id}.{extension} +``` + +| Extension | Use Case | Content-Type | +|-----------|----------|--------------| +| .ts | MPEG Transport Stream (most compatible) | video/mp2t | +| .m3u8 | HLS Adaptive Streaming | application/x-mpegurl | + +### VOD URL Structure +``` +http://{server}:{port}/movie/{username}/{password}/{stream_id}.{extension} +``` + +Container extensions: mp4, mkv, avi, 3gp, flv, wmv, mov, ts + +### Series URL Structure +``` +http://{server}:{port}/series/{username}/{password}/{episode_stream_id}.{extension} +``` + +### Timeshift/Catchup URL Structure +``` +http://{server}:{port}/timeshift/{username}/{password}/{duration_minutes}/{start_time}/{stream_id} +``` + +Start time formats: +- `YYYY-MM-DD:HH-MM` (e.g., `2025-12-24:10-00`) +- `YYYYMMDD-HH` (e.g., `20251224-10`) + +--- + +## 2. M3U Playlist Format + +### Standard M3U Plus Format +```m3u +#EXTM3U +#EXTINF:-1 tvg-id="channel.epg" tvg-name="Channel Name" tvg-logo="http://icon.url" group-title="Category",Channel Name +http://server:25461/live/user/pass/123.ts +``` + +### Extended Attributes +| Attribute | Description | +|-----------|-------------| +| tvg-id | EPG channel identifier | +| tvg-name | Display name | +| tvg-logo | Channel icon URL | +| group-title | Category name | +| tvg-chno | Channel number | +| radio | "true" for radio streams | + +### Catchup Support Tags +```m3u +#EXTINF:-1 tvg-id="channel.epg" catchup="default" catchup-source="http://server:25461/timeshift/user/pass/{duration:60}/{start}/123.ts" catchup-days="7",Channel Name +``` + +--- + +## 3. EPG/XMLTV Integration + +### XMLTV Format +```xml + + + + + Channel Name + + + + Program Title + Description + News + + +``` + +### EPG URL +``` +http://server:25461/xmltv.php?username={user}&password={pass} +``` + +### EPG Mapping +The `tvg-id` attribute in M3U must match the `channel id` in XMLTV. + +--- + +## 4. MAG/Stalker Portal Integration + +### Authentication Flow +1. Device sends handshake with MAC address +2. Server returns token +3. Device includes token in all subsequent requests +4. Watchdog keeps session alive + +### Required Headers +``` +Authorization: Bearer {token} +Cookie: mac={mac_address}; timezone={timezone}; locale={locale} +X-User-Agent: Model: MAG254; Link: WiFi +``` + +### Stalker URL Encryption +For secure streaming, URLs are encrypted: +```php +$stalker_key = base64_encode(mc_encrypt("{$mac}={$ip}={$stream_id}={$expire_time}", $secret)); +``` + +### Event Types +| Event | Description | +|-------|-------------| +| send_msg | Display message | +| reboot | Reboot device | +| reload_portal | Reload portal | +| play_channel | Auto-tune to channel | +| cut_off | Disconnect device | + +--- + +## 5. Enigma2 Integration + +### Service Reference Format +Enigma2 uses service references for channels: +``` +#SERVICE 4097:0:1:0:0:0:0:0:0:0:http://server:25461/live/user/pass/123.ts:Channel Name +#DESCRIPTION Channel Name +``` + +### Bouquet File Format +``` +#NAME Provider Bouquet +#SERVICE 4097:0:1:0:0:0:0:0:0:0:http://server:25461/live/user/pass/123.ts:Channel 1 +#DESCRIPTION Channel 1 +#SERVICE 4097:0:1:0:0:0:0:0:0:0:http://server:25461/live/user/pass/124.ts:Channel 2 +#DESCRIPTION Channel 2 +``` + +### XML Response Format +All Enigma2 API responses use XML with Base64-encoded text: +```xml + + Q2hhbm5lbCBOYW1l + RGVzY3JpcHRpb24= + + +``` + +--- + +## 6. HLS Streaming + +### Playlist Structure +```m3u +#EXTM3U +#EXT-X-VERSION:3 +#EXT-X-TARGETDURATION:3 +#EXT-X-MEDIA-SEQUENCE:1000 +#EXTINF:3.0, +123_1000.ts?token=abc123 +#EXTINF:3.0, +123_1001.ts?token=def456 +#EXTINF:3.0, +123_1002.ts?token=ghi789 +``` + +### Segment Token Validation +Each segment URL includes a token: +``` +token = md5(segment_name + username + crypt_key + filesize) +``` + +### Connection Tracking +- HLS connections tracked via `user_activity_now` table +- `hls_last_read` timestamp updated per segment request +- Inactive HLS connections cleaned up by cron + +--- + +## 7. Load Balancing + +### Server Selection +Load balancer selects optimal server based on: +- Server load (active connections) +- Geographic proximity +- Server status (online/offline) +- Stream availability + +### Redirect Mechanism +```nginx +location /live/ { + proxy_pass http://load_balancer; +} +``` + +### Balance Configuration +`nginx/conf/balance.conf`: +```nginx +upstream streaming_servers { + server 192.168.1.1:25461 weight=5; + server 192.168.1.2:25461 weight=3; + server 192.168.1.3:25461 backup; +} +``` + +--- + +## 8. TV Archive/Catchup + +### Archive Storage +``` +/home/xtreamcodes/iptv_xtream_codes/tv_archive/{stream_id}/YYYY-MM-DD:HH-MM.ts +``` + +### Archive Duration +Configured per-stream via `tv_archive_duration` (days). + +### Timeshift Playback +```bash +# Last 60 minutes from channel 123 +curl "http://server/timeshift/user/pass/60/2025-12-24:10-00/123" + +# HLS format for player apps +curl "http://server/timeshift/user/pass/60/2025-12-24:10-00/123.m3u8" +``` + +--- + +## 9. Multi-Server Architecture + +### Server Roles +| Role | Description | +|------|-------------| +| Main | Database, panel, management | +| Load Balancer | Traffic distribution | +| Streaming | Stream transcoding/delivery | + +### Inter-Server Communication +Via `system_api.php`: +- Connection state synchronization +- Stream start/stop commands +- User activity tracking + +### Server Registration +Each server has unique `SERVER_ID` from config file. + +--- + +## 10. Authentication & Security + +### User Authentication Checks (in order) +1. Username/password validation +2. Account expiration check +3. Admin enabled check +4. User enabled check +5. IP whitelist check +6. Country restriction check +7. User agent validation +8. ISP restriction check +9. Max connections check +10. Bouquet access check + +### Security Features +| Feature | Description | +|---------|-------------| +| GeoIP | Country-based restrictions | +| ISP Lock | Restrict to specific ISPs | +| IP Whitelist | Per-user allowed IPs | +| UA Whitelist | Per-user allowed user agents | +| Max Connections | Concurrent connection limit | +| Flood Protection | Rate limiting failed auth | + +### Play Token System +For MAG devices: +``` +play_token = random_string:expire_timestamp:stream_id +``` +Validated before streaming to prevent URL sharing. + +--- + +## 11. Bouquet System + +### Bouquet Structure +Bouquets group streams and categories for user access control. + +```json +{ + "bouquet_id": 1, + "bouquet_name": "Basic Package", + "bouquet_channels": [1, 2, 3, 4, 5], + "bouquet_series": [10, 11, 12], + "bouquet_movies": [100, 101, 102] +} +``` + +### User Bouquet Assignment +```json +{ + "user_id": 100, + "bouquet": [1, 2, 3] // User has access to bouquets 1, 2, and 3 +} +``` + +### Category-Based Access +Categories can be assigned to bouquets for bulk access control. + +--- + +## 12. Reseller System + +### Reseller Hierarchy +``` +Admin +├── Reseller 1 +│ ├── User A +│ ├── User B +│ └── Sub-reseller 1.1 +│ └── User C +└── Reseller 2 + └── User D +``` + +### Credit System +Resellers have credits to create/extend users: +- 1 credit = 1 month subscription +- Credits deducted on user creation/extension +- Admin can add credits to resellers + +### Reseller Permissions +| Permission | Description | +|------------|-------------| +| add_user | Can create users | +| edit_user | Can modify own users | +| delete_user | Can delete own users | +| add_mag | Can register MAG devices | +| add_e2 | Can register Enigma2 | +| allowed_ips | Restrict reseller panel access | + +--- + +## 13. Output Formats + +### User-Allowed Formats +```json +{ + "allowed_output_formats": ["ts", "m3u8", "rtmp"] +} +``` + +### Format Handling +| Format | Handler | Use Case | +|--------|---------|----------| +| ts | clients_live.php | Direct streaming | +| m3u8 | clients_live.php | HLS adaptive | +| rtmp | rtmp handler | Flash players | + +### Container Mapping +```php +$containers = [ + 'ts' => 'video/mp2t', + 'm3u8' => 'application/x-mpegurl', + 'mp4' => 'video/mp4', + 'mkv' => 'video/x-matroska', + 'avi' => 'video/x-msvideo' +]; +``` + +--- + +## 14. Client Activity Tracking + +### Activity Table Structure +```sql +user_activity_now ( + activity_id INT PRIMARY KEY, + user_id INT, + stream_id INT, + server_id INT, + user_agent VARCHAR, + user_ip VARCHAR, + container VARCHAR, + pid INT, + date_start INT, + geoip_country_code VARCHAR, + isp VARCHAR, + external_device VARCHAR, + hls_last_read INT, + hls_end TINYINT +) +``` + +### Connection Lifecycle +1. INSERT on stream start +2. UPDATE `hls_last_read` for HLS +3. DELETE on stream end +4. Archive to `user_activity` for history + +--- + +## 15. Error Handling Patterns + +### Graceful Degradation +```php +// Show alternative video on errors +ipTV_streaming::ShowVideo($is_restreamer, 'show_not_on_air_video', 'not_on_air_video_path', $extension); +``` + +### Video Placeholders +| Setting | Description | +|---------|-------------| +| show_expired_video | Show when user expired | +| show_banned_video | Show when user banned | +| show_not_on_air_video | Show when stream offline | + +### Client Logging +All access attempts logged for debugging: +```php +ipTV_streaming::ClientLog($stream_id, $user_id, 'ERROR_CODE', $user_ip, $extra_data); +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..ede9c90 --- /dev/null +++ b/README.md @@ -0,0 +1,118 @@ +# Xtream Codes IPTV Panel - API Documentation + +This documentation package provides comprehensive analysis of all API endpoints in the Xtream Codes v2.9.2 IPTV panel. + +## Documentation Files + +| File | Description | +|------|-------------| +| [XTREAM_CODES_API_DOCUMENTATION.md](XTREAM_CODES_API_DOCUMENTATION.md) | **Main Documentation** - Complete API reference with all endpoints, parameters, responses, and examples | +| [ENDPOINT_REFERENCE.md](ENDPOINT_REFERENCE.md) | Quick reference table of all endpoints and their parameters | +| [IPTV_PATTERNS_AND_INTEGRATIONS.md](IPTV_PATTERNS_AND_INTEGRATIONS.md) | IPTV-specific patterns, integrations, and technical details | + +## API Summary + +### Discovered APIs + +| API | Endpoint | Auth Method | Purpose | +|-----|----------|-------------|---------| +| Player API | `/player_api.php` | Username/Password | Client applications | +| Panel API | `/panel_api.php` | Username/Password | Panel applications | +| Admin API | `/api.php` | IP-Based | Server management | +| System API | `/system_api.php` | IP-Based | Inter-server communication | +| MAG Portal | `/portal.php` | MAC/Token | MAG STB devices | +| Enigma2 | `/enigma2.php` | Username/Password | Enigma2 receivers | +| EPG/XMLTV | `/xmltv.php` | Username/Password | Program guide | +| Playlist | `/get.php` | Username/Password | M3U generation | + +### Streaming Endpoints + +| Type | URL Pattern | +|------|-------------| +| Live TV | `/live/{user}/{pass}/{stream_id}.{ts\|m3u8}` | +| VOD/Movies | `/movie/{user}/{pass}/{stream_id}.{ext}` | +| TV Series | `/series/{user}/{pass}/{stream_id}.{ext}` | +| Timeshift | `/timeshift/{user}/{pass}/{duration}/{start}/{stream_id}` | +| HLS Segments | `/hls/{user}/{pass}/{stream_id}/{segment}.ts` | + +## Quick Start + +### 1. Authenticate +```bash +curl "http://SERVER:25461/player_api.php?username=USER&password=PASS" +``` + +### 2. Get Live Channels +```bash +curl "http://SERVER:25461/player_api.php?username=USER&password=PASS&action=get_live_streams" +``` + +### 3. Play Stream +```bash +ffplay "http://SERVER:25461/live/USER/PASS/STREAM_ID.ts" +``` + +## Key Findings + +### Total API Endpoints Documented +- **Player API**: 10 actions +- **Panel API**: 2 actions +- **Admin API**: 15+ sub-actions +- **MAG Portal**: 40+ type/action combinations +- **Enigma2 API**: 10 types +- **Streaming**: 5 endpoint patterns + +### Authentication Methods +1. Username/Password (most common) +2. IP-Based (admin APIs) +3. MAC Address + Token (MAG devices) +4. Play Token (secure streaming) + +### Security Features +- GeoIP country restrictions +- ISP locking +- IP whitelisting +- User agent filtering +- Rate limiting (20 req/sec) +- Flood protection +- Max connection limits + +### Output Formats +- Transport Stream (TS) +- HLS (M3U8) +- MP4, MKV, AVI, FLV, WMV, MOV, 3GP +- XML (Enigma2, XMLTV) +- JSON (Player/Panel APIs) + +## Source Code Analyzed + +``` +/home/xtream-codes-decoded/ +├── wwwdir/ +│ ├── api.php # Admin API +│ ├── player_api.php # Player API +│ ├── panel_api.php # Panel API +│ ├── system_api.php # System API +│ ├── portal.php # MAG Portal (1300+ lines) +│ ├── enigma2.php # Enigma2 API +│ ├── xmltv.php # EPG/XMLTV +│ ├── get.php # Playlist generator +│ ├── init.php # Bootstrap +│ ├── includes/ +│ │ ├── functions.php +│ │ ├── lib.php +│ │ ├── streaming.php +│ │ └── mysql.php +│ └── streaming/ +│ ├── clients_live.php # Live streaming +│ ├── clients_movie.php # VOD streaming +│ └── timeshift.php # Catchup +└── nginx/conf/ + └── nginx.conf # URL routing +``` + +## Analysis Date +December 24, 2025 + +## Software Version +Xtream Codes v2.9.2 diff --git a/XTREAM_CODES_API_DOCUMENTATION.md b/XTREAM_CODES_API_DOCUMENTATION.md new file mode 100644 index 0000000..3d05109 --- /dev/null +++ b/XTREAM_CODES_API_DOCUMENTATION.md @@ -0,0 +1,1763 @@ +# Xtream Codes IPTV Panel - Comprehensive API Documentation + +**Version:** 2.9.2 +**Analysis Date:** 2025-12-24 +**Codebase Location:** /home/xtream-codes-decoded + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Base Configuration](#base-configuration) +3. [Authentication Methods](#authentication-methods) +4. [Rate Limiting & Security](#rate-limiting--security) +5. [API Categories](#api-categories) +6. [Player API Endpoints](#1-player-api-player_apiphp) +7. [Panel API Endpoints](#2-panel-api-panel_apiphp) +8. [Admin/Management API Endpoints](#3-adminmanagement-api-apiphp) +9. [System API Endpoints](#4-system-api-system_apiphp) +10. [MAG Portal API Endpoints](#5-mag-portal-api-portalphp) +11. [Enigma2 API Endpoints](#6-enigma2-api-enigma2php) +12. [Streaming Endpoints](#7-streaming-endpoints) +13. [Data Models](#data-models) +14. [Error Codes](#error-codes) +15. [Integration Guide](#integration-guide) + +--- + +## Overview + +Xtream Codes is an IPTV panel management system that provides APIs for: +- User authentication and management +- Live TV streaming +- Video on Demand (VOD/Movies) +- TV Series management +- Electronic Program Guide (EPG) +- MAG/Stalker portal support +- Enigma2 device support +- Multi-server load balancing + +--- + +## Base Configuration + +### Default Ports +| Service | Port | Protocol | +|---------|------|----------| +| HTTP | 25461 | HTTP | +| HTTPS | 25463 | HTTPS/SSL | +| MySQL | 7999 | TCP | + +### Base URL Pattern +``` +http://{server_ip}:{port}/ +https://{server_ip}:{port}/ +``` + +### Directory Structure +``` +/home/xtreamcodes/iptv_xtream_codes/ +├── wwwdir/ # Web root +│ ├── api.php # Admin API +│ ├── player_api.php # Player/Client API +│ ├── panel_api.php # Panel API +│ ├── system_api.php # System API +│ ├── portal.php # MAG Portal API +│ ├── enigma2.php # Enigma2 API +│ ├── xmltv.php # EPG/XMLTV API +│ ├── get.php # Playlist Generator +│ └── streaming/ # Streaming handlers +├── streams/ # Live stream segments +├── movies/ # VOD files +├── tv_archive/ # TV Archive/Catchup +└── tmp/ # Temporary files +``` + +--- + +## Authentication Methods + +### 1. Username/Password Authentication (Most Common) +Used by: Player API, Panel API, Streaming Endpoints + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| username | string | Yes | User's login username | +| password | string | Yes | User's login password | + +**Example:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123" +``` + +### 2. IP-Based Authentication (Admin API) +Used by: Admin/Management API + +The Admin API restricts access based on server IP addresses. Only requests from authorized server IPs are accepted. + +**Source:** `api.php:5-8` +```php +if (!in_array(ipTV_streaming::getUserIP(), array_column(ipTV_lib::$StreamingServers, 'server_ip'))) { + die; +} +``` + +### 3. MAC Address Authentication (MAG Portal) +Used by: MAG Portal API + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| mac | string | Yes | Device MAC address | +| sn | string | No | Serial number | +| stb_type | string | No | STB device type | +| ver | string | No | Firmware version | + +### 4. Token-Based Authentication (HLS/Stalker) +Used for secure HLS streaming and MAG device sessions. + +**Token Generation:** +- Handshake generates a random token: `strtoupper(md5(uniqid(rand(), true)))` +- Token stored in database and sent to device +- Required in Authorization header: `Authorization: Bearer {token}` + +--- + +## Rate Limiting & Security + +### Nginx Rate Limiting +**Source:** `nginx/conf/nginx.conf:34` +```nginx +limit_req_zone $binary_remote_addr zone=one:10m rate=20r/s; +``` +- **Rate:** 20 requests per second per IP +- **Burst:** Configured per location +- **Zone:** 10MB shared memory + +### Flood Protection +Failed authentication attempts trigger flood protection: +- Tracked in database `blocked_ips` table +- Configurable block duration +- Implemented via `CheckFlood()` function + +### GeoIP Restrictions +- Uses MaxMind GeoLite2 database +- Per-user country restrictions +- Global allowed countries list +- ISP-based restrictions + +### User Agent Validation +- Empty user agents can be blocked +- Per-user allowed user agent lists +- Global blocked user agent patterns + +--- + +## API Categories + +| Category | Endpoint | Authentication | Purpose | +|----------|----------|----------------|---------| +| Player API | `/player_api.php` | Username/Password | Client apps, media players | +| Panel API | `/panel_api.php` | Username/Password | Panel applications | +| Admin API | `/api.php` | IP-Based | Server management | +| System API | `/system_api.php` | IP-Based | Inter-server communication | +| MAG Portal | `/portal.php` | MAC/Token | MAG/Stalker devices | +| Enigma2 | `/enigma2.php` | Username/Password | Enigma2 receivers | +| EPG/XMLTV | `/xmltv.php` | Username/Password | Program guide data | +| Playlist | `/get.php` | Username/Password | M3U playlist generation | +| Live Streaming | `/live/...` | Username/Password | Live TV streams | +| VOD Streaming | `/movie/...` | Username/Password | Movie/VOD streams | +| Series Streaming | `/series/...` | Username/Password | TV series streams | +| Timeshift | `/timeshift/...` | Username/Password | Catch-up TV | + +--- + +## 1. Player API (`player_api.php`) + +**Source:** `wwwdir/player_api.php` + +The Player API is the primary interface for client applications (IPTV players, mobile apps). + +### Authentication +``` +GET /player_api.php?username={username}&password={password} +``` + +### Default Action (User & Server Info) +Returns user account information and server details. + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123" +``` + +**Response:** +```json +{ + "user_info": { + "username": "user1", + "password": "pass123", + "message": "Welcome message", + "auth": 1, + "status": "Active", + "exp_date": "1735689600", + "is_trial": "0", + "active_cons": "1", + "created_at": "1609459200", + "max_connections": "2", + "allowed_output_formats": ["ts", "m3u8"] + }, + "server_info": { + "url": "http://server.example.com", + "port": "25461", + "https_port": "25463", + "server_protocol": "http", + "rtmp_port": "25462", + "timezone": "Europe/London", + "timestamp_now": 1735084800, + "time_now": "2025-12-24 12:00:00" + } +} +``` + +**Source:** `player_api.php:110-153` + +--- + +### GET Live Categories +**Action ID:** 201 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_categories" +``` + +**Response:** +```json +[ + { + "category_id": "1", + "category_name": "Sports", + "parent_id": 0 + }, + { + "category_id": "2", + "category_name": "Movies", + "parent_id": 0 + } +] +``` + +**Source:** `player_api.php:24-28` + +--- + +### GET Live Streams +**Action ID:** 202 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_streams" +# Optional: Filter by category +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_streams&category_id=1" +``` + +**Response:** +```json +[ + { + "num": 1, + "name": "Channel Name", + "stream_type": "live", + "stream_id": 123, + "stream_icon": "http://example.com/icon.png", + "epg_channel_id": "channel.epg", + "added": "1609459200", + "category_id": "1", + "custom_sid": "", + "tv_archive": 1, + "direct_source": "", + "tv_archive_duration": 7 + } +] +``` + +**Source:** `player_api.php:29-33` + +--- + +### GET VOD Categories +**Action ID:** 200 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_categories" +``` + +**Response:** +```json +[ + { + "category_id": "10", + "category_name": "Action", + "parent_id": 0 + } +] +``` + +--- + +### GET VOD Streams +**Action ID:** 203 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_streams" +# Optional: Filter by category +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_streams&category_id=10" +``` + +**Response:** +```json +[ + { + "num": 1, + "name": "Movie Title", + "stream_type": "movie", + "stream_id": 456, + "stream_icon": "http://example.com/poster.jpg", + "rating": "8.5", + "rating_5based": 4.25, + "added": "1609459200", + "category_id": "10", + "container_extension": "mkv", + "custom_sid": "", + "direct_source": "" + } +] +``` + +--- + +### GET VOD Info +**Action ID:** 209 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_info&vod_id=456" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| vod_id | integer | Yes | Movie/VOD stream ID | + +**Response:** +```json +{ + "info": { + "movie_image": "http://example.com/poster.jpg", + "tmdb_id": "12345", + "backdrop_path": ["http://example.com/backdrop.jpg"], + "youtube_trailer": "dQw4w9WgXcQ", + "genre": "Action, Adventure", + "plot": "Movie description...", + "cast": "Actor 1, Actor 2", + "rating": "8.5", + "director": "Director Name", + "releasedate": "2025-01-01", + "duration_secs": 7200, + "duration": "02:00:00" + }, + "movie_data": { + "stream_id": 456, + "name": "Movie Title", + "added": "1609459200", + "category_id": "10", + "container_extension": "mkv" + } +} +``` + +**Source:** `player_api.php:60-76` + +--- + +### GET Series Categories +**Action ID:** 206 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series_categories" +``` + +**Response:** +```json +[ + { + "category_id": "20", + "category_name": "Drama", + "parent_id": 0 + } +] +``` + +--- + +### GET Series +**Action ID:** 208 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series" +# Optional: Filter by category +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series&category_id=20" +``` + +**Response:** +```json +[ + { + "num": 1, + "name": "Series Title", + "series_id": 789, + "cover": "http://example.com/cover.jpg", + "plot": "Series description...", + "cast": "Actor 1, Actor 2", + "director": "Director Name", + "genre": "Drama", + "releaseDate": "2025-01-01", + "last_modified": "1609459200", + "rating": "9.0", + "rating_5based": 4.5, + "backdrop_path": ["http://example.com/backdrop.jpg"], + "youtube_trailer": "abc123", + "episode_run_time": "45", + "category_id": "20" + } +] +``` + +--- + +### GET Series Info +**Action ID:** 204 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series_info&series_id=789" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| series_id | integer | Yes | Series ID | + +**Response:** +```json +{ + "seasons": [ + { + "air_date": "2025-01-01", + "episode_count": 10, + "id": 1, + "name": "Season 1", + "overview": "Season description...", + "season_number": 1, + "cover": "http://example.com/season1.jpg", + "cover_big": "http://example.com/season1_big.jpg" + } + ], + "info": { + "name": "Series Title", + "cover": "http://example.com/cover.jpg", + "plot": "Series description...", + "cast": "Actor 1, Actor 2", + "director": "Director Name", + "genre": "Drama", + "releaseDate": "2025-01-01", + "last_modified": "1609459200", + "rating": "9.0", + "rating_5based": 4.5, + "backdrop_path": ["http://example.com/backdrop.jpg"], + "youtube_trailer": "abc123", + "episode_run_time": "45", + "category_id": "20" + }, + "episodes": { + "1": [ + { + "id": "1001", + "episode_num": 1, + "title": "Episode 1 Title", + "container_extension": "mkv", + "info": { + "movie_image": "http://example.com/ep1.jpg", + "plot": "Episode description...", + "releasedate": "2025-01-01", + "rating": "8.5", + "duration_secs": 2700, + "duration": "00:45:00" + } + } + ] + } +} +``` + +**Source:** `player_api.php:39-54` + +--- + +### GET Short EPG +**Action ID:** 205 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_short_epg&stream_id=123" +# Optional: Limit results +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_short_epg&stream_id=123&limit=5" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| stream_id | integer | Yes | Live stream ID | +| limit | integer | No | Number of EPG entries (default: 4) | + +**Response:** +```json +{ + "epg_listings": [ + { + "id": "12345", + "epg_id": "67", + "title": "Program Title", + "lang": "en", + "start": "2025-12-24 12:00:00", + "end": "2025-12-24 13:00:00", + "description": "Program description...", + "channel_id": "channel.epg", + "start_timestamp": 1735041600, + "stop_timestamp": 1735045200, + "now_playing": 1, + "has_archive": 1 + } + ] +} +``` + +**Source:** `player_api.php:55-58` + +--- + +### GET Simple Data Table +**Action ID:** 207 + +**Request:** +```bash +curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_simple_data_table&stream_id=123" +``` + +Returns EPG data in a simplified table format. + +--- + +## 2. Panel API (`panel_api.php`) + +**Source:** `wwwdir/panel_api.php` + +The Panel API provides comprehensive data for panel applications with all content in a single response. + +### Default Action (Full Data) +Returns complete user info, server info, and all available content. + +**Request:** +```bash +curl "http://server:25461/panel_api.php?username=user1&password=pass123" +``` + +**Response:** +```json +{ + "user_info": { + "username": "user1", + "password": "pass123", + "message": "", + "auth": 1, + "status": "Active", + "exp_date": "1735689600", + "is_trial": "0", + "active_cons": "1", + "created_at": "1609459200", + "max_connections": "2", + "allowed_output_formats": ["ts", "m3u8"] + }, + "server_info": { + "url": "http://server.example.com", + "port": "25461", + "https_port": "25463", + "server_protocol": "http", + "rtmp_port": "25462", + "timezone": "Europe/London", + "timestamp_now": 1735084800, + "time_now": "2025-12-24 12:00:00" + }, + "categories": { + "live": [...], + "movie": [...], + "series": [...] + }, + "available_channels": [...] +} +``` + +**Source:** `panel_api.php:44-98` + +--- + +### GET EPG +**Request:** +```bash +curl "http://server:25461/panel_api.php?username=user1&password=pass123&action=get_epg&stream_id=123" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| stream_id | integer | Yes | Live stream ID | + +**Response:** +```json +{ + "epg_listings": [ + { + "id": "12345", + "epg_id": "67", + "title": "Program Title", + "lang": "en", + "start": "2025-12-24 12:00:00", + "end": "2025-12-24 13:00:00", + "description": "Program description...", + "channel_id": "channel.epg" + } + ] +} +``` + +**Source:** `panel_api.php:16-42` + +--- + +## 3. Admin/Management API (`api.php`) + +**Source:** `wwwdir/api.php` + +**Important:** This API is IP-restricted. Only requests from authorized streaming server IPs are accepted. + +### Authentication +No username/password required - authentication is IP-based. + +--- + +### List Servers +**Request:** +```bash +curl "http://server:25461/api.php?action=server&sub=list" +``` + +**Response:** +```json +{ + "servers": [ + { + "id": 1, + "server_name": "Main Server", + "server_ip": "192.168.1.1", + "vpn_ip": null, + "http_broadcast_port": "25461", + "total_clients": 100, + "status": "online" + } + ] +} +``` + +**Source:** `api.php:14-20` + +--- + +### Stream Control + +#### Start Stream +```bash +curl "http://server:25461/api.php?action=stream&sub=start&stream_id=123" +``` + +#### Stop Stream +```bash +curl "http://server:25461/api.php?action=stream&sub=stop&stream_id=123" +``` + +#### List Streams +```bash +curl "http://server:25461/api.php?action=stream&sub=list" +``` + +#### Get Online Streams +```bash +curl "http://server:25461/api.php?action=stream&sub=online" +``` + +#### Get Offline Streams +```bash +curl "http://server:25461/api.php?action=stream&sub=offline" +``` + +**Source:** `api.php:40-76` + +--- + +### VOD Control + +#### Start VOD Encoding +```bash +curl "http://server:25461/api.php?action=vod&sub=start&stream_id=456" +``` + +#### Stop VOD Encoding +```bash +curl "http://server:25461/api.php?action=vod&sub=stop&stream_id=456" +``` + +**Source:** `api.php:21-39` + +--- + +### User Management + +#### Get User Info +```bash +curl "http://server:25461/api.php?action=user&sub=info&user_id=100" +# Or by username +curl "http://server:25461/api.php?action=user&sub=info&username=user1" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| user_id | integer | Yes* | User ID | +| username | string | Yes* | Username (alternative to user_id) | + +**Response:** +```json +{ + "user_info": { + "user_id": 100, + "username": "user1", + "password": "pass123", + "exp_date": 1735689600, + "max_connections": 2, + "is_restreamer": 0, + "is_trial": 0, + "created_at": 1609459200, + "created_by": 1, + "admin_enabled": 1, + "enabled": 1, + "bouquet": [1, 2, 3], + "allowed_ips": [], + "allowed_ua": [], + "forced_country": "ALL" + } +} +``` + +**Source:** `api.php:92-131` + +--- + +#### Create User +```bash +curl -X POST "http://server:25461/api.php" \ + -d "action=user" \ + -d "sub=create" \ + -d "username=newuser" \ + -d "password=newpass" \ + -d "max_connections=2" \ + -d "exp_date=1735689600" \ + -d "bouquet=[1,2,3]" \ + -d "reseller_id=5" +``` + +**Parameters:** +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| username | string | Yes | New username | +| password | string | Yes | Password | +| max_connections | integer | No | Max simultaneous connections | +| exp_date | integer | No | Expiration timestamp (null = never) | +| bouquet | array/json | No | Bouquet IDs | +| reseller_id | integer | No | Owner reseller ID | +| is_restreamer | integer | No | 0=normal user, 1=restreamer | +| is_trial | integer | No | 0=paid, 1=trial | +| allowed_ips | array | No | Allowed IP addresses | +| allowed_ua | array | No | Allowed user agents | +| forced_country | string | No | Country code restriction | + +**Response:** +```json +{ + "result": true, + "user_id": 101, + "username": "newuser" +} +``` + +**Source:** `api.php:160-223` + +--- + +#### Edit User +```bash +curl -X POST "http://server:25461/api.php" \ + -d "action=user" \ + -d "sub=edit" \ + -d "user_id=100" \ + -d "max_connections=3" \ + -d "exp_date=1767225600" +``` + +**Parameters:** +Same as Create User, plus: +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| user_id | integer | Yes | User ID to edit | + +**Source:** `api.php:132-159` + +--- + +### STB (MAG Device) Management + +#### Get STB Info +```bash +curl "http://server:25461/api.php?action=stb&sub=info&mag_id=50" +# Or by MAC address +curl "http://server:25461/api.php?action=stb&sub=info&mac=00:1A:79:XX:XX:XX" +``` + +#### Create STB +```bash +curl -X POST "http://server:25461/api.php" \ + -d "action=stb" \ + -d "sub=create" \ + -d "mac=00:1A:79:XX:XX:XX" \ + -d "user_id=100" +``` + +#### Edit STB +```bash +curl -X POST "http://server:25461/api.php" \ + -d "action=stb" \ + -d "sub=edit" \ + -d "mag_id=50" \ + -d "user_id=101" +``` + +**Source:** `api.php:224-294` + +--- + +### Reseller Management + +#### List Resellers +```bash +curl "http://server:25461/api.php?action=reg_user&sub=list" +``` + +#### Get Reseller Credits +```bash +curl "http://server:25461/api.php?action=reg_user&sub=credits®_user_id=5" +``` + +**Source:** `api.php:77-91` + +--- + +## 4. System API (`system_api.php`) + +**Source:** `wwwdir/system_api.php` + +Internal API for server-to-server communication. IP-restricted. + +### Save Opened Connections +```bash +curl -X POST "http://server:25461/system_api.php" \ + -d "action=save_opened_cons" \ + -d "data={json_encoded_connections}" +``` + +### Save Closed Connections +```bash +curl -X POST "http://server:25461/system_api.php" \ + -d "action=save_closed_cons" \ + -d "data={json_encoded_connections}" +``` + +### Kill Connection +```bash +curl "http://server:25461/system_api.php?action=pid_kill&activity_id=12345" +``` + +### Redirect Connection +```bash +curl "http://server:25461/system_api.php?action=pid_redirect&activity_id=12345&stream_id=456" +``` + +### Get Active Connections +```bash +curl "http://server:25461/system_api.php?action=get_active_cons&server_id=1" +``` + +**Source:** `system_api.php:1-80` + +--- + +## 5. MAG Portal API (`portal.php`) + +**Source:** `wwwdir/portal.php` + +Stalker/MAG middleware portal API for MAG set-top boxes. + +### Handshake +**Request:** +```bash +curl "http://server:25461/portal.php?type=stb&action=handshake&mac=00:1A:79:XX:XX:XX" +``` + +**Response:** +```json +{ + "js": { + "token": "A1B2C3D4E5F6..." + } +} +``` + +**Source:** `portal.php:29-38` + +--- + +### Get Profile +**Request:** +```bash +curl "http://server:25461/portal.php?type=stb&action=get_profile" \ + -H "Authorization: Bearer {token}" \ + -H "Cookie: mac=00:1A:79:XX:XX:XX" +``` + +**Response:** +```json +{ + "js": { + "id": 1, + "name": "MAG Device", + "mac": "00:1A:79:XX:XX:XX", + "status": 0, + "hd": "1", + "locale": "en_GB.utf8", + "default_timezone": "Europe/London", + "allowed_stb_types": ["MAG250", "MAG254", "MAG322"], + "watchdog_timeout": 100, + ... + } +} +``` + +**Source:** `portal.php:64-90` + +--- + +### Get Modules +**Request:** +```bash +curl "http://server:25461/portal.php?type=stb&action=get_modules" +``` + +**Response:** +```json +{ + "js": { + "all_modules": ["tv", "vclub", "sclub", "radio", "apps", ...], + "disabled_modules": ["karaoke", "game.mastermind", ...], + "template": "default" + } +} +``` + +**Source:** `portal.php:97-99` + +--- + +### ITV (Live TV) Actions + +#### Get Genres (Categories) +```bash +curl "http://server:25461/portal.php?type=itv&action=get_genres" +``` + +#### Get Ordered List (Channels) +```bash +curl "http://server:25461/portal.php?type=itv&action=get_ordered_list" +# With filters +curl "http://server:25461/portal.php?type=itv&action=get_ordered_list&genre=1&sortby=number&fav=1" +``` + +#### Get All Channels +```bash +curl "http://server:25461/portal.php?type=itv&action=get_all_channels" +``` + +#### Create Link (Generate Stream URL) +```bash +curl "http://server:25461/portal.php?type=itv&action=create_link&cmd=http://localhost/ch/123" +``` + +**Response:** +```json +{ + "js": { + "id": 123, + "cmd": "ffmpeg http://server:25461/live/user/pass/123.ts" + } +} +``` + +**Source:** `portal.php:293-309` + +#### Get Short EPG +```bash +curl "http://server:25461/portal.php?type=itv&action=get_short_epg&ch_id=123" +``` + +#### Get EPG Info (Full) +```bash +curl "http://server:25461/portal.php?type=itv&action=get_epg_info&period=3" +``` + +#### Set Favorite +```bash +curl "http://server:25461/portal.php?type=itv&action=set_fav&fav_ch=123,456,789" +``` + +#### Get Favorite IDs +```bash +curl "http://server:25461/portal.php?type=itv&action=get_fav_ids" +``` + +**Source:** `portal.php:291-474` + +--- + +### VOD Actions + +#### Get Categories +```bash +curl "http://server:25461/portal.php?type=vod&action=get_categories" +``` + +#### Get Ordered List +```bash +curl "http://server:25461/portal.php?type=vod&action=get_ordered_list" +# With filters +curl "http://server:25461/portal.php?type=vod&action=get_ordered_list&category=10&sortby=added&search=action" +``` + +**Parameters:** +| Parameter | Type | Description | +|-----------|------|-------------| +| category | integer | Filter by category ID | +| sortby | string | Sort by: added, name, rating, year | +| search | string | Search query | +| abc | string | Filter by first letter | +| genre | string | Filter by genre | +| years | string | Filter by year | +| fav | integer | Show favorites only (1) | + +#### Create Link (VOD) +```bash +curl "http://server:25461/portal.php?type=vod&action=create_link&cmd={base64_encoded_cmd}" +``` + +**Source:** `portal.php:503-626` + +--- + +### Series Actions + +#### Get Categories +```bash +curl "http://server:25461/portal.php?type=series&action=get_categories" +``` + +#### Get Ordered List +```bash +curl "http://server:25461/portal.php?type=series&action=get_ordered_list" +``` + +**Source:** `portal.php:628-699` + +--- + +### Watchdog Actions + +#### Get Events +```bash +curl "http://server:25461/portal.php?type=watchdog&action=get_events" +``` + +**Response:** +```json +{ + "js": { + "data": { + "msgs": 1, + "id": 123, + "event": "send_msg", + "msg": "Welcome message", + "need_confirm": 1, + "auto_hide_timeout": 0 + } + } +} +``` + +#### Confirm Event +```bash +curl "http://server:25461/portal.php?type=watchdog&action=confirm_event&event_active_id=123" +``` + +**Source:** `portal.php:103-131` + +--- + +### STB Settings Actions + +#### Set Volume +```bash +curl "http://server:25461/portal.php?type=stb&action=set_volume&vol=70" +``` + +#### Set Locale +```bash +curl "http://server:25461/portal.php?type=stb&action=set_locale&locale=en_GB.utf8" +``` + +#### Set Parent Password +```bash +curl "http://server:25461/portal.php?type=stb&action=set_parent_password&pass=1234&repeat_pass=1234" +``` + +#### Get Settings Profile +```bash +curl "http://server:25461/portal.php?type=stb&action=get_settings_profile" +``` + +**Source:** `portal.php:140-274` + +--- + +## 6. Enigma2 API (`enigma2.php`) + +**Source:** `wwwdir/enigma2.php` + +XML-based API for Enigma2 satellite receivers. + +### Authentication +``` +GET /enigma2.php?username={username}&password={password}&type={action} +``` + +### Default (Main Menu) +**Request:** +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123" +``` + +**Response (XML):** +```xml + + + Provider Name + + 1 + Provider Name + + + TGl2ZSBTdHJlYW1z + TGl2ZSBTdHJlYW1zIENhdGVnb3J5 + 0 + + + + Vm9k + VmlkZW8gT24gRGVtYW5kIENhdGVnb3J5 + 1 + + + + VFYgU2VyaWVz + VFYgU2VyaWVzIENhdGVnb3J5 + 2 + + + +``` + +**Note:** Titles and descriptions are Base64 encoded. + +**Source:** `enigma2.php:289-319` + +--- + +### Get Live Categories +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_categories" +``` + +### Get Live Streams +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_streams&cat_id=1" +``` + +### Get VOD Categories +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_categories" +``` + +### Get VOD Streams +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_streams&cat_id=10" +``` + +### Get Series Categories +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series_categories" +``` + +### Get Series +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series&cat_id=20" +``` + +### Get Seasons +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_seasons&series_id=789" +``` + +### Get Series Streams (Episodes) +```bash +curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series_streams&series_id=789&season=1" +``` + +**Source:** `enigma2.php:41-288` + +--- + +## 7. Streaming Endpoints + +### Live Streaming + +**URL Patterns:** +``` +/live/{username}/{password}/{stream_id}.{extension} +/{username}/{password}/{stream_id} (new rewrite format) +``` + +**Supported Extensions:** +| Extension | MIME Type | Description | +|-----------|-----------|-------------| +| ts | video/mp2t | MPEG Transport Stream | +| m3u8 | application/x-mpegurl | HLS Playlist | + +**Source:** `streaming/clients_live.php` + +**Request:** +```bash +# Direct TS stream +curl "http://server:25461/live/user1/pass123/123.ts" -o stream.ts + +# HLS playlist +curl "http://server:25461/live/user1/pass123/123.m3u8" +``` + +**HLS Response:** +```m3u +#EXTM3U +#EXT-X-VERSION:3 +#EXT-X-TARGETDURATION:3 +#EXT-X-MEDIA-SEQUENCE:1000 +#EXTINF:3.0, +/live/user1/pass123/123_1000.ts?token=abc123 +#EXTINF:3.0, +/live/user1/pass123/123_1001.ts?token=def456 +``` + +--- + +### VOD/Movie Streaming + +**URL Pattern:** +``` +/movie/{username}/{password}/{stream_id}.{extension} +``` + +**Supported Extensions:** +| Extension | MIME Type | +|-----------|-----------| +| mp4 | video/mp4 | +| mkv | video/x-matroska | +| avi | video/x-msvideo | +| 3gp | video/3gpp | +| flv | video/x-flv | +| wmv | video/x-ms-wmv | +| mov | video/quicktime | +| ts | video/mp2t | + +**Source:** `streaming/clients_movie.php` + +**Request:** +```bash +curl "http://server:25461/movie/user1/pass123/456.mkv" -o movie.mkv +``` + +**Range Requests Supported:** +```bash +curl "http://server:25461/movie/user1/pass123/456.mkv" \ + -H "Range: bytes=0-1048575" -o part1.mkv +``` + +--- + +### Series Streaming + +**URL Pattern:** +``` +/series/{username}/{password}/{stream_id}.{extension} +``` + +Same behavior as VOD streaming. + +--- + +### Timeshift/Catchup Streaming + +**URL Pattern:** +``` +/timeshift/{username}/{password}/{duration}/{start}/{stream_id} +``` + +**Parameters:** +| Parameter | Type | Description | +|-----------|------|-------------| +| username | string | User login | +| password | string | User password | +| duration | integer | Duration in minutes | +| start | string | Start time (format: YYYY-MM-DD:HH-MM or YYYYMMDD-HH) | +| stream_id | integer | Live stream ID | + +**Source:** `streaming/timeshift.php` + +**Examples:** +```bash +# Get last 60 minutes from channel 123 +curl "http://server:25461/timeshift/user1/pass123/60/2025-12-24:10-00/123" + +# HLS format +curl "http://server:25461/timeshift/user1/pass123/60/2025-12-24:10-00/123.m3u8" +``` + +--- + +### HLS Segment Streaming + +**URL Pattern:** +``` +/hls/{username}/{password}/{stream_id}/{segment} +``` + +Used internally by HLS playlists for segment delivery. + +--- + +## 8. EPG/XMLTV API (`xmltv.php`) + +**Source:** `wwwdir/xmltv.php` + +### Get XMLTV EPG Data + +**Request:** +```bash +curl "http://server:25461/xmltv.php?username=user1&password=pass123" +# With date range +curl "http://server:25461/xmltv.php?username=user1&password=pass123&prev_days=1&next_days=3" +``` + +**Parameters:** +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| username | string | - | User login | +| password | string | - | User password | +| prev_days | integer | 1 | Days of past EPG data | +| next_days | integer | 1 | Days of future EPG data | + +**Response (XML):** +```xml + + + + + Channel Name + + + + Program Title + Program description... + + +``` + +--- + +## 9. Playlist Generator (`get.php`) + +**Source:** `wwwdir/get.php` + +### Generate M3U Playlist + +**Request:** +```bash +curl "http://server:25461/get.php?username=user1&password=pass123&type=m3u_plus&output=ts" +``` + +**Parameters:** +| Parameter | Type | Description | +|-----------|------|-------------| +| username | string | User login | +| password | string | User password | +| type | string | Playlist type: m3u_plus, m3u, m3u8 | +| output | string | Stream format: ts, m3u8, rtmp | + +**Response (M3U):** +```m3u +#EXTM3U +#EXTINF:-1 tvg-id="channel.epg" tvg-name="Channel Name" tvg-logo="http://example.com/icon.png" group-title="Sports",Channel Name +http://server:25461/live/user1/pass123/123.ts +#EXTINF:-1 tvg-id="" tvg-name="Movie Title" tvg-logo="http://example.com/poster.jpg" group-title="Action",Movie Title +http://server:25461/movie/user1/pass123/456.mkv +``` + +--- + +## Data Models + +### User Object +```json +{ + "id": 100, + "username": "user1", + "password": "pass123", + "exp_date": 1735689600, + "max_connections": 2, + "is_restreamer": 0, + "is_trial": 0, + "created_at": 1609459200, + "created_by": 1, + "admin_enabled": 1, + "enabled": 1, + "bouquet": [1, 2, 3], + "allowed_ips": [], + "allowed_ua": [], + "forced_country": "ALL", + "pair_id": null, + "isp_desc": null, + "bypass_ua": 0 +} +``` + +### Stream Object (Live) +```json +{ + "id": 123, + "stream_display_name": "Channel Name", + "stream_icon": "http://example.com/icon.png", + "category_id": 1, + "channel_id": "channel.epg", + "epg_id": 67, + "tv_archive": 1, + "tv_archive_duration": 7, + "direct_source": 0, + "stream_source": null +} +``` + +### Stream Object (VOD) +```json +{ + "id": 456, + "stream_display_name": "Movie Title", + "stream_icon": "http://example.com/poster.jpg", + "category_id": 10, + "target_container": "mkv", + "movie_properties": { + "movie_image": "http://example.com/poster.jpg", + "tmdb_id": "12345", + "genre": "Action", + "plot": "Description...", + "cast": "Actor 1, Actor 2", + "rating": "8.5", + "director": "Director Name", + "releasedate": "2025-01-01", + "duration": "02:00:00" + } +} +``` + +### Series Object +```json +{ + "id": 789, + "title": "Series Title", + "category_id": 20, + "plot": "Series description...", + "cast": "Actor 1, Actor 2", + "director": "Director Name", + "genre": "Drama", + "release_date": "2025-01-01", + "rating": "9.0", + "cover": "http://example.com/cover.jpg", + "backdrop_path": "http://example.com/backdrop.jpg", + "youtube_trailer": "abc123" +} +``` + +### MAG Device Object +```json +{ + "mag_id": 50, + "user_id": 100, + "mac": "00:1A:79:XX:XX:XX", + "sn": "ABC123456", + "stb_type": "MAG254", + "ver": "218", + "image_version": "1.0.0", + "token": "A1B2C3D4...", + "locale": "en_GB.utf8", + "parent_password": "0000", + "volume": 70, + "last_watchdog": 1735084800 +} +``` + +### EPG Entry Object +```json +{ + "id": 12345, + "epg_id": 67, + "channel_id": "channel.epg", + "title": "UHJvZ3JhbSBUaXRsZQ==", + "description": "UHJvZ3JhbSBkZXNjcmlwdGlvbi4uLg==", + "start": "2025-12-24 12:00:00", + "end": "2025-12-24 13:00:00", + "start_timestamp": 1735041600, + "stop_timestamp": 1735045200 +} +``` +**Note:** Title and description are Base64 encoded in the database. + +--- + +## Error Codes + +### HTTP Status Codes + +| Code | Meaning | Scenarios | +|------|---------|-----------| +| 200 | Success | Request completed successfully | +| 206 | Partial Content | Range request for VOD | +| 400 | Bad Request | Missing required parameters | +| 401 | Unauthorized | Authentication failed, user expired/banned | +| 403 | Forbidden | Access denied (IP/token mismatch) | +| 404 | Not Found | Resource/file not found | +| 405 | Method Not Allowed | Extension not allowed for user | +| 406 | Not Acceptable | Stream not in user's bouquet | +| 416 | Range Not Satisfiable | Invalid range request | + +### Client Log Codes + +| Code | Description | +|------|-------------| +| AUTH_FAILED | Invalid username/password | +| USER_EXPIRED | User subscription expired | +| USER_BAN | User banned by admin | +| USER_DISABLED | User account disabled | +| USER_ALREADY_CONNECTED | Max connections reached | +| NOT_IN_BOUQUET | Stream not in user's bouquet | +| IP_BAN | IP not in allowed list | +| COUNTRY_DISALLOW | Country not allowed | +| USER_AGENT_BAN | User agent not allowed | +| EMPTY_UA | Empty user agent blocked | +| ISP_LOCK_FAILED | ISP restriction failed | +| CON_SVP | Connection from server/VPN | +| CRACKED | Known cracked IP detected | +| MAG_TOKEN_INVALID | Invalid MAG device token | +| STALKER_KEY_EXPIRED | Stalker key expired | +| STALKER_IP_MISMATCH | IP changed during session | +| USER_DISALLOW_EXT | Extension not allowed | + +--- + +## Integration Guide + +### Quick Start - Player App Integration + +#### 1. Authenticate and get user info +```bash +curl "http://server:25461/player_api.php?username=USER&password=PASS" +``` + +#### 2. Get live categories +```bash +curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_categories" +``` + +#### 3. Get channels by category +```bash +curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_streams&category_id=1" +``` + +#### 4. Play a stream +```bash +# Direct play +ffplay "http://server:25461/live/USER/PASS/123.ts" + +# HLS +ffplay "http://server:25461/live/USER/PASS/123.m3u8" +``` + +### MAG Device Integration + +#### 1. Handshake +```bash +curl "http://server:25461/portal.php?type=stb&action=handshake&mac=00:1A:79:XX:XX:XX" +``` + +#### 2. Store token and add to all subsequent requests +```bash +curl "http://server:25461/portal.php?type=stb&action=get_profile" \ + -H "Authorization: Bearer TOKEN" \ + -H "Cookie: mac=00:1A:79:XX:XX:XX" +``` + +#### 3. Get channels +```bash +curl "http://server:25461/portal.php?type=itv&action=get_all_channels" \ + -H "Authorization: Bearer TOKEN" +``` + +### Code Examples + +#### Python - Get Live Streams +```python +import requests + +server = "http://server:25461" +username = "user1" +password = "pass123" + +# Authenticate +response = requests.get(f"{server}/player_api.php", params={ + "username": username, + "password": password +}) +user_info = response.json() + +if user_info.get("user_info", {}).get("auth") == 1: + # Get live categories + categories = requests.get(f"{server}/player_api.php", params={ + "username": username, + "password": password, + "action": "get_live_categories" + }).json() + + # Get live streams + streams = requests.get(f"{server}/player_api.php", params={ + "username": username, + "password": password, + "action": "get_live_streams" + }).json() + + for stream in streams: + print(f"{stream['name']}: {server}/live/{username}/{password}/{stream['stream_id']}.ts") +``` + +#### JavaScript - Get VOD Info +```javascript +async function getVODInfo(server, username, password, vodId) { + const url = new URL(`${server}/player_api.php`); + url.searchParams.set('username', username); + url.searchParams.set('password', password); + url.searchParams.set('action', 'get_vod_info'); + url.searchParams.set('vod_id', vodId); + + const response = await fetch(url); + return await response.json(); +} + +// Usage +const vodInfo = await getVODInfo('http://server:25461', 'user1', 'pass123', 456); +console.log(vodInfo.info.plot); +console.log(`Play: http://server:25461/movie/user1/pass123/${vodInfo.movie_data.stream_id}.${vodInfo.movie_data.container_extension}`); +``` + +#### cURL - Admin Create User +```bash +curl -X POST "http://server:25461/api.php" \ + -d "action=user" \ + -d "sub=create" \ + -d "username=newuser" \ + -d "password=securepass123" \ + -d "max_connections=2" \ + -d 'bouquet=[1,2,3,4,5]' \ + -d "exp_date=1767225600" \ + -d "reseller_id=1" +``` + +--- + +## Appendix: File Reference + +| File | Location | Purpose | +|------|----------|---------| +| api.php | wwwdir/api.php | Admin/Management API | +| player_api.php | wwwdir/player_api.php | Player/Client API | +| panel_api.php | wwwdir/panel_api.php | Panel API | +| system_api.php | wwwdir/system_api.php | Internal System API | +| portal.php | wwwdir/portal.php | MAG Portal API | +| enigma2.php | wwwdir/enigma2.php | Enigma2 API | +| xmltv.php | wwwdir/xmltv.php | EPG/XMLTV API | +| get.php | wwwdir/get.php | Playlist Generator | +| clients_live.php | wwwdir/streaming/ | Live Stream Handler | +| clients_movie.php | wwwdir/streaming/ | VOD Stream Handler | +| timeshift.php | wwwdir/streaming/ | Timeshift Handler | +| init.php | wwwdir/init.php | Bootstrap/Initialization | +| functions.php | wwwdir/includes/ | Helper Functions | +| lib.php | wwwdir/includes/ | Core Library | +| streaming.php | wwwdir/includes/ | Streaming Functions | +| mysql.php | wwwdir/includes/ | Database Layer | + +--- + +*Documentation generated from source code analysis of Xtream Codes v2.9.2*