@iptv/xtream-api NPM

@iptv/xtream-api

A TypeScript library for interacting with an Xtream compatible player API.

✨ Features

ESM and CommonJS support
Supports Node, deno, bun and the browser
Standardized API responses
Customizable serializers

📥 Installation

To install this library, use the following command:

# pnpm
pnpm add @iptv/xtream-api

# npm
npm install @iptv/xtream-api

# yarn
yarn add @iptv/xtream-api

🔧 Usage

import { Xtream } from '@iptv/xtream-api';

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  preferredFormat: 'm3u8', // optional preferred format for channel URLs
});

const categories = await xtream.getChannelCategories();
console.log(categories);
/* outputs
[
  {
    category_id: 1,
    category_name: 'Category 1',
    parent_id: 0,
  },
  {
    category_id: 2,
    category_name: 'Category 2',
    parent_id: 0,
  },
]
*/

📚 API

getProfile();

getServerInfo();

getChannelCategories();

getMovieCategories();

getShowCategories();

type Options = { categoryId?: string | number;
page?: number; limit?: number; // defaults to 10 };

</td>
<td valign="top"><a href="tests/snapshots/standardized/channels.json">View Standardized</a> <br> <a href="tests/snapshots/jsonapi/channels.json">View JSON:API</a></td>
</tr>

<tr>
<td valign="top">

```ts
getMovies(options?: Options);

type Options = {
  categoryId?: string | number;
  page?: number;
  limit?: number; // defaults to 10
};

getMovie(options: Options);

type Options = {
  movieId: string | number;
};

getShows(options?: Options);

type Options = {
  categoryId?: string | number;
  page?: number;
  limit?: number; // defaults to 10
};

getShow(options: Options);

type Options = {
  showId: string | number;
};

getShortEPG(options: Options);

type Options = {
  channelId: string | number;
  limit?: number;
};

getFullEPG(options: Options);

type Options = {
  channelId: string | number;
};

generateStreamUrl(options: Options);

type Options = {
  type: 'channel' | 'movie' | 'episode';
  streamId: string | number;
  extension: string;
  timeshift: {
    duration: number;
    start: Date;
  }
};

🔄 Serializers

Xtream has an unpredictable API format, there are duplicate keys, keys change depending on what type of content is requested, dates come as date strings and timestamp strings with no reason, things that should be arrays are sometimes objects with numbered keys, some data is base64 encoded etc.

For this reason, this library can use serializers to convert the API response to a more usable format. We provide a default set of serializers for the most common API responses.

Camel Case

The simplest serializer just converts the keys of the response object to camel case.

View Definition

import { Xtream } from '@iptv/xtream-api';
import { camelCaseSerializer } from '@iptv/xtream-api/camelcase';

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  serializer: camelCaseSerializer,
});

const categories = await xtream.getChannelCategories();
console.log(categories);
/* outputs
[
  {
    categoryId: 1,
    categoryName: 'Category 1',
    parentId: 0,
  },
  {
    categoryId: 2,
    categoryName: 'Category 2',
    parentId: 1
  },
]
*/

Standardized

Converts the shape of the response object to a standardized format similar to Active Record, also decodes base64 strings.

View Definition

import { Xtream } from '@iptv/xtream-api';
import { standardizedSerializer } from '@iptv/xtream-api/standardized';

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  serializer: standardizedSerializer,
});

const categories = await xtream.getChannelCategories();
console.log(categories);
/* outputs
[
  {
    id: '1',
    name: 'Category 1',
    parentId: '0',
  },
  {
    id: '2',
    name: 'Category 2',
    parentId: '1',
  },
]
*/

JSON:API Serializer

Converts the response object to JSON:API format, also decodes base64 strings.

View Definition

import { Xtream } from '@iptv/xtream-api';
import { JSONAPISerializer } from '@iptv/xtream-api/jsonapi';

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  serializer: JSONAPISerializer,
});

const categories = await xtream.getChannelCategories();
console.log(categories);
/* outputs
{
  data: [
    {
      type: 'channel-category',
      id: '1',
      attributes: {
        name: 'Category 1',
      },
    },
    {
      type: 'channel-category',
      id: '2',
      attributes: {
        name: 'Category 2',
      },
      relationships: {
        parent: {
          data: {
            type: 'channel-category',
            id: '1',
          },
        },
      },
    },
  ],
}
*/

Custom Serializers

You can create your own serializer by passing an object of serializer methods to the Xtream class.

You can define serializers for each of these methods, all are optional.

type Serializers = {
  profile: (input: XtreamUserProfile) => any;
  serverInfo: (input: XtreamServerInfo) => any;
  channelCategories: (input: XtreamCategory[]) => any;
  movieCategories: (input: XtreamCategory[]) => any;
  showCategories: (input: XtreamCategory[]) => any;
  channels: (input: XtreamChannel[]) => any;
  movies: (input: XtreamMoviesListing[]) => any;
  movie: (input: XtreamMovie) => any;
  shows: (input: XtreamShowListing[]) => any;
  show: (input: XtreamShow) => any;
  shortEPG: (input: XtreamShortEPG) => any;
  fullEPG: (input: XtreamFullEPG) => any;
};

import { Xtream } from '@iptv/xtream-api';

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  serializer: {
    type: 'MyCustomSerializer',
    serializers: {
      channelCategories: (input) => {
        return input.map((category) => ({
          id: category.category_id,
          name: category.category_name,
        }));
      },
    },
  },
});

const categories = await xtream.getChannelCategories();
console.log(categories);
/* outputs
[
  {
    id: 1,
    name: 'Category 1'
  },
  {
    id: 2,
    name: 'Category 2'
  }
]

If you want to create your serializer as a separate file or outside of the class instantiation, a helper function is provided to ensure the correct type information is preserved.

import { defineSerializers } from '@iptv/xtream-api';

export const serializers = defineSerializers('MyCustomSerializer', {
  channelCategories: (input) => {
    return input.map((category) => ({
      id: category.category_id,
      name: category.category_name,
    }));
  },
});

In this example input will have the type of XtreamCategory[] which is the type of the response from the getChannelCategories method.

After supplying the serializers to the Xtream class, the types of the responses will be updated to reflect the changes made by the serializers.

import { Xtream, defineSerializers } from '@iptv/xtream-api';

const mySerializer = defineSerializers('MyCustomSerializer', {
  channelCategories: (input) => {
    return input.map((category) => ({
      id: Number(category.category_id),
      name: category.category_name,
    }));
  },
});

const xtream = new Xtream({
  url: 'http://example.com:8080',
  username: 'username',
  password: 'password',
  serializer: mySerializer,
});

const categories = await xtream.getChannelCategories();
//    ^---------
//    const categories = { id: number, name: string }[]