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

### Environment Variables

Configure ports and services via environment variables:

```bash
# Default values
PORT=3000              # Main streaming server port
WS4KP_PORT=8080       # WS4KP weather service port
MUSIC_PATH=/music     # Path to music files

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

Or use a `.env` file with docker-compose:
```env
PORT=8000
WS4KP_PORT=9090
```

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

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

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

```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 (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