scriptos/stream-recorder
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Release: v2.7.0 + Dokumentation ausgelagert

Browse Source
This commit is contained in:
Patrick Asmus
2026-09-07 12:54:53 +02:00
parent 7ddfb0e0d4
commit f3a8e20d7f
16 changed files with 1103 additions and 330 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -311
View File
@@ -19,350 +19,88 @@
·
<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.
<br>
## 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
- **Mehrere Stream-Typen** — RTMP, RTMPS, HLS (m3u8), MP3, AAC, OGG, FLAC und HTTP-Streams
- **Job-basiert** — Ein Stream = eine Job-Datei, inklusive Zeitplanung
- **Segment-Splitting** — Lange Aufnahmen automatisch in Teile zerlegen (z.B. stündlich)
- **Plik-Upload** — Aufnahmen und Segmente automatisch auf Plik hochladen
- **Zeitplanung** — Aufnahmezeiten direkt in der Job-Datei konfigurieren (kein Cron nötig)
- **Auto-Reconnect** — Automatische Wiederverbindung bei Verbindungsabbrüchen
- **Live-Status** — Laufende Aufnahmen mit Laufzeit, Dateigröße und Segment-Anzahl anzeigen
- **NTFY-Benachrichtigungen** — Push-Nachrichten bei Start, Stop, Fehler und Upload
- **Schnellaufnahme** — Interaktiver Modus für spontane Aufnahmen
## 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`)
- **Linux** (getestet unter Ubuntu/Debian)
- **Bash** 4.0+
- **ffmpeg** (`sudo apt install ffmpeg`)
- **curl** (optional, für NTFY und Plik)
## Installation
## Schnellstart
```bash
# Repository klonen
# Klonen und einrichten
git clone https://git.techniverse.net/scriptos/stream-recorder.git /opt/stream-recorder
cd /opt/stream-recorder
# Konfiguration anpassen
cp config/stream-recorder.conf.dist config/stream-recorder.conf
nano config/stream-recorder.conf
# Scheduler installieren (systemd-Timer)
# Scheduler installieren (optional)
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, Zeitplan und Plik-Upload und erstellt die Job-Datei automatisch. Bei aktiviertem Zeitplan wird die Aufnahmedauer wahlweise per Endzeit oder Laufzeit begrenzt — das jeweils andere wird automatisch berechnet.
**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 | Aufnahmedauer in Sekunden (wird bei Zeitplanung automatisch aus Endzeit oder Laufzeit berechnet) |
| `EXTRA_FFMPEG_ARGS`| Nein | Zusätzliche ffmpeg-Parameter |
| `PLIK_ENABLED` | Nein | Plik-Upload aktivieren (`true`/`false`) |
| `DELETE_AFTER_UPLOAD` | Nein | Lokale Datei nach erfolgreichem Upload löschen (`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
# Ersten Job 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
# Oder direkt loslegen
./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:
## Befehle
```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
./stream-recorder.sh record <job> # Aufnahme starten
./stream-recorder.sh stop <job> # Aufnahme stoppen
./stream-recorder.sh status # Laufende Aufnahmen anzeigen
./stream-recorder.sh list # Alle Jobs anzeigen
./stream-recorder.sh create # Neuen Job erstellen
./stream-recorder.sh quick # Schnellaufnahme
./stream-recorder.sh logs # Logs live verfolgen
```
## Zeitplanung
## Dokumentation
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
```
| Thema | Beschreibung |
|-------|-------------|
| [Installation](docs/installation.md) | Installation, Updates, Deinstallation |
| [Konfiguration](docs/konfiguration.md) | Alle Konfigurationsparameter |
| [Job-Dateien](docs/jobs.md) | Jobs erstellen und verwalten |
| [Zeitplanung](docs/zeitplanung.md) | Automatische Aufnahmezeiten |
| [Segment-Splitting](docs/segment-splitting.md) | Aufnahmen in Teile zerlegen |
| [Plik-Upload](docs/plik-upload.md) | Automatischer Upload auf Plik |
| [Benachrichtigungen](docs/benachrichtigungen.md) | NTFY Push-Nachrichten |
| [Befehle](docs/befehle.md) | Alle Befehle im Detail |
| [Beispiele](docs/beispiele.md) | Praxisbeispiele und Workflows |
## Verzeichnisstruktur
```
stream-recorder/
├── stream-recorder.sh # Hauptscript
├── stream-recorder.sh # Hauptscript
├── config/
│ └── stream-recorder.conf # Konfiguration
├── jobs/ # Job-Definitionen
│ └── templates/ # Vorlagen
│ └── stream-recorder.conf.dist # Konfigurations-Vorlage
├── jobs/ # Job-Definitionen
│ └── templates/ # Vorlagen
│ ├── example-rtmp.job.dist
│ ├── example-mp3.job.dist
│ └── example-hls.job.dist
│ ├── example-hls.job.dist
│ └── example-mp3.job.dist
├── docs/ # Dokumentation
├── install/
│ ├── install.sh # Scheduler installieren
│ └── uninstall.sh # Scheduler deinstallieren
│ ├── install.sh # Scheduler installieren
│ └── uninstall.sh # Scheduler deinstallieren
├── README.md
└── LICENSE
```