Add initial implementation of StreamShot with snapshot capture feature and UI

README.md

@@ -0,0 +1,66 @@
+# StreamShot 📸
+
+Capture high-quality JPEG snapshots from any YouTube livestream via a simple web UI or API.
+(yes it's a yt-dlp wrapper)
+
+## Features
+
+- **Stream Extraction**: Uses `yt-dlp` to find the best available stream URL.
+- **Frame Capture**: Uses OpenCV to grab a single frame directly from the video stream.
+- **Web UI**: A clean, Tailwind CSS-powered interface for quick captures.
+- **API Access**: Returns snapshots as base64-encoded buffers in a JSON object.
+
+## API Usage
+
+### Endpoint
+`POST /snapshot`
+
+### Request Body
+```json
+{
+  "url": "https://www.youtube.com/watch?v=..."
+}
+```
+
+### Response
+```json
+{
+  "message": "done",
+  "buffer": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAg..."
+}
+```
+
+### CLI Example (Save to File)
+To capture a snapshot and save it directly to a file using `curl`, `jq`, and `base64`:
+
+```bash
+curl -X POST \
+  https://shsf-api.reversed.dev/api/exec/16/cca815a2-216d-4362-b6f5-1d57ac9f088d/snapshot \
+  -H "Content-Type: application/json" \
+  -d '{"url": "YOUR_YOUTUBE_URL_HERE"}' \
+  | jq -r .buffer | base64 -d > snapshot.jpg
+```
+
+## Local Development
+
+### Prerequisites
+- Python 3.14 (tested)
+- `opencv-python`
+- `yt-dlp`
+- `numpy`
+
+### Installation
+```bash
+pip install -r requirements.txt
+```
+
+### Running Locally
+You can test the capture logic directly:
+```bash
+python main.py
+```
+
+## Tech Stack
+- **Backend**: Python (yt-dlp, OpenCV)
+- **Frontend**: HTML5, Tailwind CSS, JavaScript (Fetch API)
+- **Deployment**: Shsf (Serverless)