tvbox-json-monitor/README.md

TVBox JSON Monitor

This repository automatically monitors a TVBox-compatible endpoint, extracts the hidden configuration payload, decodes it, normalizes it as strict JSON, and commits updates when changes are detected.

The update process is handled by GitHub Actions on a scheduled basis.

What this repository does

The monitored endpoint returns a JPEG-like payload for TVBox-style clients.

The actual TVBox configuration is embedded after the JPEG end marker:

1. Request the endpoint with a TVBox-like User-Agent.
2. Locate the JPEG EOI marker: FF D9.
3. Read the appended payload after the JPEG data.
4. Locate the ** separator.
5. Base64-decode the content after the separator.
6. Normalize the decoded configuration into strict JSON.
7. Commit the updated JSON files when changes are detected.

Output files

The workflow maintains the following generated files:

data/tvbox.json
data/tvbox.meta.json

data/tvbox.json

This is the decoded TVBox configuration, normalized as strict JSON.

The upstream configuration may contain JSONC-style full-line comments. These comments are removed so that the stored file can be parsed by standard JSON tools.

data/tvbox.meta.json

This file contains metadata about the latest decoded payload, including:

source_url
final_url
user_agent
raw_size
raw_sha256
decoded_size
decoded_sha256
json_sha256
jpeg_eoi_offset
appended_size
base64_size
etag
last_modified
cache_control
content_type

GitHub Actions workflow

The workflow runs automatically every 5 minutes:

- cron: "*/5 * * * *"

It can also be triggered manually from the GitHub Actions UI using workflow_dispatch.

GitHub-hosted scheduled workflows are not guaranteed to run exactly on time. They may be delayed depending on GitHub Actions load.

Repository variable

The monitored endpoint URL is configured through a GitHub Actions repository variable.

Create the following repository variable:

Name: TVBOX_URL
Value: https://www.xn--sss604efuw.com/tv/

The URL should preferably include the trailing slash to avoid unnecessary redirects.

To set it:

Repository
→ Settings
→ Secrets and variables
→ Actions
→ Variables
→ New repository variable

Required repository settings

The workflow commits generated files back to the repository.

Make sure GitHub Actions has write permission:

Repository
→ Settings
→ Actions
→ General
→ Workflow permissions
→ Read and write permissions

Commit behavior

If the decoded JSON has not changed, the workflow exits without creating a commit.

If changes are detected, the workflow commits the updated files with a message like:

chore(tvbox): update decoded JSON 2026-05-13T16:00:00Z

File normalization

The generated data/tvbox.json is not a byte-for-byte copy of the decoded upstream payload.

It is normalized for public repository use:

• Full-line // comments are removed.
• JSON is parsed and re-serialized.
• UTF-8 characters are preserved.
• Output formatting uses 2-space indentation.
• Object key order is preserved as parsed by Python.

This makes the file easier to diff, inspect, and consume with standard JSON tooling.

Security and privacy

The endpoint URL is stored as a repository variable, not a secret.

This is intentional because the URL is not sensitive and this repository is designed for public use.

No credentials are required beyond the default GITHUB_TOKEN provided by GitHub Actions.

Local extraction

The same extraction logic can be run locally with Python:

export TVBOX_URL="https://www.xn--sss604efuw.com/tv/"
export TVBOX_UA="okhttp/3.15"
export OUT_JSON="data/tvbox.json"
export OUT_META="data/tvbox.meta.json"

python3 scripts/extract_tvbox.py

Disclaimer

This repository only monitors, decodes, normalizes, and stores configuration data from the configured endpoint.

It does not host video content, proxy media streams, or provide any playback service.