Initial Commit
This commit is contained in:
175
README.md
Normal file
175
README.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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 the Weatherscan music collection (~500MB).
|
||||
|
||||
## 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)
|
||||
|
||||
**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)
|
||||
- `showLatestObservations`: Real-time data from nearby stations
|
||||
- `showRegionalForecast`: Regional forecast for surrounding areas
|
||||
- **Specialized sections** (default: false):
|
||||
- `showTravel`: Travel forecast for major destinations
|
||||
- `showMarineForecast`: Marine/coastal forecast
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
yarn install
|
||||
|
||||
# Run locally (requires Chrome and FFmpeg)
|
||||
yarn start
|
||||
```
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user