ws4kp-linhanced/README.md

![Weatherstar 4000+ Current Conditions](https://github.com/netbymatt/ws4kp/blob/main/server/images/social/1200x600.png)

# ws4kp-linhanced

`ws4kp-linhanced` is a Linux-focused fork of [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) by `markmental`.

It keeps the stronger, more stable foundation of the original `ws4kp` project while selectively incorporating international weather support and global map ideas from [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international). The goal is not to become a kitchen-sink weather platform. The goal is a leaner, maintainable, Linux-oriented WeatherStar fork with a clear identity.

This fork also explicitly embraces Slackware Linux / `weatherstar4k` branding as part of its mission. Broad platform neutrality is not a design goal here.

## What This Fork Is

`ws4kp-linhanced` is a retro weather display project that preserves the classic WeatherStar-style feel while updating the data sources and map stack for modern use.

This fork is built around a few priorities:

* keep the classic WeatherStar presentation and pacing intact where practical
* support international locations without dragging in unnecessary feature creep
* prefer a stable, understandable codebase over maximum feature count
* lean into Linux-oriented branding and integrations where they add character and usefulness

It is not intended to be a perfect hardware emulation of the original WeatherStar 4000. If you want a project aimed more directly at hardware-faithful behavior, see the [WS4000 Simulator](http://www.taiganet.com/).

## Why This Fork Exists

This fork exists because the original `ws4kp` codebase provided the best overall base to keep working from, but it remained too tightly tied to US-only weather sources. At the same time, `ws4kp-international` proved that Open-Meteo and global map support were viable, but it grew in directions that felt heavier and harder to maintain.

This fork sits in the middle on purpose:

* more international than upstream `ws4kp`
* leaner and narrower in scope than `ws4kp-international`
* more explicitly Linux-focused than either

## Fork Lineage

This project builds on the work of:

* [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the core WeatherStar implementation and overall application structure
* [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for Open-Meteo international weather direction and some global-map concepts

This fork intentionally diverges from `ws4kp-international`. It selectively adapts the parts that fit this project and leaves behind the parts that would make the codebase harder to keep stable.

## Current Features

Major features currently in this fork:

* Open-Meteo-based international weather for the core forecast screens
* ArcGIS-powered international location search and reverse geocoding
* global RainViewer radar on a cached world basemap
* global `Regional Observations` on the newer map stack
* Travel Forecast rebuilt around region buckets with a global fallback
* live theme switching with auto-discovered theme folders
* Server Observations powered by [fastfetch](https://github.com/fastfetch-cli/fastfetch)
* server-side caching proxy for Open-Meteo, RainViewer metadata, and ArcGIS basemap tiles
* static-build path fixes for subdirectory deployment

Some NOAA-only products are still retained where they remain useful and there is no replacement yet:

* Hazards
* SPC Outlook

## Themes

`ws4kp-linhanced` supports live asset theme swapping from the main page. Themes are discovered automatically from the `themes/` directory and can be changed from the `Theme` selector under the `More information` link without reloading the page.

Current themes include:

* `Default`: the standard WeatherStar 4000+ asset set
* `oceanview`: based on the Oceanview Weather Channel presentation from the Eventide Media Center analog horror series
* `slackware`: based on the Oceanview theme, but with the Slackware Linux badge/logo treatment

Current themed assets include:

* `logo-corner.png`
* `1.png`
* `1-chart.png`
* `2.png`
* `3.png`
* `4.png`
* `5.png`

Additional themes can be added by creating a subdirectory under `themes/` with matching override filenames.

## Quick Start

Ensure you have Node installed.

```bash
git clone <your fork url here>
cd ws4kp-linhanced
npm install
npm start
```

Then open:

```text
http://localhost:8080/
```

## Running Modes

This fork supports two main runtime styles.

### Server Mode

Recommended for normal use.

```bash
npm start
```

This mode includes:

* Express server entry point
* proxying and caching for weather/map requests
* Fastfetch-backed Server Observations
* better shared performance when multiple clients use the same instance

### Static Mode

Useful if you want to serve the built files directly.

```bash
npm run build
STATIC=1 DIST=1 npm start
```

Or upload the generated `dist/` directory to your web server after running:

```bash
npm run build
```

The static build has been adjusted so frontend-generated paths no longer assume deployment at `/`, which makes subdirectory hosting more practical.

## International Support

Core forecast functionality works internationally.

That currently includes:

* Current Conditions
* Hourly Forecast
* Hourly Graph
* Local Forecast
* Extended Forecast
* Almanac
* Travel Forecast
* Local Radar
* Regional Observations

Legacy NOAA-only screens still remain US-specific where applicable.

## Settings And Customization

Important settings and customization features include:

* playback speed
* widescreen mode
* kiosk mode
* scan lines
* US vs metric units
* theme selection
* custom bottom scroll text
* display enable/disable checkboxes

### Permalinks

Display selections, location, and major settings can be shared or bookmarked through the built-in permalink feature.

### Kiosk Mode

Kiosk mode hides the surrounding controls and maximizes the display area for dedicated setups. It can be triggered from the UI or via permalink parameters.

### Custom Scroll Text

The bottom text crawl can be customized using the built-in custom text setting.

Multiple messages can be separated with `|` to rotate randomly.

Example:

```text
Welcome to Weatherstar|Thanks for watching
```

### Custom Hook

A customization hook is available as:

```text
server/scripts/custom.js
```

A sample file exists at:

```text
server/scripts/custom.sample.js
```

## Music

The original WeatherStar atmosphere depended heavily on background music. This repo includes a small set of WeatherStar-inspired tracks, while keeping the total size manageable.

If you want to use your own music, place `.mp3` files in:

```text
server/music/
```

The application will build or serve a playlist from those files depending on the runtime mode.

## Build And Maintenance Notes

This fork tries to stay practical not only at runtime, but also in how it is maintained.

That includes:

* keeping the codebase relatively small and understandable
* avoiding unnecessary build complexity where possible
* trimming or replacing dependencies when the benefit is low
* addressing build-step vulnerabilities instead of ignoring them

Recent cleanup includes removing vulnerable build-only sourcemap tooling from the main build pipeline.

## Motivation

Part of the motivation is simple nostalgia: old Weather Channel presentation still has a very distinct charm.

The other part is more practical. A Linux-friendly, self-hostable retro weather display is still a fun and useful thing to have around, especially when it stays light enough to keep hacking on without turning into an enormous platform project.

## Acknowledgements

This project builds on earlier work from the WeatherStar community and related forks.

Credits and thanks go to:

* [Mike Battaglia](https://github.com/vbguyny/ws4kp) for the original project lineage
* [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the upstream base this fork was built from
* [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for proving out the Open-Meteo international direction
* [TWCClassics](https://twcclassics.com/) for WeatherStar reference material, fonts, and icon resources
* the broader WeatherStar community for reference material and ongoing experimentation

## Disclaimer

This project should **not** be relied upon in life-threatening weather situations or as a mission-critical public weather information source.

Internet services fail, upstream data can be delayed, and browser-based applications are not a substitute for dedicated alerting systems.

The WeatherSTAR 4000 name and original technology belong to The Weather Channel. This project is a fan-made, non-commercial recreation and reinterpretation.