GO — Healthy across the board

• Last commit today
• 18 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• Unlicense licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

iptv-org/iptv is a curated collection of publicly available IPTV stream URLs organized into M3U playlists, with tooling to validate, format, generate, and test channel links. It solves the problem of discovering and maintaining a reliable, deduplicated directory of live TV streams worldwide by automating playlist generation from a centralized database (iptv-org/database) and running CI/CD checks via GitHub Actions. Monorepo structure: scripts/commands/ contains isolated CLI command handlers (playlist/, api/, readme/, report/); scripts/core/ provides shared utilities (playlistParser.ts, streamTester.ts, dataSet.ts, markdown.ts, htmlTable.ts); .github/workflows/ orchestrates CI jobs; tests/ contain Jest test suites paralleling scripts/ structure. Data flows from iptv-org/database → api:load → playlist:generate → playlist:validate → export to index.m3u.

IPTV player app developers and end users who need pre-packaged M3U playlists to import into VLC, Kodi, or other compatible media players; maintainers of the iptv-org ecosystem who contribute stream links and manage data quality across 100+ countries.

Actively maintained production project with 20K+ GitHub stars, continuous CI/CD via .github/workflows (check.yml, format.yml, update.yml), comprehensive test suite using Jest with TypeScript/SWC transpilation, and automated daily updates. Multiple GitHub issue templates and discussion templates indicate mature contribution process. Clear verdict: production-ready with active community.

Moderate risks: dependency on external iptv-org/database and iptv-org/api repos means breaking changes upstream can cascade; single-maintainer (Arhey) visible in package.json author field creates continuity risk. The postinstall script (npm run api:load) auto-runs during install which could introduce silent failures. Large M3U playlist files require careful memory management during processing.

Automated daily updates via update.yml workflow regenerating playlists; ongoing stream validation and deduplication; active issue triage via templates (streams_add.yml, streams_edit.yml, streams_report.yml, bug-report.yml). README generation automation visible in readme/update.ts suggests documentation is programmatically maintained.

git clone https://github.com/iptv-org/iptv.git && cd iptv && npm install && npm test

Daily commands: npm run playlist:validate (validate M3U files), npm run playlist:generate (rebuild from database), npm run playlist:test (run test suite), npm test (Jest tests), npm run lint (ESLint check). For automation: .github/workflows/update.yml runs nightly.

• package.json — Defines all npm scripts for playlist generation, validation, API loading, and GitHub Actions workflows that automate the entire pipeline.
• scripts/commands/playlist/generate.ts — Core entry point that orchestrates playlist generation from raw stream data into indexed M3U files by country, category, language, and region.
• scripts/core/playlistParser.ts — Parses and validates M3U playlist format, handling stream metadata extraction and playlist structure compliance.
• scripts/models/stream.ts — Defines the Stream data model representing an IPTV channel with all metadata (URL, name, logo, group, language, etc.).
• scripts/generators/indexGenerator.ts — Master generator that creates all indexed playlist variants (by country, category, language, region) from the unified stream dataset.
• .github/workflows/check.yml — CI workflow that validates playlist syntax, runs linting, and tests stream connectivity on every pull request.
• PLAYLISTS.md — Complete catalog of all available playlist URLs and their filtering criteria for end users and integrators.

• Playlist Generator (indexGenerator.ts) (TypeScript, FileSystem I/O) — Orchestrates loading raw streams and producing all indexed playlist variants by delegating to category/country/language/region generators.
  • Failure mode: Corrupted or missing output M3U files; missing index variants; incomplete distribution.
• M3U Parser (playlistParser.ts) (TypeScript, Regex) — Parses M3U8 format and extracts EXTINF metadata into strongly-typed Stream objects.
  • Failure mode: Malformed metadata causes stream objects to have missing fields (null names, logos, or URLs); downstream failures in indexing.
• Stream Tester (streamTester.ts) (HTTP client, axios or fetch) — Tests HTTP/M3U8 stream URLs for connectivity and measures availability/response time.
  • Failure mode: False negatives (marks live streams dead due to temporary outages); network timeouts; resource exhaustion testing 10K+ streams.
• Data Set (dataSet.ts) (TypeScript arrays/maps) — In-memory repository of all Stream objects; filters and indexes streams by country, category, language for playlist generation.
  • Failure mode: Out-of-memory errors for large stream counts; inefficient filtering causing slow playlist generation.
• GitHub Actions CI/CD Workflows (GitHub Actions YAML, bash) — Validates every pull request and automatically regenerates playlists on schedule; enforces linting and test requirements.
  • Failure mode: Failed workflows block merges; automated regeneration misses updates; no rollback if generation fails.
• Markdown & Documentation Generator (TypeScript, Markdown) — Generates human-readable README, playlist catalog (PLAYLISTS.md), and status tables from stream metadata.
  • Failure mode: Out-of-date documentation; incorrect catalog links; broken tables in generated files.

• Contributor (GitHub PR) → streams/*.m3u files — Contributor adds or edits M3U entries (stream URLs and EXTINF metadata) in country-specific playlist files.
• streams/*.m3u files → M3U Parser (playlistParser.ts) — CI/CD workflow automatically triggers parser to load all raw M3U files into Stream objects.
• M3U Parser → In-Memory Dataset (dataSet.ts) — Parsed Stream objects are indexed into dataset for filtering and lookup by country, category, language.
• In-Memory Dataset → Playlist Generators (countriesGenerator, categoriesGenerator, etc.) — Each generator filters dataset by its dimension (country/category/language/region) and produces indexed M3U output.
• Playlist Generators → Generated M3U Files (index.m3u, index.country.m3u, index.category.m3u, etc.) — Indexed playlists are written to disk and committed to Git; served via GitHub Pages CDN to end users.
• Generated M3U Files → IPTV Players (VLC, Kodi, etc.) — End users paste playlist URL into player; player fetches M3U and streams video from underlying HTTP/M3U8 sources.

Add a New IPTV Stream Channel

1. Create or edit the country M3U file (e.g., streams/gb.m3u) by adding an EXTINF metadata line followed by the stream URL (streams/[country_code].m3u)
2. Ensure Stream model properties are populated: #EXTINF:-1 group-title="Category" tvg-id="" tvg-name="" tvg-logo="" followed by the M3U8/HTTP URL (scripts/models/stream.ts)
3. Run validation to ensure the stream URL is reachable and metadata is compliant (scripts/commands/playlist/validate.ts)
4. Commit and push; CI/CD automatically runs tests and regenerates indexed playlists on merge (.github/workflows/check.yml)

Generate a New Playlist Index Variant

1. Create a new generator file in scripts/generators/ (e.g., citiesGenerator.ts) implementing the Generator interface (scripts/generators/generator.ts)
2. Implement the generate() method to filter streams by your new criteria and organize them into groupings (scripts/generators/index.ts)
3. Register the new generator in indexGenerator.ts to coordinate it with other index generators (scripts/generators/indexGenerator.ts)
4. Run npm run playlist:generate to produce the new indexed M3U files (scripts/commands/playlist/generate.ts)

Validate and Test Stream Quality

1. Use playlistParser.ts to load and parse M3U files into Stream objects (scripts/core/playlistParser.ts)
2. Invoke streamTester.ts to check each stream URL for connectivity and measure availability (scripts/core/streamTester.ts)
3. Run npm run playlist:test to execute the full test suite against all streams (scripts/commands/playlist/test.ts)
4. Check the GitHub Actions workflow output to see failed streams and quality reports (.github/workflows/check.yml)

• TypeScript (tsx) — Provides type safety for stream metadata models and reduces runtime errors in data transformation pipelines.
• GitHub Actions + npm scripts — Enables automated validation, testing, and regeneration on every commit without requiring external CI infrastructure.
• M3U Linter (m3u-linter) — Ensures all playlist files conform to M3U8 format specification for compatibility with diverse media players.
• Markdown + Static HTML Tables — Generates human-readable documentation and catalogs without requiring a database or server.

• Store playlists as static M3U files in Git repository rather than a database

  • Why: Allows direct HTTP access via CDN (GitHub Pages) and enables simple version control for stream changes.
  • Consequence: Regeneration must rewrite entire files; large playlist indexes become large files (~100KB+); no real-time stream updates.

• Synchronous stream testing during validation rather than async health checks

  • Why: Provides immediate feedback on stream availability before merging; simple implementation.
  • Consequence: Validation becomes time-consuming for large playlists; dead streams may be included between test runs.

• Index playlists by country, category, language, and region separately rather than combining dimensions

  • Why: Reduces file sizes and allows users to subscribe to specific index (e.g., all Spanish channels) without filtering.
  • Consequence: Channel duplication across multiple playlists; more files to maintain and distribute.

• Centralized stream source as single source of truth (streams/ directory)

  • Why: Ensures consistency and prevents divergence between different playlist variants.
  • Consequence: Single point of failure; corrupted or deleted stream breaks all dependent indexes.

• Not a real-time EPG or program guide (only provides channel URLs and metadata)
• Not a streaming service or media server (only aggregates links to publicly available streams)
• Not a player application (designed to integrate with existing IPTV players like VLC)
• Does not handle authentication, DRM, or geo-blocking (assumes all streams are publicly accessible)
• Does not host media content or transcode streams (purely a playlist metadata aggregator)

• Sequential Stream Testing Without Concurrency (High) — scripts/core/streamTester.ts: Streams are tested one-at-a-time rather than in parallel, causing total test time to scale linearly with stream count (potentially hours for 10K+ streams).
• No Caching of Stream Connectivity Results (Medium) — scripts/commands/playlist/validate.ts: Every validation run re-tests all stream URLs from scratch, wasting time and hitting upstream servers repeatedly despite no code changes.
• File I/O in Hot Generator Loop (Low) — scripts/generators/indexGenerator.ts: Each indexed playlist is written individually to disk within generator loop rather than batching writes, causing I/O overhead.
• No Rollback on Partial Generation Failure — scripts/commands/playlist/generate.ts: If generation fails midway through multiple indexes, partial incomplete playlists remain in output

postinstall hook (npm run api:load) runs automatically on install and requires network access to iptv-org/api—can silently fail without clear error if API is down. M3U playlist file sizes can reach hundreds of MB; memory constraints matter for validation/generation tasks. streamTester.ts performs live HTTP HEAD requests during testing; timeouts or rate limits can cause false negatives. GitHub Actions workflows require GITHUB_TOKEN and may need specific permissions for comment/PR creation. tsx TypeScript runner must be available for scripts/ commands to work.

• M3U Playlist Format — Core data format for this entire project; understanding M3U extensions (#EXTINF, #EXT-X-STREAM-INF), metadata encoding, and Unicode handling is essential for reading playlistParser.ts and validation logic
• IPTV Stream URL Testing & Liveness Checks — streamTester.ts performs HTTP HEAD requests to validate channel URLs are working; understanding timeout handling, redirect following, and false-positive prevention is critical for maintaining playlist quality
• GitHub Actions Workflow Orchestration — Three main workflows (check.yml, format.yml, update.yml) automate the entire pipeline; understanding job dependencies, artifact passing, and scheduled triggers is necessary for debugging CI failures
• Data Deduplication & Merging — scripts/core/dataSet.ts likely implements deduplication logic to merge overlapping streams from multiple sources; understanding hash-based dedup and conflict resolution affects playlist accuracy and size
• Proxy & URL Normalization — proxyParser.ts handles stream URL rewriting and proxy pass-through; affects how final playlist URLs function and whether certain regions/ISPs can access streams
• Electronic Program Guide (EPG) Integration — Playlists reference tvg-id and tvg-logo metadata that links to iptv-org/epg data; understanding EPG schema (XMLTV format) helps with channel mapping and metadata enrichment
• TypeScript + TSX Runtime Execution — All scripts/ commands use tsx for direct TypeScript execution without separate compilation step; understanding ts-node alternatives and import resolution matters for debugging and extending CLI tools

• iptv-org/database — Upstream data source containing all channel metadata, categories, and language info; required dependency for playlist generation
• iptv-org/api — REST API wrapper around the database; provides normalized access to channel data during api:load phase
• iptv-org/epg — Companion project providing Electronic Program Guide data for channels; often used together with IPTV playlists in media players
• iptv-org/awesome-iptv — Curated resource list of IPTV-related tools, apps, and libraries; referenced in README as ecosystem guide
• m3u-org/m3u-linter — External linter tool integrated via m3u-linter.json config; validates M3U syntax and structure during CI checks

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for scripts/core/playlistParser.ts

The playlistParser.ts is a critical module that parses M3U playlists, but there are no visible test files for it in the tests/ directory. Given the repo's focus on IPTV playlists and the complexity of parsing various M3U formats, this module needs dedicated test coverage. The existing Jest configuration is set up but underutilized.

• [ ] Create tests/scripts/core/playlistParser.test.ts with test cases for: valid M3U parsing, malformed entries, handling extinf tags, tvg-id/tvg-name attributes, group-title parsing, and edge cases
• [ ] Add test fixtures in tests/fixtures/ for sample M3U files (valid, invalid, international characters, special cases)
• [ ] Run 'npm test' to verify coverage and ensure playlist parsing reliability before contributors submit stream data

Add GitHub Action workflow for validating playlist integrity on pull requests

While check.yml, format.yml, and update.yml workflows exist, there's no dedicated CI job that validates M3U file structure and stream accessibility before merging. The repo has m3u-linter configured but it's only run locally. This would catch issues early when contributors submit stream additions via issues/PRs.

• [ ] Create .github/workflows/validate-playlists.yml that runs 'npm run playlist:validate' and 'npm run playlist:lint' on every pull request and push
• [ ] Configure the workflow to report linting errors as PR comments using a tool like reviewdog or native GitHub annotations
• [ ] Add status checks requirement in repository settings to block merges if validation fails

Add integration tests for scripts/commands/playlist/generate.ts using real-world playlist scenarios

The generate.ts command is critical for creating categorized playlists (by country, language, category), but there are no visible integration tests validating the output format or category distribution. This is a high-risk area where bugs could affect thousands of users relying on these playlists.

• [ ] Create tests/scripts/commands/playlist/generate.test.ts with scenarios: empty playlists, single-country playlists, multi-language filtering, category organization, and header validation
• [ ] Use test fixtures from tests/fixtures/ containing sample stream data with various metadata combinations
• [ ] Validate generated M3U structure, verify all streams are included/excluded correctly per filters, and ensure generated playlists match expected category groupings

• Add TypeScript type definitions for M3U metadata parsing: scripts/core/playlistParser.ts currently lacks strict types for channel properties like tvg-id, tvg-name, tvg-logo; create interfaces/types.ts with PlaylistEntry and ChannelMetadata types and update all usages.
• Expand streamTester.ts to include response time metrics: Currently only tests liveness; add latency benchmarking and expose as optional column in validation reports to help identify slow streams.
• Create missing unit tests for scripts/core/dataSet.ts and scripts/core/proxyParser.ts: These utilities lack dedicated test files while others in tests/ have them; follow existing Jest patterns in tests/commands/playlist/test.ts as template.

The IPTV repository demonstrates a reasonable security baseline with TypeScript support, linting infrastructure, and GitHub Actions CI/CD. However, there are several areas for improvement: (1) The postinstall script poses an automation risk, (2) Missing automated dependency vulnerability scanning, (3) No visible input validation framework for CLI tools, (4) Insufficient secret management documentation, and (5) Lack of explicit type checking in CI/CD. The project would benefit from enabling Dependabot, adding security-focused ESLint rules, implementing input validation frameworks, and removing unnecessary automation scripts. Overall security posture is

• Medium · Postinstall Script Execution Risk — package.json - postinstall script. The package.json includes a 'postinstall' script that automatically executes 'npm run api:load' whenever dependencies are installed. This could potentially be abused if a compromised dependency or malicious actor gains control of the repository. Postinstall scripts run with full privileges and without explicit user consent. Fix: Remove the postinstall script or move the api:load command to an explicit setup step that requires user action. Document the required setup steps in CONTRIBUTING.md and require manual execution.
• Medium · Transitive Dependency Vulnerabilities — package.json dependencies and package-lock.json. The project relies on external packages like @octokit/core, @freearhey/core, and @iptv-org/sdk. These dependencies may contain known vulnerabilities. The package-lock.json file exists but is not shown in the audit, preventing full dependency tree analysis. No evidence of automated dependency scanning (Dependabot, Snyk) in GitHub workflows. Fix: Enable GitHub Dependabot for automated vulnerability scanning. Regularly audit dependencies using 'npm audit' and update vulnerable packages. Add automated security checks to GitHub Actions workflows (.github/workflows/).
• Low · Missing Input Validation in CLI Tools — scripts/commands/ directory, particularly scripts/core/playlistParser.ts. The codebase includes multiple CLI commands (playlist:edit, playlist:export, report:create, etc.) that accept user input via @inquirer/prompts. Without visible input sanitization logic, there's potential for injection attacks if the processed data is used in system commands or written to files without proper escaping. Fix: Implement input validation and sanitization for all user-supplied inputs. Use libraries like 'joi' or 'zod' for schema validation. Sanitize outputs before writing to files or using in shell commands. Review playlistParser.ts and streamTester.ts for proper escaping.
• Low · No Secret Management for API Credentials — scripts/commands/api/, scripts/api.ts. The project uses GitHub API tokens via @octokit/core (evident from api.ts and api/load.ts files). There's no visible .env or .env.example file to guide developers on secure credential handling. GitHub Actions workflows may expose secrets if not properly configured. Fix: Create a .env.example file documenting required environment variables. Add documentation on secure credential handling in CONTRIBUTING.md. Ensure GitHub Actions secrets are properly configured and never logged. Use GitHub's built-in secret masking features.
• Low · TypeScript Compilation Without Type Checking in CI/CD — .github/workflows/check.yml, package.json scripts. The project uses TypeScript (tsx for execution) but there's no explicit 'tsc --noEmit' type check step visible in the package.json scripts or .github/workflows. This could allow type-unsafe code to be committed, potentially leading to runtime vulnerabilities. Fix: Add a 'typecheck' script using 'tsc --noEmit' and include it in the check workflow. Ensure all CI/CD pipelines include TypeScript type checking before deployment.
• Low · ESLint Configuration Incomplete Visibility — eslint.config.mjs, package.json. While eslint.config.mjs exists, the specific security rules configured are not visible. The project uses @stylistic/eslint-plugin and @eslint/js but critical security-focused plugins (eslint-plugin-security, eslint-plugin-import) are not evident in dependencies. Fix: Add security-focused ESLint plugins like 'eslint-plugin-security' and 'eslint-plugin-node'. Configure rules to detect common vulnerabilities (hardcoded secrets, unsafe regex, etc.). Make the ESLint configuration more restrictive for security concerns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Read in the suggested order before editing unfamiliar code. The reading-order list is computed from the actual import graph, not LLM guesses; reading bottom-up materially reduces wrong-edit risk.
3. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
4. Cite source on changes. When proposing an edit, cite the specific path/to/file.ext:Lstart-Lend you're reasoning about, the same way RepoPilot's own RAG cites code in https://repopilot.app/r/iptv-org/iptv.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live iptv-org/iptv repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/iptv-org/iptv.

What it runs against: a local clone of iptv-org/iptv — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in iptv-org/iptv | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of iptv-org/iptv. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/iptv-org/iptv.git
#   cd iptv
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of iptv-org/iptv and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "iptv-org/iptv(\\.git)?\\b" \\
  && ok "origin remote is iptv-org/iptv" \\
  || miss "origin remote is not iptv-org/iptv (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "scripts/commands/playlist/generate.ts" \\
  && ok "scripts/commands/playlist/generate.ts" \\
  || miss "missing critical file: scripts/commands/playlist/generate.ts"
test -f "scripts/core/playlistParser.ts" \\
  && ok "scripts/core/playlistParser.ts" \\
  || miss "missing critical file: scripts/core/playlistParser.ts"
test -f "scripts/models/stream.ts" \\
  && ok "scripts/models/stream.ts" \\
  || miss "missing critical file: scripts/models/stream.ts"
test -f "scripts/generators/indexGenerator.ts" \\
  && ok "scripts/generators/indexGenerator.ts" \\
  || miss "missing critical file: scripts/generators/indexGenerator.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/iptv-org/iptv"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

1. scripts/constants.ts — Foundation: doesn't import anything internally and is imported by 28 other files. Read first to learn the vocabulary.
2. scripts/generators/generator.ts — Foundation: imported by 12, no internal dependencies of its own.
3. scripts/api.ts — Built on the foundation; imported by 15 downstream files.
4. scripts/commands/api/load.ts — Layer 2 — application-level code that wires the lower layers together.

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.