Make your service look right in PhiPTV.

Values that must be in a specific shape

Small things that silently break when they are not.

• is_adult — 1, true or "1". The string "true" does not count.
• stream_type — exactly radio_streams for radio; anything else is treated as live TV.
• rating — 0 to 10. Zero or above ten is shown as unrated.
• auth — send 0 as a number for a wrong login; the string "0" shows a generic server error instead.
• last_modified, exp_date — epoch seconds, not milliseconds.
• tv_archive, tv_archive_duration — 1, true or "1"; the duration as a whole number of days.
• episodes — an object keyed by season number, not an array.
• Usernames and passwords — written into stream paths as typed; avoid / ? # % and spaces.
• container_extension — used verbatim in the movie and episode URL; defaults to mp4 when missing.
• backdrop_path — an array (first entry used) or a single string; both work.
• youtube_trailer — a bare YouTube id or a full URL.
• Timeouts — 30 seconds to connect and to wait for data on catalogue calls, 60 seconds while waiting for guide data. A slow live list fails the refresh; a slow movie or series list keeps the previous one.

How refresh works

PhiPTV downloads the whole catalogue; there is no delta API.

• Automatic refresh once a day while PhiPTV is open: it checks five minutes after start and then hourly, and runs once the customer's hour has passed (04:00 by default) and the last refresh is more than 22 hours old.
• If the fields PhiPTV keeps are unchanged (same items, same order, same category order), the database rewrite is skipped, so a stable catalogue is cheap for everyone.
• A live list that comes back empty is rejected rather than wiping the customer's channels — a panel outage does not empty their TV. Empty movie or series lists keep the previous ones. Only after the customer changes the server or login may an empty answer clear them.
• Stream URLs are built as /live/user/pass/id.m3u8, /movie/user/pass/id.ext and /series/user/pass/id.ext. allowed_output_formats is not consulted.

Catch-up (replay)

Xtream only. What makes the replay mark appear, and how the link is built.

• A channel can be replayed when tv_archive is set and tv_archive_duration is a whole number of days above 0. In the guide, a programme that has ended and started within that many days carries a replay mark; OK plays it from the start. The guide reaches 12 hours back.
• In fullscreen live on a TV, LEFT replays the programme on now from its start (the last hour when there is no guide), a minute behind live, with a Go live button.
• The link is built from the channel's live link and the guide's start and stop, trying in order: /timeshift/USER/PASS/MINUTES/YYYY-MM-DD:HH-MM/ID.m3u8, the same ending .ts, then /streaming/timeshift.php?username=…&password=…&stream=ID&start=…&duration=MINUTES. The first that works is remembered for your server.
• The start is in your server's local time, taken from server_info.time_now and timestamp_now; without them it is UTC. Accurate programme times matter.
• Each shape is checked with a short request (MAG250 User-Agent, closed after the first kilobyte) and must answer 2xx with an HLS playlist, MPEG-TS, MP4 or FLV. The replay itself plays with the VLC User-Agent and leaves no Continue Watching entry.

The shape PhiPTV expects

Two lines per entry. That is the whole contract.

• Line 1 of the file starts with #EXTM3U, or nothing is imported.
• Each entry is one #EXTINF line followed by the URL line.
• No #EXTVLCOPT, #KODIPROP or #EXTGRP line in between. An entry with an extra line in the middle is dropped. This is the single most common reason a channel is missing.
• The channel name is the text after the last comma. tvg-name is not read.
• Channel numbers are positions inside each category, starting at 1, so the order of lines within a group-title is the order customers dial; tvg-chno is ignored. Categories appear in the order each group-title first occurs.
• Each entry is identified by its position in the file. Inserting, removing or reordering lines moves customers' favourites and history to other channels, so add new channels at the end.
• Do not put " or ' inside an attribute value; the value stops at the first quote. Do not append |User-Agent=… to URLs.

#EXTM3U
#EXTINF:-1 tvg-id="news1.example" tvg-logo="https://cdn.example.com/logos/news1.png" group-title="News" tvg-country="GB" tvg-language="English",News Channel 1
http://stream.example.com/live/USER/PASS/1001.ts

#EXTINF:-1 tvg-id="sport1.example" tvg-logo="https://cdn.example.com/logos/sport1.png" group-title="Sport",Sport Channel 1 HD
http://stream.example.com/live/USER/PASS/2001.ts

#EXTINF:-1 tvg-logo="https://cdn.example.com/logos/radio1.png" group-title="Radio" radio="true",Radio Station 1
http://stream.example.com/radio/station1.mp3

Attributes that are read

Everything else on the line is ignored.

Guide for M3U customers: the header's url-tvg is not read, so publish the XMLTV URL where customers can copy it. They paste it into the playlist's EPG field in PhiPTV, once.

What is parsed

Only <programme> elements. <channel> blocks, their display names and icons, are ignored — names and logos come from the playlist.

• start, stop and channel are all required.
• The first <title>, <desc>, <category> and <icon> in each programme are used. lang attributes are not inspected, so put the language you want shown first.
• Timestamps are YYYYMMDDHHMMSS ±HHMM with a space before the offset. Without an offset the time is treated as UTC.
• Entities: & < > " '. Numeric references such as é are not decoded — write the character in UTF-8. CDATA sections are not unwrapped.
• On import PhiPTV keeps programmes that end after 24 hours ago and start within the next 48 hours, for the channel ids in the customer's playlist. The guide shows 12 hours back and 24 hours ahead. Gzip bodies and gzip transport are both fine; there is no size cap.
• The guide is refreshed every 12 hours by default (the customer can choose 4, 6, 12 or 24) while Live TV or the guide is open, an hour after a failed attempt, and on demand. It is fetched without a custom User-Agent, and its start and stop times also drive reminders and catch-up links.

<?xml version="1.0" encoding="UTF-8"?>
<tv>
  <programme start="20260901180000 +0100" stop="20260901183000 +0100" channel="news1.example">
    <title lang="en">Evening News</title>
    <desc lang="en">The day's headlines, weather and sport.</desc>
    <category lang="en">News</category>
    <icon src="https://cdn.example.com/stills/evening-news.jpg"/>
  </programme>
</tv>

channel="news1.example" must equal the stream's epg_channel_id or tvg-id exactly.

Categories

Shown in the order you return them, spelled exactly as you return them. Customers can hide, move and pin categories; that is stored by category name.

• Pick one prefix style and keep it: UK | Sport everywhere, never UK| Sport on some rows. Every spelling variant becomes a separate category.
• Put the categories customers open most at the top of the array. Uncategorised or unlisted names fall to the bottom.
• Keep names short enough for a rail label: about 24 characters.
• Give radio its own category and tag the streams. Tagged stations appear in the Radio section and stay in their category in Live TV. Untagged channels whose group contains the word "radio", or whose name reads like a station (Radio, FM, راديو…) with no TV mark, are also listed under Radio.
• Adult categories: flag every stream in them with is_adult; the category name alone hides nothing.

Channels

Listed in the order you return them; the number is the position in the list on screen.

• Put the channels customers want on low numbers at the top of each category; digit entry dials positions within the category on screen.
• Name the channel, then the quality: Sport Channel 1 HD. In M3U names, doubled suffixes like HD HD are collapsed; Xtream names are shown as sent.
• One logo per channel, square or nearly square, around 256 px, PNG or JPG, on a host that does not check the User-Agent or Referer.
• Give every channel an epg_channel_id, even if a few have no guide yet — a blank id leaves an empty guide row with nothing to focus and nothing to replay.

Movies and series

Posters, genres and detail pages come straight from your metadata.

• Portrait posters in stream_icon / cover; a wide backdrop_path for the detail page.
• genre as a comma-separated list; PhiPTV builds its genre chips from it. If it is empty the app falls back to keyword guessing from the title.
• Series: one episodes map keyed by season number, episodes numbered with episode_num, each with its own still in info.movie_image.
• Update last_modified when a new episode is added, and fill each episode's added — they drive the new-episode alert for customers who favourited the series, after their next catalogue refresh.
• Ratings on a 0–10 scale. Durations in seconds (duration_secs) are safest.

Accounts and limits

What PhiPTV shows the customer about their account.

• PhiPTV shows the customer their Xtream username. status, the expiry date and active_cons are not shown, and an expired account is only noticed when streams fail.
• PhiPTV's stream-limit guard uses max_connections by default and warns the customer before another of their own devices pushes them over it.
• Sessions you close from the server side are reopened automatically up to three times; a 429 or 509 is retried with backoff; 401/403/404/410 is treated as a dead link.