Skip to content
aayusbhat26Public

About

Local-first Windows-to-TV casting: pick a video on the laptop, play it on the TV over Chromecast. No library, account, or upload.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Lantern

A small link between this Windows laptop and the TV. Open any local video from the laptop and it plays on the Airtel Xstream Box over the home network. The laptop is the remote. There is no library, no account, no upload, and nothing to install on the TV — it uses the Box's built-in Chromecast.

Lantern.cmd

Double-click Lantern.cmd. The first run installs/builds, then a browser app window opens with the control room. Keep the console window open while you use it.


What you need

  • This Windows laptop with Node.js 20 or newer (already present).
  • The Airtel Xstream Box powered on, with Chromecast built-in, on the same Wi-Fi network as the laptop. No app or pairing on the TV is required.
  • The laptop and the Box must be able to talk to each other (the same subnet). Guest Wi-Fi, a VPN on the laptop, or AP/client isolation on the router can block discovery or the media fetch.

Lantern finds the Box automatically and shows it as Xstream Box in the top bar. If it is not there, turn the Box on, then use the screen chip → Scan.


Using it

  1. Click Open a file.
  2. Browse this laptop (Home / Videos / Downloads / Desktop / drives), or paste a full path at the top and press Enter. A folder path navigates; a video path opens.
  3. Choose a video and click Open.

It starts on the TV. The laptop shows the file, what is being sent (original or converted), and the controls.

  • Play / pause — the large centre button, or Space.
  • Skip 10 seconds — the arrows, or ← / →.
  • Seek — click or drag the timeline.
  • TV volume / mute — the control at the right of the transport.
  • Audio track — the Audio field in the right-hand rail.
  • Subtitles — the Subtitles field; text tracks are burned into the picture.
  • Quality — keep Original file when possible; choose 720p if the Box struggles or you want a lighter stream.
  • Stop casting — ends playback and releases the TV.
  • Show in folder — opens Explorer with the file selected.
  • Play last file — on the idle screen, re-opens the most recent file.

Other shortcuts: O opens the file browser, M mutes the TV, Esc closes dialogs. Closing the browser window does not stop an active cast; use Stop casting or close the console window first.

Recent files are kept for convenience, with missing files marked. Remove an entry with the × on its row.


Windows app

The packaged Windows build is a portable executable: run it, and Lantern opens as a normal desktop app without a Node.js install or a browser window. Closing the window hides Lantern to the system tray so an active cast keeps running; use Quit from the tray menu to stop it. Recents and preferences live in %APPDATA%\Lantern, not in the folder the executable was launched from.

The Windows executable is currently unsigned, so SmartScreen may ask for confirmation on first launch. The TV still needs to be able to reach the laptop over the home network; allow Lantern through Windows Firewall on private networks if prompted.

To build the portable app from source, with FFmpeg present in .tools:

npm install
npm run build
npm run desktop:prepare
npx electron-builder --win portable

The executable is written to release/.

Download page

site/ is a static Next.js App Router page for GitHub Pages. It needs no server.

npm run site:dev     # http://127.0.0.1:7350
npm run site:build   # static output in site/out

The download page checks the latest GitHub release and only enables a platform when its asset exists. For Windows, upload both Lantern-1.1.0-win-x64.exe and Lantern-1.1.0-win-x64.exe.sha256; for Android, upload Lantern-1.0.0-android.apk. Until then the card stays in a clear pending state instead of offering a broken link. .github/workflows/pages.yml deploys the static page to GitHub Pages on main and on a published release.


How playback works

Lantern serves the file directly from the laptop to the Box over HTTP.

Original stream (preferred). MP4/MKV files with H.264 or HEVC video and AAC, AC-3, E-AC-3, or MP3 audio are played untouched. The Box fetches the file with byte ranges, so seeking is native and there is no conversion work on the laptop.

Live conversion. Anything the Box cannot take as-is is converted on the fly to H.264/AAC fragmented MP4 with FFmpeg:

  • MPEG-2, MPEG-4, WMV, older codecs → H.264 (hardware AMD AMF on this laptop; NVENC/Quick Sync are detected automatically if available).
  • DTS, TrueHD, PCM, and other audio → AAC stereo.
  • HDR is tone-mapped to SDR when a conversion is needed.
  • Text subtitles are burned into the converted picture.
  • Seeking a converted stream restarts the converter at the new point; expect a short pause while it finds the frame.

Direct files start essentially immediately over a good LAN. Converted streams start after the first frame; on this laptop the hardware converter produces it in a few hundred milliseconds, and the whole cast handshake usually takes a few seconds. Actual buffering after that depends on the Wi-Fi link and the TV.


Tested on this setup

With the Xstream Box on the same LAN, Lantern was verified end to end with:

  • Direct MP4 (H.264/AAC), direct MKV (H.264/AAC), direct MKV (H.264/AC-3), and direct MKV (HEVC/AC-3).
  • A live hardware-converted MPEG-2/AAC stream.
  • A live 10-bit HEVC HDR → H.264 SDR conversion, including tone-mapping and AAC audio.
  • Pause/resume, 10-second skips, native timeline seeking, track switching, burned-in English/Hindi subtitles, stop, and re-cast.
  • The TV fetching media directly from the laptop through the production server.

Troubleshooting

No screen found

  • Wake the Box and make sure it is on the same Wi-Fi as the laptop.
  • Use the screen chip → Scan.
  • Make sure the laptop is not on a VPN and the Wi-Fi is not a guest network with client isolation. Chromecast discovery uses local multicast.
  • If the Box is in a deep sleep, turn it on once with the TV remote; the app will find it and Casting will wake it on later plays.
  • If a phone/another app is already casting to the Box, that session can interrupt discovery/playback. Stop it and try again.

The TV can't start a file

  • Run Allow Firewall.cmd once (administrator permission) and allow Node.js on private networks if Windows asks. The laptop must accept the TV's connection to port 7340.
  • Check Settings → Network. The shown laptop address must be the one the TV can reach. A VPN or a second network adapter can choose the wrong address.
  • Try again; if a direct stream fails, Lantern automatically retries with a live conversion. The rail shows the mode after it starts.

It plays but stutters or looks too heavy

  • For a converted 4K source, choose 720p in the quality field, or use a smaller file. Hardware conversion of 4K on this laptop is not a guarantee.
  • Prefer 5 GHz Wi-Fi or Ethernet for the laptop. The Box also has to be on a stable connection.
  • Direct files use no converter; if the rail says Original file, playback problems are network/TV-side.

Sound or subtitles are wrong

  • Choose the right track in the rail. A non-default audio track forces a lightweight conversion (video untouched, audio re-encoded).
  • Text subtitles (SRT/ASS/mov_text) can be burned in. Image-based subtitles (PGS/VobSub) are not supported.
  • DRM-protected content cannot be played by Lantern.

The TV is showing a Cast screen after I stopped

  • Use Stop casting. If the Box keeps its cast screen, press Back/Home on the TV remote or wait for the receiver to idle.

Privacy and local access

  • The control UI and all control APIs accept connections only from the laptop's loopback address. The scan/play/stop endpoints are not reachable from the LAN.
  • The TV may fetch only tokenised, session-specific media URLs (/api/media/<random-session>/original or /live). There is no LAN file browser and no generic media URL.
  • Sessions are random and expire after 12 hours; stopping the server invalidates everything.
  • Nothing is uploaded. The laptop is the only server involved.
  • Runtime data lives in .data/:
    • lantern.json — recent files, selected screen, quality preference.
    • subtitles/ — cache of extracted subtitle files.
    • Delete .data/ while Lantern is closed to reset it.

Windows Firewall rule from Allow Firewall.cmd: inbound TCP 7340 on the private profile only. Remove it with:

netsh advfirewall firewall delete rule name="Lantern media (TCP 7340)"

Project map

Lantern.cmd                 one-click launcher
Allow Firewall.cmd          optional private-network firewall rule (admin)
server.js                   production server; loopback-only control boundary
scripts/start.mjs           wait for readiness, open the app window
src/lib/cast.ts             discovery, Chromecast session, seek/volume/device state
src/lib/stream.ts           direct/remux/convert plans + FFmpeg arguments
src/lib/media-stream.ts     HTTP ranges, live fMP4 pipe, CORS, process cleanup
src/lib/probe.ts            FFprobe metadata
src/lib/ffmpeg.ts           bundled engine + hardware encoder detection
src/app/api/                local control APIs + tokenised TV media routes
src/components/             the laptop interface
src/app/                    Next.js App Router pages and design
.tools/ffmpeg-...           bundled FFmpeg (GPL build)
.data/                      runtime settings, recents, subtitle cache (created later)

The FFmpeg build in .tools/ includes AMD AMF, NVIDIA NVENC, Intel QSV, libx264, libx265, zscale, and libass. Encoders are tested at startup; on this machine NVENC is unavailable with the installed driver, so AMD AMF is selected automatically.

Requires Node.js 20.9+. Built with Next.js 16 and TypeScript.

About

Local-first Windows-to-TV casting: pick a video on the laptop, play it on the TV over Chromecast. No library, account, or upload.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages