podcast-kit — Agent-Fertigkeit

Was macht podcast-kit — Agent-Fertigkeit?

Zweck

Die Veröffentlichung einer Episode besteht aus einer Reihe kleiner Kopierarbeiten ausgehend von einem Satz Fakten: die Notizen, die YouTube-Kapitel, die Podcasting-2.0-Kapiteldatei und die Suche nach dem clip-würdigen Moment. Dieses Tool nimmt EINE Episoden-JSON und erzeugt alle daraus, sodass die Fakten genau einmal existieren. Reine Python-Standardbibliothek; nur lokal; die Episodendatei ist das Einzige, was es liest.

Der Ehrlichkeitskern dieses Tools: Eine Kapitelliste wird nur exportiert, wenn sie gültig ist – Player ignorieren defekte Listen stillschweigend, daher ist die Ausgabe einer defekten Liste schlimmer als gar keine Ausgabe – und ein Audiogramm-Score ist eine Rangfolge, wo man zuerst suchen sollte, berechnet allein aus dem Transkripttext. Es ist niemals eine Vorhersage, dass ein Moment performen wird, und ein Plan ist niemals ein gerendertes Audiogramm.

Wann verwenden / nicht verwenden

Verwenden, wenn:

• Eine Episode als (oder geschrieben als) eine Episoden-JSON vorliegt: Die Fertigstellung bedeutet, Shownotes, Kapitel für YouTube und Podcast-Apps zu erstellen und zu entscheiden, was geclippt werden soll.
• Eine Pipeline ein Ja/Nein-Kapitel-Gate benötigt: chapters Exit 0 = die Liste ist gültig und die Exporte befinden sich in der Ausgabe; Exit 1 = veröffentlichen Sie die Kapitel nicht so, wie sie sind.
• Ein Redakteur die fünf Zeitstempel hören möchte, bevor er eine gesamte Aufnahme durchspult.

NICHT verwenden, wenn:

• Sie eine Transkription benötigen – das Transkript ist hier eine Eingabe. Erstellen Sie zuerst mit einem Transkriptionstool Segmente.
• Sie Audio oder Video rendern müssen – audiogramm-plan ist ein Plan (Zeitstempel + Wörter + Gründe). Bringen Sie ihn zu einem Editor oder einem Rendering-Tool.
• Sie RSS, Hosting oder Batch-Verarbeitung benötigen – dieses Tool bearbeitet bewusst eine Episodendatei nach der anderen.

Befehle

Jeder Befehl nimmt die Episodendatei als positionsabhängiges Argument und unterstützt --json.

# Shownotes — Markdown (Standard) oder reiner Text
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# Kapitel validieren + exportieren (Exit 1 + kein Export bei Ungültigkeit)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# Die clip-würdigen Momente bewerten (Exit 1, wenn keiner die Mindestpunktzahl erreicht)
python3 src/podcast_kit.py audiogramm-plan EPISODE.json \
    [--top 5]

Episodenfelder: show (optional), episode (optional int), title (erforderlich für show-notes), published (optional, wird unverändert ausgegeben), duration_seconds (erforderlich für chapters; Sekunden oder ein Zeitstempel-String), summary (erforderlich für show-notes), guests — Liste von {"name", "role"?}, links — Liste von {"label", "url"}, chapters — Liste von {"start", "title"}, transcript — Liste von {"start", "end", "speaker"?, "text"}. Zeitstempel akzeptieren überall Sekunden (754), "M:SS" oder "H:MM:SS". Die Datei wird bei jedem Lesen validiert; strukturelle Probleme (fehlende Felder, falsche Zeitstempel, ein Segment, das endet, bevor es beginnt, ein Segment, das über die Dauer hinausgeht) sind Exit-2-Fehler, die das fehlerhafte Kapitel oder Segment benennen.

Kapitelvalidierung (exakt)

Probleme (Exit 1, kein Export): Das erste Kapitel beginnt nicht bei 0; ein Start liegt nicht strikt nach dem vorherigen Start; ein Start liegt bei oder nach duration_seconds (ein Start bei Dauer − 1 ist gültig); ein Titel ist leer.

Warnungen (gemeldet, Export wird dennoch erstellt): Weniger als 3 Kapitel; ein Kapitel kürzer als 10 Sekunden. Beides sind YouTube-Regeln, nicht Podcasting 2.0 – der Export ist in beiden Fällen gültig, YouTube ignoriert es möglicherweise.

Exporte: YouTube-Zeilen sind MM:SS Titel (oder H:MM:SS, wenn die Episode eine Stunde oder länger läuft). Podcasting 2.0 ist {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} – die endTime jedes Kapitels ist die startTime des nächsten Kapitels, und die endTime des letzten Kapitels ist die Dauer.

Der Audiogramm-Score (exakt)

Pro Transkriptsegment, nur aus seinem Text:

• Fragezeichen: +2 pro Stück, gedeckelt bei +4
• Zahlen (Ziffernfolgen, z.B. 18, 1.900): +2 pro Stück, gedeckelt bei +4
• Ausrufezeichen: +1 pro Stück, gedeckelt bei +2
• Starke Phrasen – die feste Liste "the truth is", "biggest mistake", "nobody tells you", "everyone gets wrong", "never", "always", "secret", "myth" (ganze Wörter, Groß-/Kleinschreibung nicht beachtet): +3 pro Stück, gedeckelt bei +6
• Segmentlänge 15–60 Sekunden inklusive: +2

Mindestpunktzahl: Ein Segment benötigt insgesamt 5, um gelistet zu werden. Reihenfolge: absteigender Score, Gleichstände nach frühestem Start. --top N begrenzt die Liste (0 oder negativ = alle qualifizierenden Segmente). Jeder gelistete Moment druckt seine Gründe mit den tatsächlich gefundenen Signalen – ein Score ohne Gründe existiert in diesem Tool nicht.

Ausgabe-JSON-Schema (--json)

Gemeinsame Felder: tool ("podcast-kit"), version, command, episode_file (Dateiname).

show-notes: title, format ("markdown" oder "text"), notes — die gerenderten Notizen als ein String, genau das, was die Textansicht druckt. chapters: title, duration_seconds, valid (bool), problems (Liste von Strings), warnings (Liste von Strings), chapters — jedes {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (der Export-Text oder null bei Ungültigkeit), podcasting20 (das Export-Objekt oder null bei Ungültigkeit). audiogramm-plan: title, segments_scanned, floor (5), moments — jedes {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. Wenn kein Segment die Mindestpunktzahl erreicht, ist moments [] und ein note-Feld erklärt, dass die Mindestpunktzahl nicht erreicht wurde (Exit 1).

Bei einem Fehler ist stdout ein einzelnes Objekt: {"error": "<message>"} mit Exit-Code 2 – einschließlich argparse-Nutzungsfehlern im --json-Modus. Niemals reiner Text, niemals ein Traceback.

Exit-Codes

• 0 — Befehl erfolgreich; für audiogramm-plan hat mindestens ein Segment die Mindestpunktzahl erreicht.
• 1 — Ein Hinweis: chapters hat Validierungsprobleme festgestellt (es wurde kein Export erstellt), oder audiogramm-plan hat kein Segment gefunden, das es wert ist, geclippt zu werden. Keines davon ist ein Absturz – handeln Sie entsprechend dem Hinweis.
• 2 — FEHLER: Episodendatei fehlt oder ist kein gültiges JSON, ein erforderliches Feld fehlt, ein fehlerhafter Zeitstempel, ein fehlerhaftes Kapitel oder Segment, ein ungültiges Flag. Aus einem fehlgeschlagenen Lauf dürfen keine Ausgabefakten zitiert werden.

Grenzen und Ehrlichkeitsregeln, die der Agent respektieren muss

• Ungültige Kapitel exportieren nichts. Wenn chapters mit Exit 1 beendet wird, rekonstruieren Sie keinen Export aus dem chapters-Array in der JSON-Ausgabe und veröffentlichen Sie ihn – die aufgeführten Probleme sind genau der Grund, warum Player ihn ignorieren würden. Korrigieren Sie die Episodendatei und führen Sie sie erneut aus.
• Warnungen sind keine Probleme. Eine gültige Liste mit Warnungen darf veröffentlicht werden; sagen Sie deutlich, dass YouTube die Kapitel möglicherweise nicht anzeigt (zu wenige oder eines zu kurz), Podcast-Apps jedoch schon.
• Ein Score ist keine Vorhersage. Melden Sie einen Moment als „nach den Textsignalen an erster Stelle bewertet