13 KiB
stream-recorder
Generischer Stream-Recorder für RTMP, HLS, HTTP-Audio und weitere Formate
🏰 Website · 📰 Community · 🐘 Mastodon · 💬 Support
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
# 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
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):
./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):
# 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
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
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
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
# 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:
./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:
./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
- Job-Datei erstellen und
SCHEDULE_*-Parameter setzen - Scheduler installieren mit
sudo install/install.sh(einmalig) - 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_DURATIONoder manueller Stop - Einmalig: Mit
SCHEDULE_ONCE=trueundSCHEDULE_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 (selbst gehostet oder öffentlich). In der Konfigurationsdatei:
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-BenachrichtigungRETRY_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-Server hochgeladen werden.
Einrichtung
- Plik-Server konfigurieren in
config/stream-recorder.conf:
PLIK_URL="https://plik.example.com"
PLIK_API_KEY="" # Optional, nur bei geschützten Servern
PLIK_TTL="30d" # Gültigkeitsdauer: 30d, 24h, oder Sekunden
- Pro Job aktivieren in der Job-Datei:
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:
NTFY_EVENTS="start,stop,error,upload"
Logging
Logs werden nach LOG_DIR geschrieben (Standard: /var/log/stream-recorder/):
stream-recorder.log- Alle Operationen des Scriptsffmpeg_<job-id>.log- ffmpeg-Ausgabe pro Job
# 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