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

> Learn to handle proxies for stream testing in the iptv-org repository using the -x --proxy CLI flag for HTTP, HTTPS, and SOCKS proxies. Optimize your testing workflow today.

- Repository: [iptv-org/iptv](https://github.com/iptv-org/iptv)
- Tags: testing
- Published: 2026-02-25

---

**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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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.

```bash

# 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:

```typescript
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:

```typescript
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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/scripts/core/proxyParser.ts) decomposes URLs into protocol, host, port, and authentication components.
- **`StreamTester`** in [`scripts/core/streamTester.ts`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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.