stream-recorder/README.md

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
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 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

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="3600"
SCHEDULE_ENABLED=true
SCHEDULE_DAYS="Mo-Fr"
SCHEDULE_START="18:00"

Verwendung

Befehle

# 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:

./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

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 (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-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-Server hochgeladen werden.

Einrichtung

1. 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

2. 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 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:

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

# 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}