stream-recorder
Generischer Stream-Recorder für RTMP, HLS, HTTP-Audio und weitere Formate
## Beschreibung
**stream-recorder** ist ein Bash-basiertes Tool zur automatisierten Aufzeichnung von Streams. Es unterstützt verschiedene Stream-Typen und kann sowohl interaktiv als auch vollautomatisch genutzt werden.
Jeder Stream wird als eigene Job-Datei definiert. Aufnahmezeiten werden direkt in der Job-Datei festgelegt - kein Cron-Wissen nötig. Ein systemd-Timer übernimmt die Zeitsteuerung automatisch.
## Funktionen
- **Mehrere Stream-Typen:** RTMP, RTMPS, HLS (m3u8), MP3, AAC, OGG, FLAC und generische HTTP-Streams
- **Job-basiert:** Ein Stream = eine Job-Datei, inklusive Zeitplanung
- **Automatische Zeitplanung:** Aufnahmezeiten direkt in der Job-Datei konfigurieren
- **Schnellaufnahme:** Interaktiver Modus für spontane Aufnahmen (`quick`)
- **Automatische Erkennung:** Stream-Typ und Dateiformat werden anhand der URL erkannt
- **Auto-Reconnect:** Automatische Wiederverbindung bei Verbindungsabbrüchen
- **NTFY-Benachrichtigungen:** Optionale Push-Nachrichten bei Start, Stop und Fehlern
- **Logging:** Strukturiertes Logging mit konfigurierbarem Log-Level und Live-Ansicht
- **Prozessverwaltung:** Start, Stop und Status einzelner oder aller Aufnahmen
- **Einfache Installation:** Install/Uninstall-Scripts für den systemd-Service
## Voraussetzungen
- **Betriebssystem:** Linux (getestet unter Ubuntu/Debian)
- **Bash:** Version 4.0 oder neuer
- **ffmpeg:** Muss installiert sein (`sudo apt install ffmpeg`)
- **curl:** Optional, nur für NTFY-Benachrichtigungen (`sudo apt install curl`)
## Installation
```bash
# Repository klonen
git clone https://git.techniverse.net/scriptos/stream-recorder.git /opt/stream-recorder
cd /opt/stream-recorder
# Konfiguration anpassen
nano config/stream-recorder.conf
# Scheduler installieren (systemd-Timer)
sudo install/install.sh
```
Das Install-Script macht das Hauptscript ausführbar, installiert fehlende Abhängigkeiten (ffmpeg) und richtet den systemd-Timer ein, der jede Minute die Zeitpläne prüft.
### Deinstallation
```bash
sudo install/uninstall.sh
```
Entfernt den systemd-Timer. Job-Dateien, Konfiguration und Aufnahmen bleiben erhalten.
## Konfiguration
Die Konfigurationsdatei liegt unter `config/stream-recorder.conf`:
| Parameter | Standard | Beschreibung |
|-----------------|------------------------------|---------------------------------------|
| `DOWNLOAD_PATH` | `/home/downloads/recordings` | Basis-Verzeichnis für Aufnahmen |
| `LOG_DIR` | `/var/log/stream-recorder` | Log-Verzeichnis |
| `LOG_LEVEL` | `INFO` | Log-Level: DEBUG, INFO, WARN, ERROR |
| `PID_DIR` | `/tmp/stream-recorder` | PID-Dateien für laufende Aufnahmen |
| `MAX_RETRIES` | `0` | Wiederholungsversuche (0 = unbegrenzt)|
| `RETRY_DELAY` | `5` | Wartezeit zwischen Versuchen (Sek.) |
| `NTFY_URL` | (leer) | NTFY Server-URL inkl. Topic |
| `NTFY_TOKEN` | (leer) | NTFY Access-Token (optional) |
| `NTFY_EVENTS` | `error` | Benachrichtigungs-Events (s. unten) |
| `PLIK_URL` | (leer) | Plik Server-URL |
| `PLIK_API_KEY` | (leer) | Plik API-Key (optional) |
| `PLIK_TTL` | `30d` | Gültigkeitsdauer der Uploads |
## Job-Dateien
Jeder Stream wird durch eine `.job`-Datei im `jobs/`-Verzeichnis definiert. Vorlagen befinden sich unter `jobs/templates/`.
### Job erstellen
**Interaktiv (empfohlen):**
```bash
./stream-recorder.sh create
```
Das Script fragt Schritt für Schritt nach URL, Name, Typ, Dauer, Zeitplan und Plik-Upload und erstellt die Job-Datei automatisch.
**Manuell (aus Vorlage):**
```bash
# Vorlage kopieren
cp jobs/templates/example-rtmp.job.dist jobs/mein-stream.job
# Anpassen
nano jobs/mein-stream.job
```
### Stream-Parameter
| Parameter | Pflicht | Beschreibung |
|--------------------|---------|-----------------------------------------------------|
| `STREAM_NAME` | Ja | Name des Streams (wird für Dateinamen verwendet) |
| `STREAM_URL` | Ja | URL des Streams |
| `STREAM_TYPE` | Nein | `auto`, `rtmp`, `hls`, `mp3`, `aac`, `ogg`, `flac` |
| `OUTPUT_FORMAT` | Nein | Dateiendung (z.B. `mp4`, `mp3`) - sonst automatisch |
| `MAX_DURATION` | Nein | Maximale Dauer in Sekunden (leer = unbegrenzt) |
| `EXTRA_FFMPEG_ARGS`| Nein | Zusätzliche ffmpeg-Parameter |
| `PLIK_ENABLED` | Nein | Plik-Upload aktivieren (`true`/`false`) |
### Zeitplan-Parameter
| Parameter | Standard | Beschreibung |
|--------------------|----------|-------------------------------------------------|
| `SCHEDULE_ENABLED` | `false` | Zeitplan aktivieren (`true`/`false`) |
| `SCHEDULE_DAYS` | `*` | Aufnahmetage (siehe Formate unten) |
| `SCHEDULE_START` | (leer) | Startzeit im Format `HH:MM` |
| `SCHEDULE_STOP` | (leer) | Endzeit im Format `HH:MM` (leer = kein Auto-Stop)|
**Tage-Formate:**
| Format | Bedeutung |
|--------------|----------------------------|
| `*` | Täglich |
| `Mo-Fr` | Montag bis Freitag |
| `Sa,So` | Samstag und Sonntag |
| `Mo,Mi,Fr` | Einzelne Tage |
| `Mo-Fr,So` | Kombiniert |
Die Tagesangaben funktionieren auf Deutsch (Mo, Di, Mi, Do, Fr, Sa, So) und Englisch (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
### Beispiel: Tägliche RTMP-Aufnahme von 20:00 bis 22:00
```bash
STREAM_NAME="Abend-Livestream"
STREAM_URL="rtmp://example.com/live/stream-key"
SCHEDULE_ENABLED=true
SCHEDULE_DAYS="*"
SCHEDULE_START="20:00"
SCHEDULE_STOP="22:00"
```
### Beispiel: Radio-Mitschnitt werktags um 18:00, 1 Stunde
```bash
STREAM_NAME="Mein-Radiosender"
STREAM_URL="https://example.com/stream.mp3"
MAX_DURATION="3600"
SCHEDULE_ENABLED=true
SCHEDULE_DAYS="Mo-Fr"
SCHEDULE_START="18:00"
```
## Verwendung
### Befehle
```bash
# Einzelnen Stream aufzeichnen
./stream-recorder.sh record mein-stream
# Alle Jobs gleichzeitig aufzeichnen
./stream-recorder.sh record-all
# Neuen Job interaktiv erstellen
./stream-recorder.sh create
# Interaktive Schnellaufnahme (URL direkt eingeben)
./stream-recorder.sh quick
# Aufnahme mit ausführlicher Ausgabe
./stream-recorder.sh -V record mein-stream
# Verfügbare Jobs und Zeitpläne anzeigen
./stream-recorder.sh list
# Laufende Aufnahmen und Scheduler-Status anzeigen
./stream-recorder.sh status
# Log-Ausgabe live verfolgen
./stream-recorder.sh logs
# Einzelne Aufnahme stoppen
./stream-recorder.sh stop mein-stream
# Alle Aufnahmen stoppen
./stream-recorder.sh stop-all
```
### Schnellaufnahme
Mit dem `quick`-Befehl kann ein beliebiger Stream ohne Job-Datei aufgezeichnet werden:
```bash
./stream-recorder.sh quick
```
Das Script fragt interaktiv nach URL, Name, Typ und Dauer. Die Dauer kann in verschiedenen Formaten angegeben werden: `3600` (Sekunden), `1h`, `30m`, `1h30m`.
### Job-Angabe
Der `record`-Befehl akzeptiert verschiedene Formate:
```bash
./stream-recorder.sh record jobs/mein-stream.job # Vollständiger Pfad
./stream-recorder.sh record mein-stream.job # Nur Dateiname
./stream-recorder.sh record mein-stream # Nur Job-Name
```
## Zeitplanung
Die Zeitplanung wird direkt in der Job-Datei konfiguriert - kein Cron nötig.
### So funktioniert's
1. **Job-Datei erstellen** und `SCHEDULE_*`-Parameter setzen
2. **Scheduler installieren** mit `sudo install/install.sh` (einmalig)
3. Der systemd-Timer prüft **jede Minute** alle Jobs und startet/stoppt Aufnahmen automatisch
### Verhalten
- **Start + Stop gesetzt:** Aufnahme läuft im angegebenen Zeitfenster
- **Nur Start gesetzt:** Aufnahme startet zur angegebenen Zeit, läuft bis `MAX_DURATION` oder manueller Stop
- **Manuell gestartete Aufnahmen** werden vom Scheduler nicht beeinflusst
- **Nach Neustart** des Servers erkennt der Scheduler automatisch, welche Aufnahmen laufen sollten
### NTFY-Benachrichtigungen
Push-Nachrichten via [ntfy](https://ntfy.sh) (selbst gehostet oder öffentlich). In der Konfigurationsdatei:
```bash
NTFY_URL="https://ntfy.sh/mein-stream-topic"
NTFY_TOKEN="" # Optional, nur bei geschützten Topics
NTFY_EVENTS="start,stop,error" # Kommasepariert: start, stop, error
```
| Event | Auslöser | Priorität |
|---------|-----------------------------------------------------|-----------|
| `start` | Aufnahme wurde gestartet | Normal |
| `stop` | Aufnahme wurde beendet (regulär oder manuell) | Normal |
| `error` | Verbindung verloren oder max. Versuche erreicht | Hoch |
| `upload` | Datei wurde auf Plik hochgeladen (mit Download-Link)| Normal |
## Auto-Reconnect
Bei Verbindungsabbrüchen versucht das Script automatisch, die Verbindung wiederherzustellen:
- `MAX_RETRIES=0` - Unbegrenzte Wiederverbindungsversuche (Standard)
- `MAX_RETRIES=5` - Maximal 5 Versuche, danach Abbruch mit NTFY-Benachrichtigung
- `RETRY_DELAY=5` - 5 Sekunden Wartezeit zwischen den Versuchen
Bei jedem Reconnect wird eine neue Datei mit aktuellem Zeitstempel erzeugt.
## Plik-Upload
Fertige Aufnahmen können automatisch auf einen [Plik](https://github.com/root-gg/plik)-Server hochgeladen werden.
### Einrichtung
1. **Plik-Server konfigurieren** in `config/stream-recorder.conf`:
```bash
PLIK_URL="https://plik.example.com"
PLIK_API_KEY="" # Optional, nur bei geschützten Servern
PLIK_TTL="30d" # Gültigkeitsdauer: 30d, 24h, oder Sekunden
```
2. **Pro Job aktivieren** in der Job-Datei:
```bash
PLIK_ENABLED=true
```
### Verhalten
- Der Upload erfolgt automatisch nach jeder regulär abgeschlossenen Aufnahme
- Bei manuellem Stop oder Verbindungsabbruch wird kein Upload ausgeführt
- Der Download-Link wird im Log ausgegeben
- Optional wird der Link per NTFY-Benachrichtigung gesendet (Event: `upload`)
### NTFY + Plik
Um den Download-Link per Push-Nachricht zu erhalten:
```bash
NTFY_EVENTS="start,stop,error,upload"
```
## Logging
Logs werden nach `LOG_DIR` geschrieben (Standard: `/var/log/stream-recorder/`):
- `stream-recorder.log` - Alle Operationen des Scripts
- `ffmpeg_.log` - ffmpeg-Ausgabe pro Job
```bash
# Logs in Echtzeit verfolgen
./stream-recorder.sh logs
# Aufnahme mit ausführlicher Ausgabe starten
./stream-recorder.sh -V record mein-stream
```
## Verzeichnisstruktur
```
stream-recorder/
├── stream-recorder.sh # Hauptscript
├── config/
│ └── stream-recorder.conf # Konfiguration
├── jobs/ # Job-Definitionen
│ └── templates/ # Vorlagen
│ ├── example-rtmp.job.dist
│ ├── example-mp3.job.dist
│ └── example-hls.job.dist
├── install/
│ ├── install.sh # Scheduler installieren
│ └── uninstall.sh # Scheduler deinstallieren
├── README.md
└── LICENSE
```
© Patrick Asmus · Techniverse Network · Lizenz