yunnysunny/hotel-tvn repository overview

⁠hotel-tvn

Generate hotel TV / IPTV channel lists from a data JSON. The tool reads a list of service URLs, probes JSON endpoints on the local network, parses channel lists, tests stream availability and speed, then writes lives.txt and lives.m3u.

⁠What it does

1. Reads a data JSON file (e.g. tv_service.json) containing service base URLs.
2. Expands each base URL into candidate JSON URLs (e.g. scanning last octet 1–255).
3. Checks which JSON URLs are reachable.
4. Fetches and parses channel lists from each available JSON endpoint.
5. Tests each channel stream and measures speed.
6. Writes the playable channels to lives.txt and lives.m3u in the chosen output directory.

⁠Requirements

• Node.js (recommended v18+)
• pnpm (or npm / yarn)

⁠Install

Install globally with npm:

npm install -g hotel-tvn

The tvn and sgen commands will be available on your PATH.

⁠Command-line usage (tvn)

⁠Run with defaults

Uses tv_service.json in the current directory and default concurrency:

tvn

Options:

⁠More Examples

# Custom data file and output directory
tvn -d ./my-services.json -o ./output

# Limit concurrency
tvn --concurrency-json 128 --concurrency-stream 32

# Help
tvn --help

⁠How to get tv_service.json

The tv_service.json can be generated from result.json using the sgen command.

If you have a result.json exported from Censys⁠, use sgen to parse it and generate tv_service.json for tvn (each item is { baseUrl, province, city }).

# Use default paths: input dist/result.json, output tv_service.json
sgen parse-result-json

# Specify input and output paths
sgen parse-result-json -i ./my_result.json -o ./my_tv_service.json

⁠Use Quake as the data source

sgen can also build tv_service.json from Quake⁠ search results. Because low-privilege accounts get a masked ip field (e.g. 36.*.*.*), the real IP and port are taken from the id field (e.g. 36.136.38.87_9901_tcp). province / city use the Chinese names (province_cn / city_cn).

Fetch directly from the Quake API (the token is read from --token or the QUAKE_TOKEN environment variable):

# Defaults: query 'response:"/iptv/live/" AND country:"China"', size 100, max 100
QUAKE_TOKEN=xxx sgen fetch-quake

# Custom query / paging, and keep the raw Quake result
sgen fetch-quake -q 'response:"/iptv/live/" AND country:"China"' --size 100 --max 500 -r ./quake-result.json -o ./tv_service.json

Or parse Quake results saved to disk (multiple files are merged and deduplicated):

sgen parse-quake-json -i ./page1.json,./page2.json -o ./tv_service.json

The Quake GitHub workflow (.github/workflows/quake.yml) runs sgen fetch-quake --size 100 --max-pages 1 (a single request for 100 records) on the 1st of every month and commits the updated tv_service.json. Add your token as the QUAKE_TOKEN repository secret to enable it.

⁠Use as a JavaScript / TypeScript library

Install in your project:

pnpm add hotel-tvn
# or: npm install hotel-tvn

The package supports both CommonJS and ESM and exports types.

⁠ESM

import { build, GenOptions } from 'hotel-tvn';

const options: GenOptions = {
  dataJsonPath: './tv_service.json',
  liveResultDir: './output',
  concurrencyJson: 256,
  concurrencyStream: 64,
};

await build(options);

⁠CommonJS

const { build } = require('hotel-tvn');

await build({
  dataJsonPath: './tv_service.json',
  liveResultDir: './output',
});

⁠Exported API and types

• build(options?: GenOptions): Promise<void>
  Runs the full pipeline (read data JSON → probe URLs → parse channels → test streams → write lives.txt and lives.m3u). Options match the CLI:

  • dataJsonPath – path to the data JSON file
  • liveResultDir – directory for lives.txt and lives.m3u
  • concurrencyJson – concurrency for JSON checks
  • concurrencyStream – concurrency for stream tests

• Types: GenOptions, Channel, ParsedChannel, RegionUrl, TvServiceItem (see types.ts).

⁠Docker image usage

The project provides a Docker image to run the tvn pipeline and a scheduled task (runs once daily at midnight).

⁠Pull the image

Pull from Docker Hub:

docker pull yunnysunny/hotel-tvn:latest

⁠Run the container

Basic usage: mount your data file and output directory, then run.

# Windows (PowerShell)
docker run -d --name hotel-tvn `
  -p 8080:80 `
  -v ${PWD}/tv_service.json:/app/tv_service.json `
  -v ${PWD}/output:/app/output `
  -e LIVE_RESULT_DIR=/app/output `
  yunnysunny/hotel-tvn:latest

# Linux / macOS
docker run -d --name hotel-tvn \
  -p 8080:80 \
  -v "$(pwd)/tv_service.json:/app/tv_service.json" \
  -v "$(pwd)/output:/app/output" \
  -e LIVE_RESULT_DIR=/app/output \
  yunnysunny/hotel-tvn:latest

• First volume: mounts your host tv_service.json into the container as the data source.
• Second volume: mounts your host output directory to /app/output and sets LIVE_RESULT_DIR=/app/output so lives.txt and lives.m3u are written there and visible on the host under output.
• -p 8080:80: exposes the in-container HTTP server so you can access the channel list via URL (see below).

⁠Access lives.txt and lives.m3u via HTTP

The container runs an HTTP server on port 8080 that serves the generated channel list files. After starting the container with -p 8080:80, you can open or use these URLs:

• On the same machine: use http://localhost:8080/lives.txt or http://localhost:8080/lives.m3u.
• From another device on the network: replace localhost with the host’s IP (e.g. http://192.168.1.100:8080/lives.m3u).

You can paste the lives.m3u URL into an IPTV app, or open lives.txt in a browser to copy stream links.

⁠Environment variables

The scheduled task reads schedule-config.json generated from these variables (you can generate this config at container startup if needed).

timeRatio is calculated as segmentDuration / downloadDuration. A larger value means the stream segment downloads faster relative to its playback duration and is therefore smoother to play.

• Increase MIN_RATIO_TOLERANCE to make filtering stricter and keep only smoother streams.
• Decrease MIN_RATIO_TOLERANCE to allow slower streams that may still be playable.

Example: custom output directory and concurrency

docker run -d --name hotel-tvn \
  -p 8080:80 \
  -e LIVE_RESULT_DIR=/app/output \
  -e CONCURRENCY_JSON=128 \
  -e CONCURRENCY_STREAM=32 \
  -v "$(pwd)/tv_service.json:/app/tv_service.json" \
  -v "$(pwd)/output:/app/output" \
  yunnysunny/hotel-tvn:latest

⁠Build the image locally

From the project root:

docker build -t hotel-tvn:local .

Example run with the local image:

docker run -d --name hotel-tvn \
  -p 8080:80 \
  -v "$(pwd)/tv_service.json:/app/tv_service.json" \
  -v "$(pwd)/output:/app/output" \
  -e LIVE_RESULT_DIR=/app/output \
  hotel-tvn:local

⁠License

MIT⁠