WeatherStar 4000+

A live version of this project is available at https://weatherstar.netbymatt.com

To run your own copy, see Quick Start.

What's new in v8.0

This release adds one major feature and a lot of work behind the scenes:

• Future Radar is a new display that loops forecast radar reflectivity from NOAA's HRRR (High-Resolution Rapid Refresh) model for the next several hours. It is available within the continental United States.
• Updated Maps Maps were redrawn from public data in the classic weatherstar style and are now a proper mercator projection.
• New Weatherstar Album The new album "Latest Observations" adds 13 tracks to Weatherstar's playlist.
• Code cleanup a significant cleanup of the code throughout the project.

About

This project aims to bring back the feel of the 90s with a weather forecast that has the look and feel of The Weather Channel at that time but available in a modern way. This is by no means intended to be a perfect emulation of the WeatherStar 4000, the hardware that produced those wonderful blue and orange graphics you saw during the local forecast on The Weather Channel. If you would like a much more accurate project please see the WS4000 Simulator. Instead, this project intends to create a simple to use interface with minimal configuration fuss. Some changes have been made to the screens available because either more or less forecast information is available today than was in the 90s. Most of these changes are listed in What's different below.

What's different

I've made several changes to this WeatherStar 4000 simulation compared to the original hardware unit and the code that this was forked from.

• Radar displays the timestamp of the image. Local Radar is not available for Alaska or Hawaii.
• A new Future Radar display loops forecast radar reflectivity from the HRRR model for the next several hours. It is only available within the continental United States.
• A new hour-by-hour graph of the temperature, dewpoint, cloud cover and precipitation chances for the next 36 hours (48 hours in Widescreen Enhanced).
• A new hourly forecast display for the next 24 hours is available, and is shown in the style of the travel cities forecast. (off by default because it duplicates the hourly graph)
• The SPC Outlook is shown in the style of the old air quality screen. This shows the probability of severe weather over the next 3 days at your location. SPC outlook only displays if you're within one of the highlight areas over the next 3 days. You can view the maps and pick a location within one of the risk categories to see if the screen is working for you.
• The "Local Forecast" and "Extended Forecast" provide several additional days of information compared to the original format in the 90s.
• The original music has been replaced. More info in Music.
• Marine forecast (tides) is not available as it is not reliably part of the new API.
• "Flavors" are not present in this simulation. Flavors refer to the order of the weather information that was shown on the original units. Instead, the order of the displays has been fixed and checkboxes on the Displays tab can be used to turn on and off individual displays. The travel forecast has been defaulted to off so only local information shows for new users.

What's your motivation

Nostalgia. And I enjoy following the weather, especially severe storms.

It's also a creative outlet for me and keeps my programming skills honed for when I need them for my day job.

Does WeatherStar 4000+ work outside of the USA?

This project is tightly coupled to NOAA's Weather API, which is exclusive to the United States. Using NOAA's Weather API is a crucial requirement to provide an authentic WeatherStar 4000+ experience. Choosing a location outside the United States shows a message under the search box instead of a forecast.

If you would like to display weather information for international locations (outside of the USA), please check out a fork of this project created by @mwood77:

• ws4kp-international

Using WeatherStar

Choosing a location

Type a ZIP code, a city and state, or a place name into the box above the display and pick a suggestion, or press GO to use the first match. Only US locations are available.

The GPS button uses your device's location. Browsers only allow this on https:// pages or on localhost, so a self-hosted copy may need a certificate (see Community Notes). When GPS is used, it is used again on your next visit.

Reset clears the saved location and returns to the title card. If a location can't be found, or the National Weather Service isn't responding, a message appears under the search box.

Page layout

Below the weather display are four tabs:

• Displays: Checkboxes to turn each display on or off, with a count of how many are enabled. Each display's name is colored by its status (ready, loading, failed or off/no data), and clicking the name of a ready display jumps straight to it. Hazards shows an ALERT tag when there are alerts you haven't seen yet.
• Settings: The options described in Settings.
• Share: Shows and copies a permalink to your current configuration.
• Headend: What the forecast is built from: the location, the observation station and when it last reported, the radar, forecast zone, NWS office and grid point, the HRRR model run used by Future Radar, and when the data was last refreshed. It also shows the display mode and scale, whether the page is using the caching server, any displays that are failing, the version number and the music track that is playing. The "Copy headend info" button copies all of this as text, which is helpful to include when reporting an issue.

Keyboard shortcuts

These work while the page itself has focus (click on the weather display first if you've been typing in the location box or using a tab), and in fullscreen and kiosk mode.

Key	Action
Space	Play or pause
→ or Page Down	Next screen
← or Page Up	Previous screen
↑	Stop playback and show the list of displays
0 (zero)	Reload the forecast data
F	Enter or exit fullscreen
Ctrl-K	Exit kiosk mode

On a touch screen, swipe left or right on the weather display for the next or previous screen.

Settings

These are found on the Settings tab below the weather display.

Speed: Controls the playback speed of the displays, from "Very Fast" (2x) to "Very Slow" (0.67x) with "Normal" being 1x. Note: if editing the permalink the multipliers are inverse with Very Fast = 0.5 and Very Slow = 1.5. These are the multipliers that are applied directly to the time delays in the slide deck.

Display Mode:

• Standard: Classic 4:3 display with the classic (not enhanced, below) screen layouts.
• Widescreen: Stretches the background to 16:9 to avoid "pillarboxing" on modern displays
• Widescreen Enhanced: Stretches as above, and makes use of the additional space to provide wider maps, more weather data and/or additional days in the forecast
• Portrait Enhanced: Rotates the screen to a 16:9 portrait orientation and enhances the original displays by adjusting them to fit the new orientation and filling with additional data where possible

Kiosk: Immediately activates kiosk mode, which hides all settings. Exit by refreshing the page or using Ctrl-K. (Kiosk mode is similar to clicking the "Fullscreen" icon, but scales to the current browser viewport instead of activating the browser's actual "Fullscreen" mode.)

Sticky Kiosk: When enabled, stores the kiosk mode preference in local storage so the page automatically enters kiosk mode (maximizing the size of the main weather display without any settings) on subsequent visits. This feature is designed primarily for iPhone and iPad users who want to create a Home Screen app experience, since Mobile Safari doesn't support PWA installation via manifest.json or the Fullscreen API:

For iOS/iPadOS (Mobile Safari):

1. Tap the Share icon and choose Add to Home Screen
2. Adjust the name as desired and tap Add
3. Launch the newly-created Home Screen shortcut
4. Configure all settings
5. Tap to enable Sticky Kiosk
6. Make sure everything is configured exactly like you want it!
7. Tap Kiosk

For Android and Desktop browsers: The included manifest.json file enables PWA (Progressive Web App) installation. To get the best app-like experience:

1. Configure all your settings first (ignore the "Kiosk" and "Sticky Kiosk" settings)
2. Create a permalink using the "Copy Permalink" feature and manually add &kiosk=true to the end
3. Open the edited permalink URL in your browser
4. Look for browser prompts to "Install" or "Add to Home Screen" from the kiosk-enabled URL
5. The PWA will launch directly into kiosk mode (without forcing kiosk mode when accessed from the browser)

For temporary fullscreen during regular browsing, use the fullscreen button in the toolbar.

Important Notes:

• iOS/iPadOS limitations: Mobile Safari strips all URL parameters when adding to Home Screen and runs shortcuts in an isolated environment with separate storage from the main Safari app
• After creating a Home Screen app on iOS or iPadOS and activating Kiosk mode, the only way to change settings is to delete the Home Screen shortcut and recreate it
• In situations where you can edit a shortcut's URL, you can forcibly remove a "sticky" kiosk setting by adding &kiosk=false to the URL (or simply press Ctrl-K to exit kiosk mode if a keyboard is available)

Scan Line Style: Appears while scan lines are on (turn them on with the scan lines button in the toolbar, which adds a retro-style scan line effect). Overrides the "Auto" setting if you prefer a different line thickness than the one chosen for your browser and display.

Units: Switches between US and metric units. (Note that some text-based products from the National Weather Service APIs contain embedded units that are not converted.)

Enable Custom Text / Custom Text: Adds your own text to the scroll in the bottom blue bar. See Custom text scroll.

Volume is set with the speaker icon in the toolbar and is included in the permalink. Moving the volume slider while music is off starts it.

Custom text scroll

If you would like your Weatherstar to have custom scrolling text in the bottom blue bar, turn on the Enable Custom Text setting and then enter text in the Custom Text box. Then press Set.

Tip: You can have Weatherstar select randomly between several text strings on each pass through the current conditions. Use a pipe character to separate strings. Welcome to Weatherstar|Thanks for watching.

The text is shown exactly as typed; HTML tags are not interpreted.

Sharing a permalink (bookmarking)

Selected displays, the forecast city and most settings are sticky from one session to the next. However if you would like to share your exact configuration or bookmark it, open the Share tab. The permalink is shown in a read-only box and the "Copy permalink" button copies it to your clipboard. (If your browser doesn't support clipboard transfers directly the button reads "Get Permalink" and selects the link so you can copy it by hand.) The link includes your selected displays, settings and location. You can then share this link or add it to your bookmarks.

Your permalink will be very long. Here is an example for the Orlando International Airport:

https://weatherstar.netbymatt.com/?hazards=true&current-weather=true&latest-observations=true&hourly=false&hourly-graph=true&travel=false&regional-forecast=true&local-forecast=true&extended-forecast=true&almanac=true&spc-outlook=true&radar=true&future-radar=true&kiosk=false&stickyKiosk=false&customTextEnable=false&speed=1.00&viewMode=standard&scanLineMode=auto&units=us&customText=&mediaVolume=0.75&wide=false&portrait=false&enhanced=false&scanLines=false&latLonQuery=Orlando+International+Airport%2C+Orlando%2C+FL%2C+USA&latLon=%7B%22lat%22%3A28.4311%2C%22lon%22%3A-81.3091%7D

You can also build your own permalink. Settings left out of the link keep the viewer's own saved choice, or the default if they've never changed it. This lets a link change one thing, such as ?units=si, without touching anything else. Here are a few examples:

https://weatherstar.netbymatt.com/?latLonQuery=Orlando+International+Airport
https://weatherstar.netbymatt.com/?kiosk=true
https://weatherstar.netbymatt.com/?units=si
https://weatherstar.netbymatt.com/?viewMode=wide-enhanced

Permalinks created with older versions, which used keys such as travel-checkbox and settings-units-select, continue to work.

Kiosk mode

Kiosk mode can be activated by the Kiosk checkbox on the Settings tab. This will start Weatherstar in a fullscreen-like view without the play/volume/etc toolbar and scaled to fill the entire space. This does not activate the browser's fullscreen or kiosk mode. Those can only be activated by user interaction or by launching the browser with specific parameters such as --start-fullscreen or --kiosk.

When using kiosk mode (via the checkbox), there is no on-screen way to exit the fullscreen-like view of weatherstar. Press Ctrl-K or reload the page to return to the normal view (unless Sticky Kiosk is enabled). This is deliberate as a browser's kiosk mode is intended not to be exited or significantly modified. A separate full-screen icon is available in the tool bar to go full-screen on a laptop or mobile browser.

It's also possible to enter kiosk mode using a permalink. First generate a Permalink, then to the end of it add &kiosk=true. Opening this link will load all of the selected displays included in the Permalink, enter kiosk mode immediately upon loading and start playing the forecast.

Phone App

An Android app is in a closed beta test. It's nothing too special, just a wrapper for displaying the website in a browser.

You can get this functionality without an app on both Android and iOS by using the install or add to home screen feature of your browser.

iOS native app? No. I own zero Apple devices and thus have no way to develop, test, compile or verify myself to the app store. This app has been created by the community.

Music

The WeatherStar had wonderful background music from the smooth jazz and new age genres by artists of the time. Lists of the music that played are available by searching online, but it's all copyrighted music and would be difficult to provide as part of this repository.

I've used AI tools to create WeatherStar-inspired music tracks that are unencumbered by copyright and are included in this repo. To keep the size down, I've only included 4 tracks. Additional tracks are in a companion repository ws4kp-music.

If you're looking for the original music that played during forecasts TWCClassics has thorough documentation of playlists.

Music doesn't auto play

Ws4kp is muted by default, but if it was unmuted on the last visit it is coded to try and auto play music on subsequent visits. But, it's considered bad form to have a web site play music automatically on load, and I fully agree with this. Chrome and Firefox have extensive details on how and when auto play is allowed.

If the browser blocks auto play, the music button shows as off and the music starts with your first click or key press on the page. Your setting to play music is kept for next time.

Chrome seems to be more lenient on auto play and will eventually let a site auto-play music if you've visited it enough recently and manually clicked to start playing music on each visit. It also has a flag you can add to the command line when launching Chrome: chrome.exe --autoplay-policy=no-user-gesture-required. This is the best solution when using Kiosk-style setup.

If you're unable to pre-set the play state before entering kiosk mode (such as with a home dashboard implementation) you can add the query string value below to the url. Volume can be pre-set in the same way. The browser will still follow the auto play rules outlined above.

?mediaPlaying=true
?mediaVolume=0.75  // 0-1.0 as a percent

Running your own copy

Quick Start

Ensure you have Node.js 20 or later installed.

git clone https://github.com/netbymatt/ws4kp.git
cd ws4kp
npm install
npm start

Open your browser and navigate to http://localhost:8080

To use a different port, set WS4KP_PORT, for example WS4KP_PORT=3000 npm start.

Deployment Modes

WeatherStar 4000+ supports two deployment modes:

Server Deployment (Recommended)

• Includes Node.js server with caching proxy for better performance (especially when running on a local server for multiple clients)
• Server-side request deduplication and caching
• Weather API observability and logging
• Used by: npm start, DIST=1 npm start, and Dockerfile.server

Static Deployment

• Pure client-side deployment using nginx to serve static files
• All API requests are made directly from each browser to the weather services
• Browser-based caching
• Used by: static file hosting and default Dockerfile

Other methods to run Ws4kp

Development Mode (individual JS files, easier debugging)

npm start

Development Mode without proxy caching

STATIC=1 npm start

Production Mode (minified/concatenated JS, faster loading)

npm run build
DIST=1 npm start

Production Mode without proxy caching (simulates static Docker deployment)

npm run build
STATIC=1 DIST=1 npm start

For all modes, access WeatherStar by going to: http://localhost:8080/

Key Differences

Development Mode (npm start):

• Uses the individual JavaScript module files, served as they are
• Easier debugging with readable code
• Slower initial load (many HTTP requests for individual files)
• Changes to browser files (server/scripts, views) show up when you reload the page; changes to the server itself (index.mjs, proxy/, src/) need a restart

Production Mode (DIST=1 npm start):

• Uses a single minified JavaScript bundle (ws.min.js), with a source map for debugging
• Faster initial load (fewer HTTP requests, smaller file sizes)
• Optimized for performance with multiple clients
• Requires npm run build to generate optimized files

Docker Deployments

To run via Docker using a "static deployment" where everything happens in the browser (no server component, like STATIC=1):

docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp

To run via Docker using a "server deployment" with a caching proxy server for multi-client performance and enhanced observability (like npm run build; DIST=1 npm start):

docker build -f Dockerfile.server -t ws4kp-server .
docker run -p 8080:8080 ws4kp-server

To run via Docker Compose (shown here in static deployment mode):

---
services:
  ws4kp:
    image: ghcr.io/netbymatt/ws4kp
    container_name: ws4kp
    environment:
      # Each argument in the permalink URL can become an environment variable on the Docker host by adding WSQS_
      # Following the "Sharing a Permalink" example below, here are a few environment variables defined. Visit that section for a
      # more complete list of configuration options.
      - WSQS_latLonQuery=Orlando International Airport Orlando FL USA
      - WSQS_hazards=false
      - WSQS_current_weather=true
    ports:
      - 8080:8080 # change the first 8080 to meet your local network needs
    restart: unless-stopped

Serving a static app

There are several ways to deploy WeatherStar as a static app that runs entirely in the browser:

Manual static hosting (Apache, nginx, CDN, etc.): Build static distribution files for upload to any web server:

npm run build

The resulting files in /dist can be uploaded to any web server; no server-side scripting is required. Any custom scripts (server/scripts/custom*.*) are copied into dist/scripts by the build.

Docker static deployment: The default Docker image uses nginx to serve pre-built static files. See Docker Deployments.

Node.js in static mode: Use the Node.js server as a static file host without the caching proxy:

STATIC=1 npm start          # Use Express to serve development files
STATIC=1 DIST=1 npm start   # Use Express to serve (minimized) production files

Default query string parameters (environment variables)

When serving this via the built-in Express server, it's possible to define environment variables that direct the user to a default set of parameters (like the Permalink above). If a user requests the root page at http://localhost:8080/ the query string provided by environment variables will be appended to the url thus providing a default configuration.

Environment variables can be added to the command line as usual, or via a .env file which is parsed with dotenv. Both methods have the same effect.

Environment variables that are to be added to the default query string are prefixed with WSQS_ and then use the same key/value pairs generated by the Permalink above, with the - (dash) character replaced by an _ (underscore). For example, if you wanted to turn the travel forecast on, you would find travel=true in the permalink, its matching environment variable becomes WSQS_travel=true. Likewise regional-forecast=false becomes WSQS_regional_forecast=false.

When using the Docker container, these environment variables are read on container start-up to generate the static redirect HTML.

Customizing the music

WeatherStar 4000+ supports background music during forecast playback. The music behavior depends on how you deploy the application:

Express server modes (npm start, DIST=1 npm start, or Dockerfile.server)

When running with Node.js, the server generates a playlist.json file by scanning the ./server/music directory for .mp3 files. If no files are found in ./server/music, it falls back to scanning ./server/music/default/. The playlist is served dynamically at the /playlist.json endpoint.

Adding your own music: Place .mp3 files in ./server/music/

Docker server example:

docker build -f Dockerfile.server -t ws4kp-server .
docker run -p 8080:8080 -v /path/to/local/music:/app/server/music ws4kp-server

Static hosting modes (default Dockerfile, nginx, Apache, etc.)

When hosting static files, there are two scenarios:

Static Docker deployment: The build process creates a playlist.json file with default tracks, but the Docker image intentionally removes it to force browser-based directory scanning. The browser attempts to fetch playlist.json, receives a 404 response with the X-Weatherstar header, which causes it to fall back to scanning the music/ directory.

Manual static hosting: If you build and upload the files yourself (npm run build), playlist.json will contain the default tracks unless you customize ./server/music/ before building.

For directory scanning to work properly:

• Your web server must generate directory listings for the music/ path
• Your web server must set the X-Weatherstar: true header (the provided nginx configuration does this)

Adding your own music: Place .mp3 files in music/ (or bind mount to /usr/share/nginx/html/music for Docker)

Docker static example:

docker run -p 8080:8080 -v /path/to/local/music:/usr/share/nginx/html/music ghcr.io/netbymatt/ws4kp

Subdirectories will not be scanned. When WeatherStar loads in the browser, it randomizes the track order and reshuffles on each loop through the playlist.

Customization

Hooks are provided as server/scripts/custom.js and server/scripts/custom.mjs to allow customizations to your own fork of this project, without accidentally pushing your customizations back upstream to the git repository. A sample file is provided at server/scripts/custom.sample.js and should be renamed to custom.js to activate it. Recommended naming for additional files is custom-file.json which are also part of gitignore.

When using Docker:

• Images you build yourself (docker build): any server/scripts/custom*.* files are included automatically, because the build copies them into dist/scripts.
• The published static image (ghcr.io/netbymatt/ws4kp): mount your files into /usr/share/nginx/html/scripts/, for example custom.js or custom.mjs.
• Server deployment: to change your files without rebuilding the image, mount them into /app/server/scripts/.

Issue reporting and feature requests

Please do not report issues with api.weather.gov being down. I've also observed that the API can go down on a regional basis (based on NWS office locations). This means that you may have problems getting data for, say, Chicago right now, but Dallas and others are working just fine.

Before reporting an issue or requesting a feature please consider that this is not intended to be a perfect recreation of the WeatherStar 4000, it's a best effort that fits within what's available from the API and within a web browser.

Note: not all units are converted to metric, if selected. Some text-based products such as warnings are simple text strings provided from the national weather service and thus have baked-in units such as "gusts up to 60 mph." These values will not be converted.

The full moon icon is broken

This is a known problem with the Ws4kp as it ages. It was a problem with the actual Weatherstar hardware as well.

Community Notes

Thanks to the WeatherStar+ community for providing these discussions to further extend your retro forecasts!

• Stream as FFMPEG
• Weather like it's 1999 Raspberry pi, streaming, music and CRT all combined into a complete solution.
• ws4channels A Dockerized Node.js application to stream WeatherStar 4000 data into Channels DVR using Puppeteer and FFmpeg.
• SSL Certificates Discussion about how to host with an SSL certificate (enables geolocation).
• Changing playlists Possible ways to automatically change the playlist on a schedule.
• Customize Travel Forecast Cities
• Apple iOS/TV application

Related Projects

Not retro enough? Try the Weatherstar 3000+

Use

Linking directly to the live web site at https://weatherstar.netbymatt.com is encouraged. As is using the live site for digital signage, home dashboards, streaming and public display. Please note the disclaimer below.

Acknowledgements

This project is based on the work of Mike Battaglia. It was forked from his work in August 2020.

• Mike Battaglia for the original project and all of the code which draws the weather displays. This code remains largely intact and was a huge amount of work to get exactly right. He's also responsible for all of the background graphics including the maps used in the application.
• The team at TWCClassics for several resources.
  • A font set used on the original WeatherStar 4000
  • Icon sets
  • Countless photos and videos of WeatherStar 4000 forecasts used as references.
• The growing list of contributors to this repository

Disclaimer

This web site should NOT be used in life threatening weather situations, or be relied on to inform the public of such situations. The Internet is an unreliable network subject to server and network outages and by nature is not suitable for such mission critical use. If you require such access to NWS data, please consider one of their subscription services. The authors of this web site shall not be held liable in the event of injury, death or property damage that occur as a result of disregarding this warning.

The WeatherSTAR 4000 unit and technology is owned by The Weather Channel. This web site is a free, non-profit work by fans. All of the back ground graphics of this web site were created from scratch. The icons were created by Charles Abel and Nick Smith (http://twcclassics.com/downloads/icons.html) as well as by Malek Masoud. The fonts were originally created by Nick Smith (http://twcclassics.com/downloads/fonts.html).