From 709c1ed70a12fa92b6c05084191ade92fbbc4b2e Mon Sep 17 00:00:00 2001 From: worldofiptvcom Date: Wed, 24 Dec 2025 16:42:51 +0300 Subject: [PATCH] Add files via upload --- xtream-codes-player-api-documentation.md | 945 +++++++++++++++++++++++ 1 file changed, 945 insertions(+) create mode 100644 xtream-codes-player-api-documentation.md diff --git a/xtream-codes-player-api-documentation.md b/xtream-codes-player-api-documentation.md new file mode 100644 index 0000000..3ba4a10 --- /dev/null +++ b/xtream-codes-player-api-documentation.md @@ -0,0 +1,945 @@ +# Xtream Codes API Documentation + +Complete API reference for the Xtream Codes Player API. + +--- + +## Table of Contents + +- [Overview](#overview) +- [Authentication](#authentication) +- [Base URL](#base-url) +- [User Info](#user-info) +- [Live Channels](#live-channels) + - [Get Live Categories](#get-live-categories) + - [Get Live Streams](#get-live-streams) +- [VOD (Movies)](#vod-movies) + - [Get VOD Categories](#get-vod-categories) + - [Get VOD Streams](#get-vod-streams) + - [Get VOD Info](#get-vod-info) +- [Series](#series) +- [EPG (Electronic Program Guide)](#epg-electronic-program-guide) + - [Get Short EPG](#get-short-epg) + - [Get Full EPG](#get-full-epg) +- [Response Codes](#response-codes) +- [Data Models](#data-models) + +--- + +## Overview + +The Xtream Codes Player API provides access to IPTV content including live streams, video on demand (VOD), and electronic program guide (EPG) data. + +### Available Actions + +| Action | Description | Category | +|--------|-------------|----------| +| *(none)* | Get user account & server info | User Info | +| `get_live_categories` | List all live stream categories | Live | +| `get_live_streams` | List all live channels | Live | +| `get_vod_categories` | List all VOD/movie categories | VOD | +| `get_vod_streams` | List all movies | VOD | +| `get_vod_info` | Get detailed movie information | VOD | +| `get_short_epg` | Get short EPG for a channel | EPG | +| `get_simple_data_table` | Get full EPG listing | EPG | + +--- + +## Authentication + +All API requests require authentication via `username` and `password` query parameters. + +``` +?username=YOUR_USERNAME&password=YOUR_PASSWORD +``` + +### Authentication Failure Response + +```json +{ + "user_info": { + "auth": 0 + } +} +``` + +--- + +## Base URL + +``` +http://SERVER_ADDRESS:PORT/player_api.php +``` + +Replace `SERVER_ADDRESS` and `PORT` with your server details. + +--- + +## User Info + +Get account information and server details. + +### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | + +> **Note:** Do not include an `action` parameter to get user info. + +### Example Request + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123" +``` + +### Example Response + +```json +{ + "user_info": { + "username": "john", + "password": "secret123", + "auth": 1, + "message": "", + "status": "Active", + "exp_date": 1735689600, + "is_trial": 0, + "active_cons": 1, + "created_at": 1704067200, + "max_connections": 2, + "allowed_output_formats": ["m3u8", "ts"] + }, + "server_info": { + "url": "example.com", + "port": "8080", + "server_protocol": "http", + "timezone": "UTC", + "timestamp_now": 1703980800, + "time_now": "2024-12-31 12:00:00", + "rtmp_port": "", + "https_port": "" + } +} +``` + +### User Status Values + +| Status | Description | +|--------|-------------| +| `Active` | Account is enabled and not expired | +| `Banned` | Account banned by administrator | +| `Disabled` | Account is disabled | +| `Expired` | Account has passed expiration date | + +### Response Fields + +#### `user_info` Object + +| Field | Type | Description | +|-------|------|-------------| +| `username` | string | Account username | +| `password` | string | Account password | +| `auth` | integer | Authentication status (1 = success, 0 = failed) | +| `message` | string | System message (if any) | +| `status` | string | Account status | +| `exp_date` | integer/null | Expiration timestamp (null = never expires) | +| `is_trial` | integer | Trial account flag (1 = trial, 0 = regular) | +| `active_cons` | integer | Current active connections | +| `created_at` | integer | Account creation timestamp | +| `max_connections` | integer | Maximum allowed simultaneous connections | +| `allowed_output_formats` | array | Allowed streaming formats | + +#### `server_info` Object + +| Field | Type | Description | +|-------|------|-------------| +| `url` | string | Server URL or IP address | +| `port` | string | Server port | +| `server_protocol` | string | Protocol (http/https) | +| `timezone` | string | Server timezone | +| `timestamp_now` | integer | Current server timestamp | +| `time_now` | string | Current server time (Y-m-d H:i:s) | +| `rtmp_port` | string | RTMP port (if available) | +| `https_port` | string | HTTPS port (if available) | + +--- + +## Live Channels + +### Get Live Categories + +Retrieve all available live stream categories. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_live_categories` | + +#### Example Request + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_categories" +``` + +#### Example Response + +```json +[ + { + "category_id": "1", + "category_name": "Sports", + "parent_id": 0 + }, + { + "category_id": "2", + "category_name": "News", + "parent_id": 0 + }, + { + "category_id": "3", + "category_name": "Entertainment", + "parent_id": 0 + } +] +``` + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `category_id` | string | Unique category identifier | +| `category_name` | string | Category display name | +| `parent_id` | integer | Parent category ID (0 = root) | + +--- + +### Get Live Streams + +Retrieve all available live channels, optionally filtered by category. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_live_streams` | +| `category_id` | string | ❌ No | Filter by category ID | + +#### Example Request - All Streams + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams" +``` + +#### Example Request - Filter by Category + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams&category_id=1" +``` + +#### Example Response + +```json +[ + { + "num": 1, + "name": "Sports Channel HD", + "stream_type": "live", + "stream_id": 101, + "stream_icon": "http://example.com/icons/sports.png", + "epg_channel_id": "sports.us", + "added": "1704067200", + "category_id": "1", + "tv_archive": 0, + "direct_source": "", + "tv_archive_duration": 0 + }, + { + "num": 2, + "name": "News 24/7", + "stream_type": "live", + "stream_id": 102, + "stream_icon": "http://example.com/icons/news.png", + "epg_channel_id": "news.us", + "added": "1704067200", + "category_id": "2", + "tv_archive": 0, + "direct_source": "", + "tv_archive_duration": 0 + } +] +``` + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `num` | integer | Stream number in list | +| `name` | string | Channel display name | +| `stream_type` | string | Always `live` for live streams | +| `stream_id` | integer | Unique stream identifier | +| `stream_icon` | string | Channel logo URL | +| `epg_channel_id` | string | EPG channel identifier | +| `added` | string | Timestamp when stream was added | +| `category_id` | string | Category the stream belongs to | +| `tv_archive` | integer | TV archive availability (0/1) | +| `direct_source` | string | Direct source URL (if available) | +| `tv_archive_duration` | integer | Archive duration in days | + +#### Playing a Live Stream + +To play a live stream, use this URL format: + +``` +http://SERVER:PORT/USERNAME/PASSWORD/STREAM_ID.EXT +``` + +**Example:** +``` +http://example.com:8080/john/secret123/101.m3u8 +http://example.com:8080/john/secret123/101.ts +``` + +--- + +## VOD (Movies) + +### Get VOD Categories + +Retrieve all available movie categories. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_vod_categories` | + +#### Example Request + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_categories" +``` + +#### Example Response + +```json +[ + { + "category_id": "10", + "category_name": "Action", + "parent_id": 0 + }, + { + "category_id": "11", + "category_name": "Comedy", + "parent_id": 0 + }, + { + "category_id": "12", + "category_name": "Drama", + "parent_id": 0 + } +] +``` + +--- + +### Get VOD Streams + +Retrieve all available movies, optionally filtered by category. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_vod_streams` | +| `category_id` | string | ❌ No | Filter by category ID | + +#### Example Request - All Movies + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_streams" +``` + +#### Example Request - Filter by Category + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_streams&category_id=10" +``` + +#### Example Response + +```json +[ + { + "num": 1, + "name": "Action Movie 2024", + "stream_type": "movie", + "stream_id": 5001, + "stream_icon": "http://example.com/posters/movie1.jpg", + "added": "1704067200", + "category_id": "10", + "direct_source": "", + "rating": 7.5, + "rating_5based": 4, + "custom_sid": null, + "container_extension": "mkv" + }, + { + "num": 2, + "name": "Comedy Film", + "stream_type": "movie", + "stream_id": 5002, + "stream_icon": "http://example.com/posters/movie2.jpg", + "added": "1704153600", + "category_id": "11", + "direct_source": "", + "rating": 6.8, + "rating_5based": 3, + "custom_sid": null, + "container_extension": "mp4" + } +] +``` + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `num` | integer | Movie number in list | +| `name` | string | Movie title | +| `stream_type` | string | Always `movie` for VOD | +| `stream_id` | integer | Unique movie identifier | +| `stream_icon` | string | Movie poster URL | +| `added` | string | Timestamp when movie was added | +| `category_id` | string | Category the movie belongs to | +| `direct_source` | string | Direct source URL (if available) | +| `rating` | float/null | Rating out of 10 | +| `rating_5based` | integer | Rating out of 5 (rounded up) | +| `custom_sid` | null | Custom stream ID | +| `container_extension` | string | File extension (mp4, mkv, avi, etc.) | + +--- + +### Get VOD Info + +Retrieve detailed information about a specific movie. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_vod_info` | +| `vod_id` | integer | ✅ Yes | Movie/VOD stream ID | + +#### Example Request + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_info&vod_id=5001" +``` + +#### Example Response + +```json +{ + "info": { + "imdb_id": "", + "movie_image": "http://example.com/posters/movie1.jpg", + "genre": "Action, Thriller", + "plot": "An exciting action movie about a hero saving the world.", + "cast": "Actor One, Actor Two, Actor Three", + "director": "Famous Director", + "rating": 7.5, + "releasedate": "2024-01-15", + "duration_secs": 7200, + "duration": "02:00:00", + "bitrate": 4500, + "kinopoisk_url": "", + "episode_run_time": "", + "youtube_trailer": "", + "actors": "Actor One, Actor Two, Actor Three", + "name": "Action Movie 2024", + "name_o": "Action Movie 2024", + "cover_big": "http://example.com/posters/movie1.jpg", + "description": "An exciting action movie about a hero saving the world.", + "age": "", + "rating_mpaa": "", + "rating_count_kinopoisk": 0, + "country": "", + "backdrop_path": [], + "audio": [], + "video": [] + }, + "movie_data": { + "stream_id": 5001, + "name": "Action Movie 2024", + "added": "1704067200", + "category_id": "10", + "container_extension": "mkv", + "custom_sid": "", + "direct_source": "" + } +} +``` + +#### Response Fields + +##### `info` Object + +| Field | Type | Description | +|-------|------|-------------| +| `imdb_id` | string | IMDB identifier | +| `movie_image` | string | Movie poster URL | +| `genre` | string | Movie genres | +| `plot` | string | Movie plot/synopsis | +| `cast` | string | Cast members | +| `director` | string | Director name | +| `rating` | float/null | Rating out of 10 | +| `releasedate` | string | Release date | +| `duration_secs` | integer | Duration in seconds | +| `duration` | string | Duration formatted (HH:MM:SS) | +| `bitrate` | integer | Video bitrate | +| `youtube_trailer` | string | YouTube trailer URL | +| `name` | string | Movie title | +| `description` | string | Movie description | +| `backdrop_path` | array | Backdrop images | +| `audio` | array | Audio track information | +| `video` | array | Video track information | + +##### `movie_data` Object + +| Field | Type | Description | +|-------|------|-------------| +| `stream_id` | integer | Stream identifier | +| `name` | string | Movie title | +| `added` | string | Timestamp when added | +| `category_id` | string | Category ID | +| `container_extension` | string | File extension | +| `custom_sid` | string | Custom stream ID | +| `direct_source` | string | Direct source URL | + +#### Playing a VOD Stream + +To play a movie, use this URL format: + +``` +http://SERVER:PORT/movie/USERNAME/PASSWORD/STREAM_ID.EXTENSION +``` + +**Example:** +``` +http://example.com:8080/movie/john/secret123/5001.mkv +``` + +--- + +## Series + +> ⚠️ **Note:** Series endpoints are not available in this API version. The available actions are limited to: +> - `get_live_categories` +> - `get_vod_categories` +> - `get_live_streams` +> - `get_vod_streams` +> - `get_vod_info` +> - `get_short_epg` +> - `get_simple_data_table` + +Series functionality may be available in other API endpoints or a different version. + +--- + +## EPG (Electronic Program Guide) + +### Get Short EPG + +Retrieve a short EPG listing for a specific channel. + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_short_epg` | +| `stream_id` | integer | ✅ Yes | Live stream ID | +| `limit` | integer | ❌ No | Number of EPG entries (default: 4) | + +#### Example Request - Default Limit + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101" +``` + +#### Example Request - Custom Limit + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101&limit=10" +``` + +#### Example Response + +```json +{ + "epg_listings": [ + { + "id": "12345", + "epg_id": "67890", + "title": "TW9ybmluZyBOZXdz", + "description": "RGFpbHkgbmV3cyBicm9hZGNhc3Q=", + "start": "2024-12-31 08:00:00", + "end": "2024-12-31 09:00:00", + "start_timestamp": 1704009600, + "stop_timestamp": 1704013200 + }, + { + "id": "12346", + "epg_id": "67890", + "title": "U3BvcnRzIFVwZGF0ZQ==", + "description": "TGF0ZXN0IHNwb3J0cyBoaWdobGlnaHRz", + "start": "2024-12-31 09:00:00", + "end": "2024-12-31 10:00:00", + "start_timestamp": 1704013200, + "stop_timestamp": 1704016800 + } + ] +} +``` + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | EPG entry ID | +| `epg_id` | string | EPG channel ID | +| `title` | string | Program title (**Base64 encoded**) | +| `description` | string | Program description (**Base64 encoded**) | +| `start` | string | Start time (Y-m-d H:i:s) | +| `end` | string | End time (Y-m-d H:i:s) | +| `start_timestamp` | integer | Start time as Unix timestamp | +| `stop_timestamp` | integer | End time as Unix timestamp | + +> **Important:** The `title` and `description` fields are **Base64 encoded**. Decode them to get the actual text. + +#### Decoding Example (JavaScript) + +```javascript +const title = atob("TW9ybmluZyBOZXdz"); // "Morning News" +const description = atob("RGFpbHkgbmV3cyBicm9hZGNhc3Q="); // "Daily news broadcast" +``` + +#### Decoding Example (Python) + +```python +import base64 +title = base64.b64decode("TW9ybmluZyBOZXdz").decode('utf-8') # "Morning News" +``` + +#### Decoding Example (PHP) + +```php +$title = base64_decode("TW9ybmluZyBOZXdz"); // "Morning News" +``` + +--- + +### Get Full EPG + +Retrieve a complete EPG listing for a specific channel (up to 1000 entries). + +#### Request + +**Endpoint:** `GET /player_api.php` + +**Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | ✅ Yes | Account username | +| `password` | string | ✅ Yes | Account password | +| `action` | string | ✅ Yes | `get_simple_data_table` | +| `stream_id` | integer | ✅ Yes | Live stream ID | + +#### Example Request + +```bash +curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_simple_data_table&stream_id=101" +``` + +#### Example Response + +```json +{ + "epg_listings": [ + { + "id": "12345", + "epg_id": "67890", + "title": "TW9ybmluZyBOZXdz", + "description": "RGFpbHkgbmV3cyBicm9hZGNhc3Q=", + "start": "2024-12-31 08:00:00", + "end": "2024-12-31 09:00:00", + "start_timestamp": 1704009600, + "stop_timestamp": 1704013200, + "now_playing": 1, + "has_archive": 0 + }, + { + "id": "12346", + "epg_id": "67890", + "title": "U3BvcnRzIFVwZGF0ZQ==", + "description": "TGF0ZXN0IHNwb3J0cyBoaWdobGlnaHRz", + "start": "2024-12-31 09:00:00", + "end": "2024-12-31 10:00:00", + "start_timestamp": 1704013200, + "stop_timestamp": 1704016800, + "now_playing": 0, + "has_archive": 0 + } + ] +} +``` + +#### Additional Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `now_playing` | integer | Currently playing indicator (1 = yes, 0 = no) | +| `has_archive` | integer | Archive availability (1 = yes, 0 = no) | + +> **Note:** The first entry in the response has `now_playing: 1` to indicate it's the current program. + +--- + +## Response Codes + +### HTTP Status Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request | +| 401 | Unauthorized (invalid credentials) | +| 500 | Server Error | + +### Authentication Response + +| `auth` Value | Description | +|--------------|-------------| +| `1` | Authentication successful | +| `0` | Authentication failed | + +--- + +## Data Models + +### User Object + +```json +{ + "username": "string", + "password": "string", + "auth": "integer", + "message": "string", + "status": "string (Active|Banned|Disabled|Expired)", + "exp_date": "integer|null", + "is_trial": "integer", + "active_cons": "integer", + "created_at": "integer", + "max_connections": "integer", + "allowed_output_formats": ["string"] +} +``` + +### Category Object + +```json +{ + "category_id": "string", + "category_name": "string", + "parent_id": "integer" +} +``` + +### Live Stream Object + +```json +{ + "num": "integer", + "name": "string", + "stream_type": "live", + "stream_id": "integer", + "stream_icon": "string", + "epg_channel_id": "string", + "added": "string", + "category_id": "string", + "tv_archive": "integer", + "direct_source": "string", + "tv_archive_duration": "integer" +} +``` + +### VOD Stream Object + +```json +{ + "num": "integer", + "name": "string", + "stream_type": "movie", + "stream_id": "integer", + "stream_icon": "string", + "added": "string", + "category_id": "string", + "direct_source": "string", + "rating": "float|null", + "rating_5based": "integer", + "custom_sid": "null", + "container_extension": "string" +} +``` + +### EPG Entry Object + +```json +{ + "id": "string", + "epg_id": "string", + "title": "string (Base64)", + "description": "string (Base64)", + "start": "string (Y-m-d H:i:s)", + "end": "string (Y-m-d H:i:s)", + "start_timestamp": "integer", + "stop_timestamp": "integer", + "now_playing": "integer (only in get_simple_data_table)", + "has_archive": "integer (only in get_simple_data_table)" +} +``` + +--- + +## Stream URL Formats + +### Live Stream URL + +``` +http://SERVER:PORT/USERNAME/PASSWORD/STREAM_ID.EXTENSION +``` + +**Extensions:** `m3u8`, `ts` + +**Example:** +``` +http://example.com:8080/john/secret123/101.m3u8 +``` + +### VOD/Movie URL + +``` +http://SERVER:PORT/movie/USERNAME/PASSWORD/STREAM_ID.EXTENSION +``` + +**Extensions:** `mp4`, `mkv`, `avi` (as specified in `container_extension`) + +**Example:** +``` +http://example.com:8080/movie/john/secret123/5001.mkv +``` + +### Series Episode URL + +``` +http://SERVER:PORT/series/USERNAME/PASSWORD/STREAM_ID.EXTENSION +``` + +--- + +## Quick Reference + +### Complete API Endpoints Summary + +| Endpoint | Method | Action | Required Params | Optional Params | +|----------|--------|--------|-----------------|-----------------| +| `/player_api.php` | GET | User Info | `username`, `password` | - | +| `/player_api.php` | GET | `get_live_categories` | `username`, `password` | - | +| `/player_api.php` | GET | `get_live_streams` | `username`, `password` | `category_id` | +| `/player_api.php` | GET | `get_vod_categories` | `username`, `password` | - | +| `/player_api.php` | GET | `get_vod_streams` | `username`, `password` | `category_id` | +| `/player_api.php` | GET | `get_vod_info` | `username`, `password`, `vod_id` | - | +| `/player_api.php` | GET | `get_short_epg` | `username`, `password`, `stream_id` | `limit` | +| `/player_api.php` | GET | `get_simple_data_table` | `username`, `password`, `stream_id` | - | + +--- + +## Example Workflow + +### 1. Authenticate and Get User Info + +```bash +curl "http://example.com:8080/player_api.php?username=john&password=secret123" +``` + +### 2. Get Live Categories + +```bash +curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_categories" +``` + +### 3. Get Streams in a Category + +```bash +curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams&category_id=1" +``` + +### 4. Get EPG for a Stream + +```bash +curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101" +``` + +### 5. Play the Stream + +``` +http://example.com:8080/john/secret123/101.m3u8 +``` + +--- + +*Documentation generated based on Xtream Codes Player API source code.*