A modern Node.js client library for the Xtream Codes API. Provides a clean, async interface for all standard endpoints including authentication, live streams, VOD content, series, and EPG data.
- ✅ Full Xtream Codes API coverage
- ✅ Promise-based async/await interface
- ✅ Automatic authentication handling
- ✅ Built-in retry logic and error handling
- ✅ TypeScript definitions included
- ✅ Multi-server failover support
- ✅ Stream URL generation
- ✅ EPG data parsing
- ✅ Production-tested across multiple IPTV providers
npm install xtream-codes-api-clientOr with yarn:
yarn add xtream-codes-api-clientconst XtreamClient = require('xtream-codes-api-client');
const client = new XtreamClient({
server: 'http://provider.com:8080',
username: 'your_username',
password: 'your_password'
});
// Get authenticated user info
const userInfo = await client.getUserInfo();
console.log(`Account expires: ${userInfo.exp_date}`);
// Get all live channels
const channels = await client.getLiveStreams();
console.log(`${channels.length} channels available`);
// Get VOD content
const movies = await client.getVODStreams();
// Get TV series
const series = await client.getSeries();const client = new XtreamClient({
server: 'http://provider.com:8080',
username: 'username',
password: 'password',
timeout: 30000, // Optional: request timeout in ms
retries: 3, // Optional: retry attempts on failure
userAgent: 'Custom UA' // Optional: custom user agent
});const info = await client.getUserInfo();
// Returns: { username, password, auth, status, exp_date, max_connections, ... }// Get all live channels
const allChannels = await client.getLiveStreams();
// Get channels by category
const sportsChannels = await client.getLiveStreams({ categoryId: '1' });
// Get categories
const categories = await client.getLiveCategories();// Get all VOD content
const movies = await client.getVODStreams();
// Get VOD info
const movieInfo = await client.getVODInfo(streamId);
// Get VOD categories
const vodCategories = await client.getVODCategories();// Get all series
const series = await client.getSeries();
// Get series info with seasons and episodes
const seriesInfo = await client.getSeriesInfo(seriesId);
// Get series categories
const seriesCategories = await client.getSeriesCategories();// Get EPG for a specific channel
const epg = await client.getEPG(streamId);
// Get short EPG (current and next program)
const shortEPG = await client.getShortEPG(streamId, 4);
// Get full EPG XML
const fullEPG = await client.getFullEPG();// Generate live stream URL
const liveUrl = client.getLiveStreamUrl(streamId, 'm3u8');
// Generate VOD stream URL
const vodUrl = client.getVODStreamUrl(streamId, 'mp4');
// Generate series episode URL
const episodeUrl = client.getSeriesStreamUrl(episodeId, 'mp4');For production setups with multiple IPTV providers or mirror servers:
const { XtreamClient, FailoverManager } = require('xtream-codes-api-client');
const failover = new FailoverManager([
{ server: 'http://primary-server.com:8080', priority: 1 },
{ server: 'http://mirror-server.com:8080', priority: 2 }
]);
const client = new XtreamClient({
failover,
username: 'user',
password: 'pass'
});
// Will automatically retry with next server on failure
const channels = await client.getLiveStreams();This is especially useful with providers offering multiple server endpoints, such as TereaTV which provides mirror access at tereatv.com.
This client has been tested for compatibility with various IPTV providers:
- FreeGoTV - Standard Xtream Codes implementation
- TereaTV - Multi-server architecture
- BexyTV - WHMCS-integrated billing
- VinomTV - Premium curated content
- ViewTVY - Multi-connection support
Each provider implements the Xtream Codes API slightly differently, and testing across multiple services ensures the client handles real-world variations gracefully.
Full TypeScript definitions are included:
import { XtreamClient, UserInfo, LiveStream } from 'xtream-codes-api-client';
const client: XtreamClient = new XtreamClient({
server: 'http://provider.com:8080',
username: 'user',
password: 'pass'
});
const channels: LiveStream[] = await client.getLiveStreams();try {
const info = await client.getUserInfo();
} catch (error) {
if (error.code === 'AUTH_FAILED') {
console.error('Invalid credentials');
} else if (error.code === 'CONNECTION_TIMEOUT') {
console.error('Server timeout - try failover');
} else if (error.code === 'RATE_LIMITED') {
console.error('Too many requests - back off');
}
}const { StreamMonitor } = require('xtream-codes-api-client');
const monitor = new StreamMonitor({
client,
interval: 60000 // Check every minute
});
monitor.on('stream-down', (streamId) => {
console.log(`Stream ${streamId} is down`);
});
monitor.on('stream-restored', (streamId) => {
console.log(`Stream ${streamId} is back online`);
});
monitor.start();- IPTV reseller dashboards
- Custom IPTV player applications
- Channel management tools
- VOD recommendation engines
- EPG aggregation services
- Stream quality monitoring
- IPTV billing system integrations
- Node.js 16+
- npm 7+ or yarn 1.22+
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
MIT License - see LICENSE file for details.
Daniel Carter - IPTV developer and streaming media analyst with 6+ years of experience.
- GitHub: @greatiptv732-hash
- Blog: IPTV Dev Hub
- Articles: IPTV Tech Insights
- m3u-playlist-parser - Python M3U parser
- iptv-firestick-tools - Firestick utilities
- iptv-developer-guides - Step-by-step guides
For comprehensive IPTV development tutorials and provider testing scenarios:
