hongguoTV pairs an Android TV client with a Node bridge for unofficial video access

Two clients live in one repository: React Native and Kotlin

The current branch of the repository offers a Kotlin native standalone APK. Install it, connect it to the network, and it works without Node or Docker on the machine. The native project sits in `kotlin-tv/`, the application id is `com.hongguotv.nativeapp`, and it can coexist with the older build. The earlier React Native implementation is still in the repository and still documented.

The React Native version is built with React Native TV and TypeScript and targets Android 8.0, API level 26, as its minimum. The architecture splits the work in two: the television handles the interface and playback, while a separate Node service handles content access and media segment processing. That split is deliberate, because it means another platform could reuse the service without inheriting the television interface.

The release naming reflects the two tracks. Recent tags are `kotlin-v0.8.0`, `kotlin-v0.7.0` and `kotlin-v0.6.0`, all published in September 2026, and the npm `package.json` still carries version 0.1.1 for the React Native side. The repository is not archived and the last push was on 2026-09-24.

What the app does is ordinary television software: recommendations, keyword search, pagination, detail pages and episode selection on one side, and remote control focus, direction keys, the confirm key and the back key on the other. Playback keeps the original aspect ratio and supports pause, seeking forward and backward, moving between episodes and automatic continuation. Local state covers favourites, recently watched items and resuming from the last position.

The bridge service is where the unofficial interface lives

The Node service is where the platform contact happens. It listens on `127.0.0.1` by default, so on a developer machine nothing is exposed to the network until the `--lan` flag is passed, which explicitly opens access to the home network. Three parameters shape it: `BRIDGE_HOST`, `PORT` and `BRIDGE_TOKEN`, the last being an optional access password that the same value must be entered for in the television app settings.

That is the honest security boundary of the project. The service is designed for a home network, and the documentation says plainly that the access control needed for a public internet deployment is not implemented. There is no mention of transport encryption for the LAN traffic either, so a shared password is the only barrier between a device on the same network and the content feed.

The behaviour on failure is deliberate. On first launch the application has no service address configured, and it does not fall back on fabricated content. The built-in test player plays only the clearly labelled Big Buck Bunny public sample. When something goes wrong, an error is displayed rather than being replaced with fake listings.

The Node service itself is a thin shell over a pinned commit of the `drpys` source. The original files, the GPL-3.0 licence text and the provenance records are kept in the repository under `server/vendor/`, with the notice file pointing at them.

Running the service from a computer or a NAS

The documented workflow expects Node.js 22 or newer on the machine that will serve content. Installing the dependencies and starting the bridge with LAN access looks like this:

npm ci
npm run bridge -- --lan

The startup log prints the address to enter on the television, in the form of an http URL pointing at the computer's LAN address on port 8787.

If you only want the service and not the React Native application, the install is scoped to the server directory and the process is started directly:

npm ci --prefix server
node server/index.mjs --lan

Docker is the option for a NAS or a headless machine. The repository ships a `.env.example`, and the compose file in the `server/` directory builds and starts the service:

cp .env.example .env
docker compose --env-file .env -f server/compose.yaml up -d --build

The compose file pulls `ghcr.io/n3urda/hongguotv-bridge:${HONGGUOTV_VERSION:-0.1.1}`, publishes port 8787 from a bind address that defaults to `0.0.0.0`, and passes the host, port and token through environment variables. The container runs read-only, drops all capabilities, sets the no-new-privileges option and keeps a capped log file. Published images exist for AMD64 and ARM64.

One detail catches people: the Node process does not read `.env` by itself. The variables have to be passed by the shell or by the deployment tooling, which is why the compose file is started with `--env-file`.

Getting the APK onto the television

The television needs the application installed, and there are two routes. You can download the APK from the project's releases and copy it to the television yourself, or you can build it locally and install it over ADB. The locally built artifact is named `outputs/hongguotv-0.1.1-android8.apk`, and the ADB command is:

adb install -r outputs/hongguotv-0.1.1-android8.apk

The `-r` flag is what lets the new package overwrite an existing installation, which matters later because of how signing and updates work.

After installation the television and the machine running the bridge have to be on the same home network. In the application settings you enter the address shown in the startup log and choose connect and save. The documentation is emphatic about one thing: `127.0.0.1` on the television points at the television itself, not at your computer, so the LAN address is mandatory.

Two operational conditions are worth planning around. The content service has to keep running while you watch, and the computer cannot go to sleep. A bridge running on a NAS avoids both problems, which is the arrangement the Docker path is really aimed at.

Minimum Android 8.0 is a configuration floor rather than a certification. The project documentation states that the minimum version setting does not mean the target television has been accepted, and that while an Apple TV skeleton is kept, the mobile and web clients have not been delivered.

Version 0.9.0 added in-application updates for the native build

The native branch introduced in-app updating. The mechanism is that pushing native code to the repository automatically synchronises it to the public release repository and builds a signed APK, and the television then checks for a newer version while the user browses and downloads it, leaving a system installation confirmation to the user. Two deliberate limits are documented: the check does not run during playback, and an overwriting installation preserves the records already on the device.

That second point matters more than it first appears, because it is also what makes the signing story delicate. The release APK is built with a local development signature intended for personal installation. The signing file is excluded from version control, so building on another machine requires keeping the same key if you want the new build to overwrite an existing installation directly. Before distributing the application publicly, the project says you should configure your own proper release signing.

For the React Native track, the improvement history is documented per release. Version 0.1.1 covers television focus scrolling, restoring state on back, remote control playback keys, safe margins and grouping of episodes. Those are the kinds of fixes that only appear once real hardware is in the loop.

GPL-3.0 code, GPL-3.0 vendored source, MIT template skeleton

The licensing is layered, and anyone planning to redistribute has to read all three layers. The project code is provided under GPL-3.0, with the `package.json` spelling it as `GPL-3.0-only`. The Node service is built on a pinned commit of the `drpys` source, and the original files are kept with their own GPL-3.0 licence and source records under `server/vendor/`, which is what makes the combination compliant rather than merely convenient. The Android and tvOS project skeletons come from an MIT licensed React Native TV template.

The project also states that it has no affiliation with the platform's official operator, that the content interface is an unofficial implementation, and that platform changes may break it. That is the honest framing for a client that talks to a service whose API is not public, and it is also the reason the error handling shows failures instead of substituting content.

The practical consequence for an adopter is that the interface layer is the fragile part and the client around it is not. The Kotlin releases published on 2026-09-23, the `kotlin-v0.6.0`, `kotlin-v0.7.0` and `kotlin-v0.8.0` tags, are built on top of an interface that the platform can change at any time without notice.

Development commands and what the automated checks cover

The scripts defined in `package.json` are short and easy to read:

    "start": "react-native start",
    "android": "react-native run-android",
    "typecheck": "tsc --noEmit",
    "test": "node --import tsx --test tests/*.test.*",
    "bridge": "node server/index.mjs",
    "probe": "node scripts/probe.mjs",
    "build:android": "bash scripts/build-android.sh"

The type check and the test suite run against the TypeScript sources, with the tests executed through the Node test runner and `tsx`. The probe script is the research tool: run from a second terminal against the real platform, it writes its findings to `outputs/probe.json`.

Building the Android package needs a specific toolchain, namely JDK 17, Android SDK 36, Build Tools 36.0.0 and NDK 27.1.12297006. The resulting release APK includes the JavaScript, so the television does not need Metro or a development server at runtime. The npm manifest declares `node` `>=22.0.0` as the engine requirement, and the runtime dependencies are small and specific: `axios` for HTTP, `react-native-video` for playback, `@react-native-async-storage/async-storage` for local records, and the React Native TV build aliased as `npm:[email protected]`.

That combination tells you where the fragility sits. The application side is an ordinary React Native app with pinned dependencies and a type check. The service side talks to an interface nobody guarantees.

Editorial conclusion

hongguoTV suits a household running its own TV box on Android 8.0 or newer, with one computer or NAS on the home network that can stay awake while a Node 22 bridge serves content, and it suits a developer who wants to study how a TV interface can be built on top of an unofficial platform interface. It does not suit a public deployment, because the bridge has no full access control and only the home network is supported, and it does not suit someone who needs signed builds, since the release workflow documents a local development signature and the keystore is not in the repository. Check three things before adopting: whether your television runs Android 8.0 or later, whether the bridge and the TV can reach each other over the LAN with `BRIDGE_TOKEN` set if you want a password, and whether the Kotlin releases published on 2026-09-23 still work against the platform, since the interface is unofficial and the last push was on 2026-09-24.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. N3urda/hongguoTV on GitHub
4. README
5. Releases