Webpage to HLS Stream

Simple Dockerized service that converts any webpage to a live video stream using Puppeteer and FFmpeg. Streams use MPEGTS format for reliable HTTP delivery. 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 (if port is exposed)

Environment Variables

Configure ports and services via environment variables:

# Default values
PORT=3000                    # Main streaming server port
WS4KP_EXTERNAL_PORT=8080    # External port for WS4KP interface (optional)
MUSIC_PATH=/music           # Path to music files
LOG_WS4KP_URL=false         # When true, logs full ws4kp URL instead of just request path
TZ=America/New_York         # Timezone for weather display (default: America/New_York)

# Example with custom ports
PORT=8000 WS4KP_EXTERNAL_PORT=9090 docker-compose up

# Run with full ws4kp URL logging
LOG_WS4KP_URL=true docker-compose up

# Run with different timezone (e.g., Los Angeles)
TZ=America/Los_Angeles docker-compose up

# Run without exposing WS4KP externally (only accessible internally to the streaming app)
# Comment out the WS4KP port line in docker-compose.yml

Or use a .env file with docker-compose:

PORT=8000
WS4KP_EXTERNAL_PORT=9090
LOG_WS4KP_URL=true
TZ=America/Chicago

Timezone Note: The TZ environment variable controls what time is displayed in the weather stream. Use standard IANA timezone identifiers (e.g., America/New_York, America/Chicago, America/Los_Angeles, Europe/London, Asia/Tokyo). This should match the timezone of the location you're streaming weather for.

Note: The WS4KP weather service runs internally on port 8080 inside the container and is always accessible to the streaming app. The WS4KP_EXTERNAL_PORT controls whether it's exposed externally. If you don't need direct access to the WS4KP interface, you can comment out the WS4KP port mapping in docker-compose.yml to keep it internal-only.

Persistent Geocoding Cache

Geocoding results are cached in the ./cache directory. When using docker-compose, this directory is automatically mounted to persist between container restarts. If using Docker directly, mount the cache volume to persist data:

docker run -p 3000:3000 -p 8080:8080 -v $(pwd)/cache:/streaming-app/cache ghcr.io/sethwv/ws4kp-to-hls:latest

Using Docker directly

# With WS4KP interface exposed
docker run -p 3000:3000 -p 8080:8080 ghcr.io/sethwv/ws4kp-to-hls:latest

# Without exposing WS4KP interface (internal only)
docker run -p 3000:3000 ghcr.io/sethwv/ws4kp-to-hls:latest

Note: Initial build takes an additional ~90 seconds due to downloading and processing the Weatherscan music collection (~500MB, processed to VBR q6 quality with normalization).

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. Geocoding results are cached in the ./cache directory to improve performance and reduce API calls.

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)
• refreshInterval (optional): Page refresh interval in minutes (default: 90)

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)
• refreshInterval (optional): Page refresh interval in minutes (default: 90)
• 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 MPEGTS stream (H.264 video, AAC audio for weather)
4. For weather streams: background music is shuffled and played from the Weatherscan collection
5. The MPEGTS stream is piped directly to the HTTP response
6. City names are automatically geocoded to coordinates via OpenStreetMap's Nominatim API (results are cached locally for performance)

Features

• Configurable Ports: Both streaming server and WS4KP service ports are configurable via environment variables
• Geocoding Cache: City geocoding results are cached on the filesystem to reduce API calls and improve response times
• Background Music: Weather streams include shuffled Weatherscan music collection
• Multi-platform: Docker images for AMD64 and ARM64 architectures
• Automatic Geocoding: City names are converted to coordinates automatically
• Flexible Display Options: Control which weather forecast sections to show/hide