grown/QUICK_START.md

# RTSP to HLS Streaming - Quick Start Guide

## Installation (5 minutes)

### 1. Install FFmpeg
```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg
```

### 2. Install Dependencies
```bash
npm install
```

### 3. Start Development Server
```bash
npm run dev
```

Visit `http://localhost:5173`

## Usage

1. Enter a **Stream ID** (e.g., "camera-1")
2. Enter an **RTSP URL** (e.g., "rtsp://192.168.1.100:554/stream")
3. Click **Start Stream**
4. Watch video play in the browser
5. Click **Stop Stream** to terminate

## What Was Set Up

### Backend Components
- **`src/lib/server/streaming.ts`** - FFmpeg process manager
  - Spawns FFmpeg to convert RTSP → HLS
  - Manages stream lifecycle
  - Handles errors and cleanup

- **`src/routes/api/stream/+server.ts`** - REST API
  - `/api/stream` POST endpoint
  - Actions: start, stop, status, list

### Frontend Components
- **`src/lib/components/RTSPVideoPlayer.svelte`** - Video player
  - HLS.js library for playback
  - Input forms for Stream ID and RTSP URL
  - Stream controls and status display

### Static Files
- **`static/hls/`** - HLS segments (auto-created)
  - Stores `.m3u8` playlists
  - Stores `.ts` segment files
  - Automatically cleaned up by FFmpeg

## How It Works

```
RTSP Stream (Camera)
        ↓
    FFmpeg (spawned process on server)
    Converts to HLS segments
        ↓
    HLS.js (browser)
    Parses playlist and segments
        ↓
    HTML5 Video Player
    Displays video in browser
```

## API Examples

### Start Stream
```bash
curl -X POST http://localhost:5173/api/stream \
  -H "Content-Type: application/json" \
  -d '{
    "action": "start",
    "streamId": "camera-1",
    "rtspUrl": "rtsp://192.168.1.100:554/stream"
  }'
```

### Stop Stream
```bash
curl -X POST http://localhost:5173/api/stream \
  -H "Content-Type: application/json" \
  -d '{
    "action": "stop",
    "streamId": "camera-1"
  }'
```

### Get Status
```bash
curl -X POST http://localhost:5173/api/stream \
  -H "Content-Type: application/json" \
  -d '{"action": "status", "streamId": "camera-1"}'
```

### List All Streams
```bash
curl -X POST http://localhost:5173/api/stream \
  -H "Content-Type: application/json" \
  -d '{"action": "list"}'
```

## Common RTSP URLs

| Camera Brand | URL Pattern |
|---|---|
| Hikvision | `rtsp://admin:password@IP:554/stream` |
| Dahua | `rtsp://admin:password@IP:554/live` |
| Generic | `rtsp://user:password@IP:554/stream` |
| Reolink | `rtsp://user:password@IP:554/h264Preview_01_main` |
| Ubiquiti | `rtsp://user:password@IP:554/live1` |

## Troubleshooting

| Problem | Solution |
|---|---|
| FFmpeg not found | Install FFmpeg and add to PATH |
| Stream won't connect | Verify RTSP URL with VLC first |
| No video playback | Check browser console for HLS.js errors |
| High CPU usage | Use `-preset ultrafast` in streaming.ts |
| High latency | Reduce `-hls_time` from 10 to 2-5 seconds |

## File Structure

```
grown/
├── src/
│   ├── lib/
│   │   ├── server/
│   │   │   └── streaming.ts          ← FFmpeg manager
│   │   └── components/
│   │       └── RTSPVideoPlayer.svelte ← Video player UI
│   └── routes/
│       ├── +page.svelte              ← Home page
│       └── api/stream/
│           └── +server.ts            ← Stream API
├── static/
│   └── hls/                          ← HLS segments (auto-created)
├── package.json
├── svelte.config.js
└── vite.config.ts
```

## Configuration

Edit `src/lib/server/streaming.ts` to adjust FFmpeg parameters:

### Lower Latency (for real-time apps)
```typescript
'-hls_time', '2',        // 2-second segments
'-hls_list_size', '5',   // Keep 5 segments
'-preset', 'ultrafast',  // Fastest encoding
```

### Higher Quality
```typescript
'-crf', '23',            // Better quality
'-b:v', '2500k',         // Higher video bitrate
'-b:a', '192k',          // Higher audio bitrate
```

### GPU Acceleration (NVIDIA)
```typescript
'-c:v', 'h264_nvenc',    // GPU encoder
'-preset', 'fast',       // fast, medium, slow
```

## Testing

### Test with a Public RTSP Stream
```
rtsp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mov
```

### Test with VLC Player
```bash
# Verify RTSP URL works before using in the app
vlc rtsp://192.168.1.100:554/stream
```

## Next Steps

1. **Deploy**: Use Docker or your preferred hosting
2. **Secure**: Add authentication to `/api/stream` endpoints
3. **Monitor**: Log stream statistics and errors
4. **Scale**: Implement load balancing for multiple cameras
5. **Optimize**: Adjust FFmpeg parameters for your use case

## Documentation

- Full setup guide: `RTSP_STREAMING_SETUP.md`
- FFmpeg docs: https://ffmpeg.org/documentation.html
- HLS.js docs: https://github.com/video-dev/hls.js/wiki
- SvelteKit docs: https://kit.svelte.dev

## Browser Support

✓ Chrome/Edge (HLS.js)
✓ Firefox (HLS.js)
✓ Safari (Native HLS)
✓ Mobile browsers (Full support)

## Need Help?

1. Check the browser console for errors
2. Check terminal output for FFmpeg logs
3. Verify RTSP URL is correct
4. Ensure FFmpeg is installed and in PATH
5. Check network connectivity to camera

---

**You're all set!** Start the dev server and visit `http://localhost:5173`