How to Handle Proxies for Stream Testing in the IPTV-ORG Repository

The IPTV-ORG repository provides built-in proxy support for stream testing through the -x, --proxy CLI flag, which automatically routes requests via HTTP, HTTPS, or SOCKS proxies using the ProxyParser class and StreamTester with dynamic Axios configuration.

When testing IPTV streams in the iptv-org/iptv repository, network restrictions or geographic limitations often require routing requests through proxy servers. The codebase provides a robust mechanism to handle proxies for stream testing without modifying core logic, leveraging command-line flags and modular TypeScript classes that support multiple proxy protocols.

Understanding the Proxy Architecture

The proxy handling system consists of three integrated components that work sequentially to route stream testing requests:

1. CLI Flag Interface – The -x, --proxy <url> option in scripts/commands/playlist/test.ts (lines 42-44) captures user input and stores it in the options object.
2. Proxy Parsing – The ProxyParser class in scripts/core/proxyParser.ts (lines 13-30) decomposes URLs into protocol, host, port, and optional authentication components.
3. HTTP Client Configuration – The StreamTester class in scripts/core/streamTester.ts (lines 31-50) constructs an Axios instance with either native proxy settings or SocksProxyAgent based on the detected protocol.

How Proxy Handling Works Under the Hood

When you specify a proxy for stream testing, the system executes a four-step pipeline:

Step 1: CLI Argument Capture

The command-line parser stores the proxy URL in options.proxy when you invoke the test command with -x or --proxy.

Step 2: URL Parsing

The ProxyParser.parse() method extracts components from strings like http://user:pass@proxy.example.com:3128 or socks5://127.0.0.1:1080, returning an object with protocol, host, port, and optional auth fields.

Step 3: Protocol Detection

The system checks if the protocol is one of the SOCKS variants (socks, socks5, socks5h, socks4, socks4a). This determination happens in scripts/core/streamTester.ts around lines 38-49.

Step 4: Axios Client Construction

Based on the protocol:

• SOCKS proxies: Instantiates SocksProxyAgent from the socks-proxy-agent package and assigns it to both httpAgent and httpsAgent in the Axios config.
• HTTP/HTTPS proxies: Uses Axios's native proxy configuration object with the parsed host, port, and authentication details.

The resulting Axios instance in scripts/core/streamTester.ts (line 52) handles all subsequent stream testing requests through the chosen proxy.

Methods to Handle Proxies for Stream Testing

Using the CLI Flag

The simplest way to handle proxies for stream testing is through the command-line interface. The -x or --proxy flag accepts any valid proxy URL.

# HTTP proxy with basic authentication

npx iptv playlist test -x http://user:pass@proxy.example.com:3128

# HTTPS proxy

npx iptv playlist test -x https://proxy.example.com:8080

# SOCKS5 proxy (no authentication)

npx iptv playlist test -x socks5://127.0.0.1:1080

# SOCKS5h (proxy resolves DNS)

npx iptv playlist test -x socks5h://proxy.example.com:1080

You can combine the proxy flag with other test options like --timeout, --parallel, or --fix without conflict.

Programmatic Usage with StreamTester

For custom scripts or integrations, instantiate StreamTester directly with proxy options:

import { StreamTester } from './scripts/core/streamTester';
import { OptionValues } from 'commander';

const options: OptionValues = {
  proxy: 'socks5://127.0.0.1:1080',   // or an http(s) proxy URL
  timeout: 30000,
  userAgent: 'Mozilla/5.0 (Custom Bot)',
  // …other StreamTester options
};

const tester = new StreamTester({ options });

// Test a single stream
const result = await tester.test({
  url: 'https://example.com/stream.m3u8',
  // Optional: override per-request settings
});

The StreamTester constructor automatically invokes ProxyParser and configures the internal Axios client based on the supplied proxy string.

Custom Proxy Configuration

If you need to modify proxy behavior at runtime or build a custom HTTP client:

import { ProxyParser } from './scripts/core/proxyParser';
import { SocksProxyAgent } from 'socks-proxy-agent';
import axios, { AxiosInstance } from 'axios';

// Parse the proxy URL
const parser = new ProxyParser();
const proxyCfg = parser.parse('http://proxy.mycorp.com:8080');

// Build Axios instance based on protocol
let axiosInstance: AxiosInstance;

if (proxyCfg.protocol?.startsWith('socks')) {
  const agent = new SocksProxyAgent('http://proxy.mycorp.com:8080');
  axiosInstance = axios.create({
    httpAgent: agent,
    httpsAgent: agent,
    timeout: 30000,
  });
} else {
  axiosInstance = axios.create({
    proxy: proxyCfg,
    timeout: 30000,
  });
}

// Use the configured client for requests
const response = await axiosInstance.get('https://example.com/stream.m3u8');

This approach gives you direct control over agent instantiation while leveraging the repository's ProxyParser for URL validation and component extraction.

Key Implementation Files

Understanding these source files helps when debugging proxy issues or extending functionality:

• scripts/commands/playlist/test.ts – Defines the -x, --proxy CLI option (lines 42-44) and passes user input to the testing pipeline.
• scripts/core/proxyParser.ts – Contains the ProxyParser class that normalizes proxy URLs into structured objects with protocol, host, port, and authentication fields (lines 13-30).
• scripts/core/streamTester.ts – Implements the StreamTester class that configures Axios with either native proxy settings or SocksProxyAgent based on the parsed protocol (lines 31-50, 52).
• package.json – Lists required dependencies including axios, socks-proxy-agent, and proxy-from-env that enable proxy functionality.

Summary

• The IPTV-ORG repository handles proxies for stream testing through the -x, --proxy CLI flag and the StreamTester class.
• ProxyParser in scripts/core/proxyParser.ts decomposes URLs into protocol, host, port, and authentication components.
• StreamTester in scripts/core/streamTester.ts automatically selects between Axios native proxy configuration and SocksProxyAgent based on the detected protocol.
• Supported protocols include HTTP, HTTPS, SOCKS4, SOCKS4A, SOCKS5, and SOCKS5H.
• You can invoke proxy handling via CLI commands, programmatic StreamTester instantiation, or custom Axios configurations using the repository's parser utilities.

Frequently Asked Questions

What proxy protocols does the IPTV-ORG stream tester support?

The stream tester supports HTTP, HTTPS, SOCKS4, SOCKS4A, SOCKS5, and SOCKS5H protocols. SOCKS5H specifically instructs the proxy server to resolve DNS names rather than the client. The system detects the protocol from the URL scheme in scripts/core/streamTester.ts and configures either Axios's native proxy settings or a SocksProxyAgent accordingly.

How do I authenticate with a proxy when testing streams?

Include credentials directly in the proxy URL using the standard format protocol://username:password@host:port. The ProxyParser class in scripts/core/proxyParser.ts extracts these credentials and passes them to Axios's proxy configuration or embeds them in the SocksProxyAgent connection string. Both HTTP basic authentication and SOCKS authentication are supported through this URL-based credential passing.

Can I use proxies with other playlist commands besides test?

The -x, --proxy flag is specifically implemented in the playlist test command located at scripts/commands/playlist/test.ts. Other commands like playlist generate or playlist validate do not expose this flag by default. However, you can reuse the StreamTester and ProxyParser classes in custom scripts to add proxy support to any operation that performs HTTP requests.

Why does the stream tester use SocksProxyAgent for SOCKS protocols?

Axios does not natively support SOCKS proxies through its standard proxy configuration object, which only handles HTTP and HTTPS proxies. The StreamTester class detects SOCKS protocols in scripts/core/streamTester.ts (lines 38-49) and instantiates SocksProxyAgent from the socks-proxy-agent package, assigning it to both httpAgent and httpsAgent in the Axios config. This enables full SOCKS4 and SOCKS5 support including DNS resolution through the proxy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}