380 lines
13 KiB
Markdown
380 lines
13 KiB
Markdown
<p align="center">
|
|
<a href="https://techniverse.net">
|
|
<img src="https://assets.techniverse.net/f1/git/graphics/repo-techniverse-logo.png" alt="Techniverse Community" height="70" />
|
|
</a>
|
|
</p>
|
|
|
|
<h1 align="center">stream-recorder</h1>
|
|
|
|
<h4 align="center">
|
|
Generischer Stream-Recorder für RTMP, HLS, HTTP-Audio und weitere Formate
|
|
</h4>
|
|
|
|
<h6 align="center">
|
|
<a href="https://www.cleveradmin.de">🏰 Website</a>
|
|
·
|
|
<a href="https://techniverse.net">📰 Community</a>
|
|
·
|
|
<a href="https://social.techniverse.net/@donnerwolke">🐘 Mastodon</a>
|
|
·
|
|
<a href="https://matrix.to/#/#support:techniverse.net">💬 Support</a>
|
|
</h6>
|
|
<br><br>
|
|
|
|
## 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 |
|
|
| `STATE_DIR` | `/var/lib/stream-recorder` | Status für bereits gestartete Zeitpläne |
|
|
| `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, z.B. `300`, `5m`, `1h30m` (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_ONCE` | `false` | Einmaliger Termin statt wöchentlichem Zeitplan |
|
|
| `SCHEDULE_DATE` | (leer) | Datum für einmalige Termine (`YYYY-MM-DD`) |
|
|
| `SCHEDULE_DAYS` | `*` | Aufnahmetage für wöchentliche Zeitpläne |
|
|
| `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).
|
|
|
|
Ohne `SCHEDULE_ONCE=true` sind Tagesangaben wöchentlich/wiederkehrend. Ein Job mit `SCHEDULE_DAYS="Mi"` und `SCHEDULE_START="21:00"` läuft also jeden Mittwoch.
|
|
|
|
### 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="1h"
|
|
SCHEDULE_ENABLED=true
|
|
SCHEDULE_ONCE=false
|
|
SCHEDULE_DAYS="Mo-Fr"
|
|
SCHEDULE_START="18:00"
|
|
```
|
|
|
|
### Beispiel: Einmalige Aufnahme am 09.09.2026 um 21:00, 30 Minuten
|
|
|
|
```bash
|
|
STREAM_NAME="Einmaliger-Mitschnitt"
|
|
STREAM_URL="https://example.com/stream.mp3"
|
|
MAX_DURATION="30m"
|
|
SCHEDULE_ENABLED=true
|
|
SCHEDULE_ONCE=true
|
|
SCHEDULE_DATE="2026-09-09"
|
|
SCHEDULE_START="21:00"
|
|
SCHEDULE_STOP=""
|
|
```
|
|
|
|
## Verwendung
|
|
|
|
### Befehle
|
|
|
|
```bash
|
|
# Einzelnen Stream aufzeichnen
|
|
./stream-recorder.sh record mein-stream
|
|
|
|
# Im Vordergrund aufzeichnen, z.B. für Tests
|
|
./stream-recorder.sh --foreground 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
|
|
|
|
# Vorhandene Aufnahme erneut nach Plik hochladen
|
|
./stream-recorder.sh upload /pfad/zur/aufnahme.mp4 "Stream-Name"
|
|
|
|
# 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
|
|
- **Einmalig:** Mit `SCHEDULE_ONCE=true` und `SCHEDULE_DATE="YYYY-MM-DD"` startet der Job nur an diesem Datum
|
|
- **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 Browser-Link zur Plik-Upload-Seite wird im Log und per NTFY ausgegeben
|
|
- Die direkte Datei-URL wird zusätzlich ins Log geschrieben
|
|
- Optional wird der Link per NTFY-Benachrichtigung gesendet (Event: `upload`)
|
|
- Plik-Uploads verwenden den direkten Multipart-Upload-Endpunkt des Servers.
|
|
|
|
### 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_<job-id>.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
|
|
```
|
|
|
|
|
|
<br><br>
|
|
<p align="center">
|
|
<img src="https://assets.techniverse.net/f1/git/graphics/gray0-catonline.svg" alt="">
|
|
</p>
|
|
|
|
<p align="center">
|
|
<sub>
|
|
© Patrick Asmus · Techniverse Network · <a href="./LICENSE">Lizenz</a>
|
|
</sub>
|
|
</p>
|