Webpage to HLS Stream

Simple Dockerized service that converts any webpage to an HLS stream using Puppeteer and FFmpeg. Includes built-in ws4kp weather display.

Docker Image: ghcr.io/sethwv/ws4kp-to-hls:latest (multi-platform: AMD64, ARM64)

Quick Start

Using Docker Compose (recommended)

# Build and start
docker-compose up --build

# Or pull pre-built image
docker-compose pull
docker-compose up

# The service runs on http://localhost:3000
# ws4kp interface available at http://localhost:8080

Using Docker directly

docker run -p 3000:3000 -p 8080:8080 ghcr.io/sethwv/ws4kp-to-hls:latest

Note: Initial build takes an additional ~90 seconds due to downloading the Weatherscan music collection (~500MB).

Usage

Stream any webpage

# Basic usage
http://localhost:3000/stream?url=http://example.com

# With custom dimensions and framerate
http://localhost:3000/stream?url=http://example.com&width=1280&height=720&fps=25

Stream weather (ws4kp)

The service includes a built-in ws4kp weather display with automatic geocoding and background music:

# Default location (Toronto, ON)
http://localhost:3000/weather

# Custom location (automatically geocoded via OpenStreetMap)
http://localhost:3000/weather?city=New+York,NY,USA
http://localhost:3000/weather?city=London,UK
http://localhost:3000/weather?city=Tokyo,Japan

# With imperial units (Fahrenheit, mph, miles, inHg)
http://localhost:3000/weather?city=Miami,FL,USA&units=imperial

# With 12-hour time format
http://localhost:3000/weather?city=New+York,NY,USA&units=imperial&timeFormat=12h

# Show only current weather and radar (hide other forecasts)
http://localhost:3000/weather?city=Miami,FL,USA&showHourly=false&showExtendedForecast=false

# Minimal display (just current weather)
http://localhost:3000/weather?city=Toronto,ON,Canada&showHourly=false&showRadar=false&showExtendedForecast=false&showLocalForecast=false

# With custom resolution
http://localhost:3000/weather?city=Miami,FL,USA&width=1280&height=720&fps=25

# Hide the ws4kp logo
http://localhost:3000/weather?city=Toronto,ON,Canada&hideLogo=true

City Format: Use City,State,Country format for best accuracy (e.g., Toronto,ON,Canada or Miami,FL,USA). The service automatically geocodes the city using OpenStreetMap's Nominatim API and falls back to Toronto coordinates if geocoding fails.

Units: Use units=metric (default) for Celsius/kph/km/mb or units=imperial for Fahrenheit/mph/miles/inHg.

Time Format: Use timeFormat=24h (default) for 24-hour time or timeFormat=12h for 12-hour AM/PM format.

Forecast Sections: Control which sections are displayed using show* parameters (set to true or false). See Parameters section below for full list.

Background Music: The weather endpoint includes shuffled background music from the Weatherscan collection, with tracks automatically changing when one ends.

Logo Control: Use hideLogo=true to hide the ws4kp Logo3.png image from the stream.

Consume with FFmpeg

# Play the stream
ffplay "http://localhost:3000/stream?url=http://example.com"

# Save to file
ffmpeg -i "http://localhost:3000/stream?url=http://example.com" -c copy output.mp4

# Re-stream to RTMP
ffmpeg -i "http://localhost:3000/stream?url=http://example.com" \
  -c:v copy -f flv rtmp://your-server/live/stream

Parameters

Stream endpoint (/stream):

• url (required): The webpage URL to capture
• width (optional): Video width in pixels (default: 1920)
• height (optional): Video height in pixels (default: 1080)
• fps (optional): Frames per second (default: 30)
• hideLogo (optional): Set to true to hide Logo3.png image (default: false)

Weather endpoint (/weather):

• city (optional): City name in City,State,Country format (default: Toronto,ON,Canada)
  • Examples: Toronto,ON,Canada, New+York,NY,USA, London,UK
  • Automatically geocoded via OpenStreetMap Nominatim
• units (optional): Unit system - metric or imperial (default: metric)
  • metric: Celsius, kph, km, mb
  • imperial: Fahrenheit, mph, miles, inHg
• timeFormat (optional): Time format - 12h or 24h (default: 24h)
• width (optional): Video width in pixels (default: 1920)
• height (optional): Video height in pixels (default: 1080)
• fps (optional): Frames per second (default: 30)
• hideLogo (optional): Set to true to hide ws4kp Logo3.png image (default: false)
• Forecast Section Toggles (all optional, use true or false):
  • Commonly used sections (default: true):
    • showHazards: Weather alerts and hazards
    • showCurrent: Current weather conditions
    • showHourly: Hourly forecast
    • showHourlyGraph: Hourly forecast graph
    • showLocalForecast: Local forecast
    • showExtendedForecast: Extended forecast (7-day)
    • showRadar: Weather radar
    • showAQI: Air Quality Index
    • showAlmanac: Weather almanac (historical data, records)
  • Specialized sections (default: false):
    • showLatestObservations: Real-time data from nearby stations
    • showRegionalForecast: Regional forecast for surrounding areas
    • showTravel: Travel forecast for major destinations
    • showMarineForecast: Marine/coastal forecast
  • Note: Sections disabled by default (showLatestObservations, showRegionalForecast, showTravel, showMarineForecast) may display incorrect or incomplete information for locations outside the United States, as they rely on NOAA data sources.

How It Works

1. Puppeteer opens the webpage in headless Chrome/Chromium
2. Screenshots are captured at the specified FPS using a sequential loop with backpressure handling
3. FFmpeg encodes the screenshots into an HLS stream (H.264 video, AAC audio for weather)
4. For weather streams: background music is shuffled and played from the Weatherscan collection
5. The HLS stream is piped directly to the HTTP response
6. City names are automatically geocoded to coordinates via OpenStreetMap's Nominatim API

Development

# Install dependencies
yarn install

# Run locally (requires Chrome and FFmpeg)
yarn start

Health Check

curl http://localhost:3000/health

Notes

• The stream continues indefinitely until the client disconnects
• Each request creates a new browser instance
• Memory usage scales with the number of concurrent streams
• Weather streams include automatic geocoding (adds ~200-500ms initial latency)
• Background music for weather streams is shuffled from a collection of Weatherscan tracks
• Multi-platform Docker image available for AMD64 and ARM64 architectures

License

MIT