ws4kp-to-hls/README.md

# 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)

```bash
# 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

```bash
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 and processing the Weatherscan music collection (~500MB, processed to VBR q6 quality with normalization).

## Usage

### Stream any webpage

```bash
# 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:

```bash
# 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

```bash
# 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 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