Porter Skill (Streaming Worker)

Ein Video-Link in einen fertigen Clip mit fest eingebrannten chinesischen Untertiteln verwandeln. Vier Phasen werden nacheinander ausgeführt: Holen → Transkribieren → Übersetzen → Einbrennen. Jede Phase schreibt ihre Ergebnisse auf die Festplatte, sodass bei einem Fehler in einer späteren Phase die bereits abgeschlossenen Teile nicht verloren gehen.

⚠️ Voraussetzung: Für das Transkribieren wird ein Schlüssel benötigt

Dies muss zuerst bestätigt werden, da die Aufgabe sonst in der Transkriptionsphase fehlschlägt.

Fähigkeit	Benötigt Schlüssel?
Herunterladen, Übersetzen, Einbrennen	Nicht benötigt
Sprachtranskription (ASR)	Benötigt `OPENAI_API_KEY` (oder `WHISPER_API_KEY`), oder installiertes VideoCaptioner CLI
Native Untertitelspuren (YouTube / Bilibili usw.)	Nicht benötigt – bei vorhandener nativer Spur wird kein ASR ausgeführt

Der in v0.1 angekündigte „reine Python-Schlüssellose Kreislauf" ist nicht mehr gültig: Alle schlüssellosen Spracherkennungs-Endpunkte sind abgeschaltet (Stand 2026-09-22; oder verwenden Sie das [asr-local] Extra für schlüssellose lokale Erkennung). Wenn kein Schlüssel vorhanden ist und das Video auch keine Plattform-Untertitelspur hat, wird die Aufgabe in der transcribe-Phase mit every speech-to-text backend failed beendet.

Daher: Führen Sie zuerst plan aus – es zeigt Ihnen direkt an, ob dieses Video über die native Untertitelspur oder über ASR läuft und ob das machbar ist.

Einstiegspunkt für den Aufruf

Der CLI-Einstiegspunkt wird über uvx ausgeführt. Windows PowerShell verwenden Sie das native .ps1-Skript und gehen nicht davon aus, dass Git Bash / WSL verfügbar ist:

Skript	Zweck
`scripts/porter.sh`	Bash-Haupteinstiegspunkt, leitet an die `porter` CLI weiter.
`scripts/porter.ps1`	Windows PowerShell-Haupteinstiegspunkt, unterstützt ebenfalls Unterbefehle wie `inspect` / `plan` / `run` / `jobs`.
`scripts/inspect.sh`	Bash-Prüfung, entspricht `porter.sh inspect`.
`scripts/bootstrap.sh`	Alternativer Einstiegspunkt, der aus dem Repository-Checkout ein `.venv` erstellt; installiert den Python-Quellcode nicht zusammen mit dem Skill.

# Prüfung
<SKILL_DIR>/scripts/inspect.sh "https://youtu.be/dQw4w9WgXcQ"
# Planung
<SKILL_DIR>/scripts/porter.sh plan "https://youtu.be/dQw4w9WgXcQ"
# Ausführung
<SKILL_DIR>/scripts/porter.sh run "https://youtu.be/dQw4w9WgXcQ" -o ./porter_output

Windows PowerShell verwendet & '<SKILL_DIR>\scripts\porter.ps1' inspect '<URL>' --json, plan / run / jobs werden ebenfalls über denselben Einstiegspunkt aufgerufen. inspect.sh und die unten stehenden nohup- und grep-Befehle sind Bash-Beispiele und können nicht direkt in PowerShell eingefügt werden.

uvx benötigt beim ersten Start eine Internetverbindung, um Abhängigkeiten aufzulösen. Standardmäßig wird nur porter-workflow[llm] installiert (das Basispaket enthält bereits yt-dlp); für lokales ASR wird nach Zustimmung des Benutzers PORTER_SKILL_SPEC=porter-workflow[llm,asr-local] gesetzt. Für die Offline-Installation bereiten Sie die lokalen Abhängigkeiten im Repository-Checkout vor, anstatt darauf zu vertrauen, dass das Skill-Verzeichnis den Quellcode selbst enthält.

In einem Host, in dem nur das Arbeitsverzeichnis beschreibbar ist, bestätigen Sie zuerst das erlaubte absolute Verzeichnis, setzen Sie PORTER_SKILL_STATE_DIR auf dessen .state-Unterverzeichnis und führen Sie porter.sh --host-check oder porter.ps1 --host-check aus; es leitet uv, yt-dlp und den Auftragsregister-Cache dorthin um (überschreibt die vom Host gesetzten Cache-Pfade). Die Ausgabe -o muss sich ebenfalls im erlaubten Verzeichnis befinden. Wenn nicht gesetzt, werden die Standardpfade des Hosts beibehalten. Befehle, Einschränkungen und Windows-Beispiele finden Sie in references/HOSTS.md.

Workflow-Ablauf

Wird der Reihe nach ausgeführt. Jeder Schritt ist günstiger als der nächste, um schlechte Eingaben zu verwerfen, bevor zeitaufwändige Berechnungen durchgeführt werden.

1. Prüfung – `inspect`

<SKILL_DIR>/scripts/inspect.sh "<URL>" --json

Gibt Plattform, Titel, Dauer, Auflösung, Seitenverhältnis und Vorhandensein von Untertitelspuren zurück. Wird abgeschlossen, bevor Medien heruntergeladen werden, in Sekunden.

Interpretation: is_valid bedeutet, dass der Link funktioniert; ok bedeutet nur, dass der Aufruf erfolgreich war. Wenn der Link ungültig ist (is_valid=false), wiederholen Sie es nicht – das Wiederholen toter Links ist sinnlos.

Exit-Code 1 bedeutet, dass der Link nicht verfügbar ist.

2. Planung – `plan`

<SKILL_DIR>/scripts/porter.sh plan "<URL>" --json

Dies ist der zeitsparendste Schritt, der die Frage beantwortet: „Wie wird dieses Video verarbeitet und ist das möglich?":

subtitles.route: platform (Verwendung der nativen Untertitelspur der Plattform) oder asr (Ausführung der Spracherkennung)
translation.needed: Bei vorhandener chinesischer Spur false, kann die Übersetzung vollständig übersprungen werden
feasible / blocking_issues: Wenn false, dann stoppen und keinen Auftrag starten
notes: Unbedingt lesen. Zwei wichtige Punkte:
- Die native Untertitelspur der Plattform ist "angefordert, nicht garantiert" – das Abrufen kann fehlschlagen (Plattform-Drosselung, HTTP 429) und auf Spracherkennung zurückfallen
- Wenn die verfügbaren Erkennungs-Backends alle nicht getestete Reverse-Engineering-Endpunkte sind, wird dies im Hinweistext explizit erwähnt

Exit-Code 1 bedeutet, dass es nicht machbar ist.

3. Benutzerbestätigung

Ein Auftrag kann mehrere hundert MB herunterladen und Minuten dauern. Melden Sie das Ergebnis von plan dem Benutzer und holen Sie seine Zustimmung ein, bevor Sie starten (welche Spur genommen wird, welche Phasen ausgeführt werden, ob eingebrannt wird). Wenn feasible=false, melden Sie das blockierende Problem und starten Sie keinen Auftrag.

4. Ausführung – `run`

<SKILL_DIR>/scripts/porter.sh run "<URL>" -o ./porter_output

Bei langen Videos warten Sie nicht im Vordergrund auf den Abschluss. Starten Sie es im Hintergrund und fragen Sie dann das Auftragsregister ab:

nohup <SKILL_DIR>/scripts/porter.sh run "<URL>" -o ./porter_output > run.log 2>&1 &
# Abfrage (Auftragsdatensätze werden in der gemeinsamen Registerdatei geschrieben, prozessübergreifend sichtbar)
<SKILL_DIR>/scripts/porter.sh jobs list
<SKILL_DIR>/scripts/porter.sh jobs status <job_id>

PowerShell starten Sie & '<SKILL_DIR>\scripts\porter.ps1' run ... asynchron mit dem vom Host bereitgestellten Hintergrundauftrags-Tool und fragen Sie kontinuierlich mit demselben PORTER_SKILL_STATE_DIR den jobs status ab. Verwenden Sie nicht Out-String, um den Fortschritt zeitaufwändiger Befehle bis zum Ende zu sammeln.

Nicht das Tool-Timeout auf 1200 Sekunden setzen, um lange Aufgaben zu erzwingen (wie in v0.1). Das schlägt bei noch längeren Videos fehl, und Sie erhalten keinerlei Fortschrittsinformationen bei einem Fehler. Das Auftragsregister wurde genau dafür entwickelt.

5. Qualitätskontrolle (obligatorisch)

Verlassen Sie sich nicht nur auf den Exit-Code für den Abschluss. Überprüfen Sie mindestens:

# 1. Chinesische Untertitel sind vorhanden und enthalten CJK (verhindert „nicht übersetzte Fake-Untertitel")
grep -qP '[\x{4e00}-\x{9fff}]' ./porter_output/<task>/cooked/subtitle_zh.srt \
  && echo "OK: Enthält Chinesisch" || echo "FEHLER: Kein Chinesisch"

# 2. Der fertige Clip ist dekodierbar und das moov-Atom ist intakt (verhindert veröffentlichte abgeschnittene Dateien)
ffprobe -v error -show_entries format=duration -of csv=p=0 ./porter_output/<task>/cooked/video_zh.mp4

Eine ungewöhnlich kleine Dateigröße des fertigen Clips deutet normalerweise auf einen Fehler beim Einbrennen hin, nicht auf ein kurzes Video.

6. Bei Fehlern

<SKILL_DIR>/scripts/porter.sh doctor     # Kann dieser Rechner die Arbeit erledigen: ffmpeg/libass, JS-Laufzeit, Schriftarten, Encoder
<SKILL_DIR>/scripts/porter.sh config list # Analysierte Konfiguration (Schlüssel maskiert)

Häufige Parameter

# Nur Untertitel, kein Einbrennen
run "<URL>" --burn skip

# Nur rein chinesischen fertigen Clip (keine zweisprachige Ausgabe)
run "<URL>" --burn zh_only

# Ausgabeverzeichnis / Zielsprache angeben
run "<URL>" -o /path/to/out --target-lang zh-Hans

# Ein bestimmtes Backend zuerst ausführen lassen (andere bleiben als Fallback, nicht „nur dieses verwenden")
run "<URL>" --translator google
run "<URL>" --asr-engine whisper-api

# Für diesen Auftrag ein anderes LLM-Modell verwenden (Konfiguration nicht ändern)
run "<URL>" --llm-model deepseek-reasoner

# Bereits vorhandene Quelluntertitel: direkt verwenden, keine Erkennung ausführen (.srt / .vtt)
run "<URL>" --subtitle-file ./my_subtitles.srt

# Video, das eine Anmeldung erfordert
run "<URL>" --cookies-from-browser chrome
run "<URL>" --cookies ./cookies.txt

# Erneut ausführen (zwischengespeicherte Phasenergebnisse ignorieren)
run "<URL>" --force

# Für Skriptkonsum
run "<URL>" --json

Die Semantik von --only-phase ist „bis zu dieser Phase", nicht „nur diese Phase ausführen" – jede Phase benötigt die Ausgabe der vorherigen, daher werden frühere Phasen trotzdem ausgeführt.

Ausgabestruktur

<task_dir>/
├── raw/                       # Master und Zwischenprodukte
│   ├── video.mp4              # Standardisiertes Master (verlustfreier Stream-Kopie, keine Neucodierung)
│   ├── audio.wav              # Referenz-Audiospur
│   ├── audio_enhanced.wav     # Für ASR optimierte Audiospur (Rauschunterdrückung + Sprachausgleich), wird nicht für den fertigen Clip verwendet
│   ├── subtitle.srt           # Untertitel in der Quellsprache (Plattformspur oder ASR-Ergebnis)
│   ├── transcript.json/.txt   # Strukturiertes Drehbuch
│   ├── cover.jpg
│   └── metadata.json
└── cooked/                    # Fertige Produkte
    ├── subtitle.srt / .ass    # Zweisprachig
    ├── subtitle_zh.srt / .ass # Rein chinesisch
    ├── video_bilingual.mp4    # Fertiger Clip mit zweisprachigen fest eingebrannten Untertiteln
    └── video_zh.mp4           # Fertiger Clip mit rein chinesischen fest eingebrannten Untertiteln

Das Audio des fertigen Clips ist direkt durchgeschleift (-c:a copy) aus dem Original-Master. Die optimierte Audiospur wird nur für die Erkennung verwendet – Erkennungsgenauigkeit und Endprodukt-Audioqualität werden gleichermaßen sichergestellt.

Konfiguration

Konfigurationssuchreihenfolge (spätere überschreiben frühere):

Integrierte Standardwerte
Umgebungsvariablen: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL, WHISPER_API_KEY, PORTER_ASR_ENGINE
Benutzerkonfiguration (porter config list gibt den tatsächlichen Pfad aus)
Projektkonfiguration: porter.json / porter.toml / config.json im aktuellen Verzeichnis
--config <path>

Vollständige Schlüsseltabelle in references/CONFIG.md, Vorlage in assets/config.example.json.

Verwendung über MCP (optional, aber besser)

Wenn der Host bereits einen porter MCP-Server konfiguriert hat, verwenden Sie diesen anstelle der Shell:

Strukturierte Ergebnisse, keine Notwendigkeit, stdout zu parsen (vermeidet auch Shell-Escape und Codierungsprobleme)
porter_job_start gibt sofort zurück + porter_job_status Polling, lange Aufgaben stoßen nicht auf Tool-Timeout
Einziger Weg, um „schlerlose LLM-Übersetzung" zu erhalten: §8.3 sampling verwendet das Host-Modell zur Übersetzung, der CLI-Prozess hat keinen Zugriff auf das Host-Modell

Tool-Namenszuordnung und Konfigurationsmethode in references/MCP.md.

Hinweis: npx skills add installiert nur das Skill-Verzeichnis, nicht den MCP-Server. Bei Neuinstallation orientieren Sie sich am CLI-Pfad.

Referenzdateien

Datei	Inhalt
`references/ARCHITECTURE.md`	Vier-Phasen-Pipeline, Plattform- und Backend-Fallback-Kette, Designeinschränkungen
`references/CONFIG.md`	Alle Konfigurationsschlüssel, Umgebungsvariablen, Priorität
`references/MCP.md`	MCP-Tool-Zuordnungstabelle und Konfigurationsmethode
`references/HOSTS.md`	Windows-nativer Einstiegspunkt und Prüfung für eingeschränkte Hosts
`assets/config.example.json`	Konfigurationsvorlage

Letzte Überprüfung: 2026-09-22

Video-Lokalisierung: vom Link zur Version mit Untertiteln

Was ist Video-Lokalisierung: vom Link zur Version mit Untertiteln?

In Ihrer bevorzugten KI fragen

Dokumentation

Porter Skill (Streaming Worker)

⚠️ Voraussetzung: Für das Transkribieren wird ein Schlüssel benötigt

Einstiegspunkt für den Aufruf

Workflow-Ablauf

1. Prüfung – `inspect`

2. Planung – `plan`

3. Benutzerbestätigung

4. Ausführung – `run`

5. Qualitätskontrolle (obligatorisch)

6. Bei Fehlern

Häufige Parameter

Ausgabestruktur

Konfiguration

Verwendung über MCP (optional, aber besser)

Referenzdateien

Verwandte Skills

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

In Ihrer bevorzugten KI fragen

Dokumentation

Porter Skill (Streaming Worker)

⚠️ Voraussetzung: Für das Transkribieren wird ein Schlüssel benötigt

Einstiegspunkt für den Aufruf

Workflow-Ablauf

1. Prüfung – inspect

2. Planung – plan

3. Benutzerbestätigung

4. Ausführung – run

5. Qualitätskontrolle (obligatorisch)

6. Bei Fehlern

Häufige Parameter

Ausgabestruktur

Konfiguration

Verwendung über MCP (optional, aber besser)

Referenzdateien

Verwandte Skills

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

1. Prüfung – `inspect`

2. Planung – `plan`

4. Ausführung – `run`