# GStreamerVideoMetrics

**Repository Path**: techwolf/GStreamerVideoMetrics

## Basic Information

- **Project Name**: GStreamerVideoMetrics
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-11
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GStreamerVideoMetrics
# 📡 RTMP Video Monitoring with GStreamer, FFmpeg, Prometheus & Grafana

This project provides a full-stack solution to ingest RTMP video feeds, convert them to JPEG using GStreamer, monitor live stream metadata using FFmpeg, and export observability data using Prometheus. It is optimized for Docker-based deployments and ARM-compatible systems.

---

## 🗂️ Project Structure
```
.
├── gstreamer-jpeg/
│   ├── Dockerfile                 # GStreamer JPEG capture & metrics exporter
│   └── gstreamer_app.py           # RTMP to JPEG processor with Prometheus metrics
├── ffmpeg-probe/
│   ├── Dockerfile                 # Container to probe RTMP feeds using FFmpeg
│   └── ffmpeg_probe_exporter.py  # Prometheus exporter for video metadata
├── nginx-rtmp/
│   ├── nginx.conf                 # RTMP + HLS config
│   └── html/
│       └── index.html             # Web player (HLS.js)
├── prometheus/
│   └── prometheus.yml            # Prometheus scrape & remote_write config
├── docker-compose.yml            # Service orchestration
└── README.md                     # This file
```
---

## 📦 Components

### 🖼️ `gstreamer-jpeg/`
- Ingests RTMP stream using GStreamer.
- Converts to JPEG frames.
- Exposes Prometheus metrics:
  - Frame rate
  - Dropped frames
  - JPEG size, width, height, quality
  - CPU/memory usage
  - RTMP connectivity
  - Pipeline health

### 🎞️ `ffmpeg-probe/`
- Probes RTMP streams every 30 seconds using `ffprobe`.
- Exports:
  - Stream availability
  - Frame rate
  - Width / Height
  - Video & audio codec presence

### 🌐 `nginx-rtmp/`
- RTMP ingest and HLS delivery via NGINX.
- Embedded HLS player using [HLS.js](https://github.com/video-dev/hls.js).

### 📊 `prometheus/`
- Scrapes GStreamer and FFmpeg exporters.
- Optional remote_write to Grafana Cloud.

---

## ⚙️ Configuration

### Environment Variables (set in `docker-compose.yml`)

```yaml
environment:
  - RTMP_STREAMS=rtmp://nginx-rtmp:1935/live/stream
  - JPEG_FPS=15
  - JPEG_QUALITY=90
  - PROBE_INTERVAL_SECONDS=30
```

```remote_write:
  - url: https://prometheus-prod-<region>.grafana.net/api/prom/push
    basic_auth:
      username: <your-instance-id>
      password: <your-api-key>
```


## 🚀 Running the Stack

```
docker compose up --build
```

	•	GStreamer metrics: http://localhost:8000/metrics
	•	FFmpeg probe metrics: http://localhost:8001/metrics
	•	HLS video player: http://localhost:8080/

 
⸻

📈 Example Prometheus Metrics
	•	gstreamer_jpeg_fps
	•	gstreamer_pipeline_up
	•	gstreamer_jpeg_size_bytes
	•	gstreamer_rtmp_connected
	•	ffmpeg_stream_up
	•	ffmpeg_stream_frame_width
	•	ffmpeg_stream_video_codec{codec="h264"}

 🔍 Troubleshooting

 Issue
Fix
ffmpeg_stream_up is 0
Ensure the RTMP stream is active
No JPEGs generated
RTMP feed is down or misconfigured
Player doesn’t load video
Use supported browsers (Firefox/Chrome), check MIME and CORS headers
Cross-origin error
Confirm nginx.conf includes proper add_header for Access-Control-Allow-Origin

🖥️ Embedding HLS Player

The HLS stream is accessible at /hls/playlist.m3u8. The default index.html uses HLS.js and can be embedded as:

```html
<iframe src="/index.html" width="100%" height="500" style="border: none;"></iframe>
```


🔄 Extending
	•	Add multiple RTMP feeds by comma-separating in RTMP_STREAMS
	•	Push metrics to Grafana Cloud
	•	Add alerting rules based on stream_up == 0
	•	Customize GStreamer pipeline with filters, overlays, etc.


 ✨ Credits

Built with:
	•	GStreamer
	•	FFmpeg
	•	Prometheus
	•	Grafana
	•	NGINX + RTMP Module