Skip to main content
Glama

standbild

Erklärvideos zu Transkript + Screenshots. standbild wandelt ein Software-Erklärvideo (YouTube-Link oder lokale Datei) in ein ZIP-Paket um: ein Markdown-Transkript, in das an jeder relevanten Bildänderung ein Screenshot in Originalauflösung eingehängt ist. Das Paket ist für Menschen lesbar und für eine spätere Auswertung durch eine KI vorbereitet.

  • Läuft vollständig lokal in einem einzigen Docker-Image (Whisper large-v3-turbo ist enthalten).

  • Keine „große KI“: nur lokales Speech-to-Text (Whisper). Bildvergleich, Ausrichtung und Ausgabe sind klassische, deterministische Algorithmen. Kein OCR, keine Zusammenfassung.

  • Drei Zugänge, ein Kern: Web-UI, MCP-Endpunkt und CLI; Aufträge liegen in einer Postgres-Warteschlange.

>>>>> ![frame_0002 · 00:00:41](frames/frame_0002_00-00-41.png)

[00:00:41](https://www.youtube.com/watch?v=abc123&t=41s) Hier seht ihr die Datei docker-compose.yml. …

Hinweis zu YouTube: Das Herunterladen von YouTube-Videos widerspricht den YouTube-Nutzungsbedingungen. standbild ist für den privaten Gebrauch gedacht. Verarbeite nur Videos, die du verwenden darfst.

Das Paket

abc123_20261114-1830.zip
├── AGENTS.md              Anleitung für eine KI: wie das Paket zu lesen ist
├── transcript.md          Transkript mit >>>>>-Bildverweisen
├── frames/                Screenshots als PNG, exakt in der Auflösung des Videos
├── meta.json              Video-Metadaten, Kapitel, wirksame Parameter, Modell
└── log/
    ├── processing.log     Versionen, Einstellungen, Dauer jeder Stufe, Warnungen
    ├── frames.json        pro Screenshot: Zeit, Messwerte, Grund, Duplikat
    └── detection_log.csv  Messwerte pro analysiertem Frame

Eine Zeile >>>>> ![frame_NNNN · hh:mm:ss](frames/…) bedeutet: Ab hier zeigt der Bildschirm dieses Bild, bis zur nächsten Markierung. Kehrt das Video zu einer früheren Ansicht zurück, verweist die Markierung auf das frühere Bild. Markdown-Viewer wie Obsidian, VS Code oder GitHub zeigen die Bilder direkt an.

Related MCP server: shared-video-transcriber

Bauen und Bereitstellen

Fertige Images liegen in der GitHub Container Registry. Die Action release.yml baut bei jeder Änderung an Code oder Dockerfile auf main (oder von Hand über „Run workflow“) ein Image und veröffentlicht es unter der Version YYYY-MM-DD_hhmmss (UTC) und als latest:

docker pull ghcr.io/bjoernwuest/standbild:latest

Selbst bauen und in eine eigene Registry schieben:

make build REGISTRY=registry.local:5000     # baut :<Version aus pyproject.toml> und :latest
make push  REGISTRY=registry.local:5000

Das entspricht docker build -t registry.local:5000/standbild:1.0.0 -t registry.local:5000/standbild:latest . und zwei docker push. Der erste Build lädt das Whisper-Modell (ca. 1,6 GB); das CPU-Image ist ca. 3,4 GB groß.

Build-Argument

Voreinstellung

Bedeutung

SEED_MODEL

large-v3-turbo

Whisper-Modell der Startausstattung (Name wie in faster-whisper)

YTDLP_VERSION

leer

yt-dlp-Version; leer = neueste beim Build

CUDA

0

1 installiert zusätzlich die CUDA-Bibliotheken für GPU-Betrieb

Beispiel: make build BUILD_ARGS="--build-arg CUDA=1".

Starten

Die Postgres-Datenbank (Version ≥ 13) muss existieren und darf leer sein; die Tabellen legt standbild beim Start selbst an. Der Datenbankbenutzer muss im Schema Tabellen anlegen dürfen. Ab Postgres 15 ist das im Schema public nur noch dem Eigentümer der Datenbank erlaubt; fehlt das Recht, nennt die Fehlermeldung beim Start den passenden GRANT.

docker run -d --name standbild --restart unless-stopped -p 8080:8080 \
  -v standbild-tmp:/tmp -v standbild-packages:/data/packages -v standbild-models:/models \
  -e STANDBILD_DB_HOST=db.local -e STANDBILD_DB_NAME=standbild \
  -e STANDBILD_DB_USER=standbild -e STANDBILD_DB_PASSWORD=geheim \
  -e STANDBILD_PUBLIC_URL=http://nas.local:8080 \
  registry.local:5000/standbild:latest

Danach: Web-UI unter http://<host>:8080/, REST unter /api (Dokumentation: /api/docs), MCP unter /mcp. Beim ersten Start wird large-v3-turbo ohne Netzwerkzugriff ins Modell-Volume kopiert und als Standardmodell eingetragen. GPU-Variante: Image mit CUDA=1 bauen und zusätzlich --gpus all angeben. Zeitstempel in Paketnamen und Protokollen sind UTC; mit -e TZ=Europe/Berlin gilt die lokale Zeit.

Volumes

Volume

Inhalt

Größenordnung

/tmp

Videodownload und Zwischendateien je Auftrag (/tmp/standbild/<job_id>/), nach Abschluss gelöscht

einige GB pro laufendem Auftrag

/data/packages

Ergebnis-ZIPs (<youtube-id>_<yyyymmdd-hhmm>.zip)

5–50 MB pro Paket

/models

Whisper-Modelle, ein Unterverzeichnis pro Modell

0,5–3 GB pro Modell

Ohne -v legt Docker anonyme Volumes an. Für Pakete und Modelle sind benannte Volumes oder Bind-Mounts sinnvoll, damit sie Updates des Containers überleben. Der Container läuft als UID/GID 1000; bei Bind-Mounts muss das Verzeichnis diesem Benutzer gehören, sonst bricht der Start mit einer klaren Meldung ab.

Konfiguration

Betrieb

Variable

Voreinstellung

Bedeutung

STANDBILD_DB_HOST

– (Pflicht)

Postgres-Host

STANDBILD_DB_PORT

5432

Postgres-Port

STANDBILD_DB_NAME

– (Pflicht)

Datenbankname

STANDBILD_DB_USER

– (Pflicht)

Benutzername

STANDBILD_DB_PASSWORD

– (Pflicht)

Passwort; alternativ STANDBILD_DB_PASSWORD_FILE (Docker Secrets)

STANDBILD_DB_SCHEMA

public

Schema der Tabellen; wird bei Bedarf angelegt

STANDBILD_DB_SSLMODE

prefer

libpq-SSL-Modus

STANDBILD_PORT

8080

HTTP-Port für Web-UI, API und MCP

STANDBILD_PUBLIC_URL

http://localhost:8080

Basis-URL für Download-Links in MCP-Antworten

STANDBILD_WORKERS

1

Anzahl paralleler Aufträge

STANDBILD_API_TOKEN

leer

Wenn gesetzt: Bearer-Token für /api und /mcp; Web-UI per Basic-Auth (beliebiger Benutzername, Passwort = Token)

STANDBILD_DEVICE

auto

cpu oder cuda

STANDBILD_KEEP_RESULTS

3

Gespeicherte Ergebnisse pro Video; ältere werden samt ZIP gelöscht

STANDBILD_MCP_MAX_INLINE_MB

25

Größte ZIP-Größe, die das MCP-Tool get direkt einbettet

STANDBILD_TEMPLATE_DIR

leer

Verzeichnis mit einer eigenen AGENTS.md.j2

STANDBILD_YTDLP_AUTOUPDATE

false

yt-dlp beim Start per pip aktualisieren

STANDBILD_CONDITION_ON_PREVIOUS_TEXT

true

Whisper-Kontext über Fenstergrenzen (siehe DECISIONS.md)

STANDBILD_LOG_LEVEL

INFO

Logausgabe auf stdout

HF_TOKEN

leer

Optional, für zugangsbeschränkte HuggingFace-Modelle

Verarbeitungsparameter

Jeder Parameter lässt sich pro Auftrag setzen (Web-UI „Parameter“, MCP process → options, CLI-Option --<name>) und hat STANDBILD_<NAME> als Voreinstellung. Rangfolge, der höhere Rang gewinnt:

  1. Werte des Auftrags

  2. das beim Auftrag gewählte Profil

  3. Umgebungsvariablen

  4. eingebaute Voreinstellungen

Ungültige Werte werden abgelehnt, bevor ein Auftrag entsteht. Die wirksamen Werte stehen in meta.json.

Schlüssel

Voreinstellung

Erlaubt

Bedeutung

profile

default

slides, default, coding

Satz von Schwellen (siehe unten)

whisper_model

Standardmodell

installierte Modelle

Modell für die Transkription

lang

auto

ISO-Code oder auto

Sprache für Whisper

use_subtitles

false

bool

Manuelle YouTube-Untertitel statt Whisper (automatische werden nie verwendet)

max_height

1080

360–2160

Maximale Downloadhöhe in Pixeln

sample_interval

0.5

0,1–5 s

Abstand der analysierten Frames

threshold

0.05

0,001–0,9

Anteil geänderter Fläche für einen Wechsel

min_local_change

0.004

0,0005–0,5

Schwelle für kleine, zusammenhängende Änderungen

pixel_noise

20

1–128

Mindestdifferenz, ab der ein Pixel als geändert gilt

stable_time

1.0

0–10 s

Ruhezeit vor dem Screenshot

max_wait

8

1–60 s

Danach Screenshot auch ohne Ruhe

min_gap

3.0

0–120 s

Mindestabstand zwischen Screenshots

max_per_minute

6

1–60

Obergrenze pro Minute

analysis_width

960

320–1920 px

Breite des internen Vergleichsbildes

masks

leer

Liste [x, y, w, h], relativ 0–1

Bereiche, die ignoriert werden (z. B. Webcam)

timestamps

true

bool

Absätze beginnen mit [hh:mm:ss]

Profil

threshold

min_local_change

stable_time

min_gap

slides

0,08

0,02

1,0 s

5 s

default

0,05

0,004

1,0 s

3 s

coding

0,02

0,002

1,5 s

4 s

Web-UI

Eine Seite unter /: YouTube-Link einfügen, dann zeigt eine Karte je nach Zustand Verarbeiten, den Fortschritt, oder Herunterladen und Erneut verarbeiten. Der aufklappbare Bereich „Parameter“ ist mit den zuletzt für dieses Video verwendeten Werten vorbelegt, sonst mit den Voreinstellungen. Darunter stehen die letzten 20 Aufträge. /?url=<Link> öffnet die Karte zu einem Link direkt.

MCP

Streamable HTTP unter /mcp, zustandslos, Servername standbild. Einbindung:

{"mcpServers": {"standbild": {"type": "http", "url": "http://nas.local:8080/mcp",
  "headers": {"Authorization": "Bearer <token>"}}}}

(Der headers-Eintrag entfällt ohne STANDBILD_API_TOKEN.)

Tool

Parameter

Ergebnis

process

url, force (false), options (Schlüssel der Tabelle oben)

job_id, status, reused, wirksame options. Ein Ergebnis mit denselben wirksamen Parametern wird wiederverwendet.

status

job_id

status (queued, running, done, failed), stage, progress; höchstens alle 15 s abfragen

get

job_id

ZIP als eingebettete Ressource plus Name, Größe, SHA-256 und Download-URL; über STANDBILD_MCP_MAX_INLINE_MB nur die URL

{"url": "https://youtu.be/abc123", "options": {"profile": "coding", "threshold": 0.03, "masks": [[0.78, 0.72, 0.22, 0.28]]}}

REST-API

Methode und Pfad

Zweck

GET /api/videos/lookup?url=

Link normalisieren, Zustand des Videos, zuletzt verwendete Parameter

GET /api/defaults

Wirksame Voreinstellungen, Profile, Wertebereiche, installierte Modelle

POST /api/jobs {url, force?, options?}

Auftrag anlegen → {job_id, status, reused, …}

GET /api/jobs/{id}

Status

GET /api/jobs/{id}/package

ZIP herunterladen

GET /api/jobs?limit=20

Letzte Aufträge

GET /api/models, POST /api/models {url, name?}, DELETE /api/models/{name}, PUT /api/models/{name}/default

Modelle verwalten

GET /healthz

Lebenszeichen inkl. Datenbank und beschreibbarer Volumes

CLI

standbild serve                       Web-UI + REST + MCP + Worker (Standard-Befehl des Images)
standbild run <URL|Datei> [Optionen]  ein Video direkt verarbeiten, ohne Datenbank
standbild migrate                     Tabellen anlegen/aktualisieren (macht serve auch beim Start)
standbild preview <ZIP|Job-ID>        Diagramm der Änderungswerte zum Einstellen der Schwellen
# Einzelaufruf ohne Datenbank; das ZIP landet im Paket-Volume
docker run --rm -v standbild-packages:/data/packages -v standbild-models:/models \
  registry.local:5000/standbild:latest standbild run "https://www.youtube.com/watch?v=…" --profile coding

# im laufenden Container, mit Maske für eine Webcam unten rechts
docker exec standbild standbild run "https://youtu.be/…" --mask 0.78,0.72,0.22,0.28 --no-timestamps

run nimmt alles an, was yt-dlp unterstützt, oder eine lokale Videodatei, außerdem --out <Verzeichnis> und --cookies cookies.txt (für altersbeschränkte Videos). Eingabe- und Downloadfehler enden mit Exit-Code 2.

Whisper-Modelle verwalten

Reiter „Modelle“ im Web-UI: Liste aller Modelle mit Quelle, Größe, Status und Standardmodell. Zum Hinzufügen einen HuggingFace-Link oder eine Repo-ID eintragen, z. B. Systran/faster-whisper-medium (optional mit …/tree/<revision>). Akzeptiert werden nur CTranslate2-Modelle für faster-whisper (model.bin, config.json, tokenizer.json oder vocabulary.*); Transformers-Modelle werden nicht konvertiert. Der Download läuft im Hintergrund, danach steht das Modell im Parameterbereich und für MCP options.whisper_model zur Auswahl. Das Standardmodell und Modelle, die gerade ein Auftrag nutzt, lassen sich nicht entfernen.

Die Modelle liegen ohne Datenbank im Volume /models: ein Verzeichnis pro Modell mit standbild-model.json, das Standardmodell steht in default.txt.

Schwellen einstellen mit preview

Zu viele oder zu wenige Screenshots? preview zeichnet aus einem fertigen Paket global_ratio und largest_region über die Zeit, die beiden Schwellen als gestrichelte Linien und jeden gespeicherten Screenshot als senkrechte Linie:

docker exec standbild standbild preview <Job-ID> --out /data/packages/preview.png
standbild preview abc123_20261114-1830.zip
  • Kurve liegt oft knapp über min_local_change, ohne dass sich Wichtiges ändert → Wert erhöhen (oder Profil slides).

  • Neue Codezeilen bleiben unter der Linie → Profil coding oder min_local_change senken.

  • Lange Strecken über der Schwelle ohne Screenshot → max_per_minute hat gebremst; erhöhen, wenn mehr Zwischenstände gewünscht sind.

  • Eine Webcam hält die Kurven dauerhaft oben → mit masks ausblenden.

log/frames.json nennt zu jedem Screenshot den Grund (first, global, local, forced).

yt-dlp aktuell halten

YouTube ändert regelmäßig Details, die neue yt-dlp-Versionen erfordern. Regulär: Image neu bauen (yt-dlp wird dabei aktualisiert) und neu ausrollen. Optional aktualisiert STANDBILD_YTDLP_AUTOUPDATE=true yt-dlp bei jedem Containerstart per pip; schlägt das fehl, gilt die mitgelieferte Version. Scheitert ein Download mit einem typischen yt-dlp-Fehler, steht im Auftrag der Hinweis „yt-dlp evtl. veraltet – Image neu bauen“.

Richtwerte zur Laufzeit

Gemessen im Container auf einer VM mit 8 CPU-Kernen ohne GPU (large-v3-turbo, int8), Voreinstellungen:

Video

Auflösung

Download

Bildwechsel

Transkription

gesamt

Screenshots

Paket

4:31 min, Live-Demo

1280×706

8 s

24 s

2:00 min

2:08 min

23

5,7 MB

4:23 min, Folien

1920×1080

8 s

13 s

2:17 min

2:24 min

6

3,6 MB

15:43 min, Folien + Demo

1920×1080

10 s

54 s

4:43 min

4:54 min

57

25 MB

Bildwechsel-Erkennung und Transkription laufen parallel; die Transkription bestimmt die Dauer (etwa ein Drittel bis die Hälfte der Videolänge). Whisper nutzt 4 Threads; mehr Kerne lassen sich mit OMP_NUM_THREADS zuweisen. Mit GPU ist die Transkription um ein Vielfaches schneller (nicht gemessen). Speicherbedarf: ca. 2 GB je Worker.

Entwicklung

python3.12 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"            # braucht ffmpeg im PATH
pytest                             # Datenbanktests starten Postgres per testcontainers (Docker nötig)
pytest -m slow                     # Transkription mit dem Modell tiny (lädt es beim ersten Lauf)
make lint                          # ruff + mypy --strict

tests/data/jfk.wav ist eine gemeinfreie Aufnahme (John F. Kennedy, 1961) aus den Beispielen von whisper.cpp. Mit STANDBILD_TEST_DB=postgresql://user:pass@host:5432/db laufen die Datenbanktests gegen einen vorhandenen Postgres (jeder Test in einem eigenen Schema). Abweichungen von der Spezifikation stehen in DECISIONS.md.

Lizenz

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables turning YouTube video URLs into timestamped, citation-ready transcript evidence, with optional search, comments, analytics, and cross-video comparison for MCP clients.
      159 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to submit Douyin/Bilibili/YouTube links or local audio/video and create reusable processing jobs, then retrieve timestamped transcripts, SRT subtitles, summaries, sampled screenshots, exports, and optional AI-rewritten scripts through MCP tools sharing a local FastAPI job store.
      MIT