jasveerai88/podcast-kit

podcast-kit — compétence agent

Objectif

Publier un épisode, c'est une série de petits travaux de copie à partir d'un ensemble de faits : les notes, les chapitres YouTube, le fichier de chapitres Podcasting 2.0, et la recherche du moment clippable. Cet outil prend UN fichier JSON d'épisode et produit tout cela, de sorte que les faits n'existent qu'une seule fois. Bibliothèque standard Python pure ; uniquement local ; le fichier épisode est la seule chose qu'il lit.

Le cœur d'honnêteté de cet outil : une liste de chapitres n'est exportée que lorsqu'elle est valide — les lecteurs ignorent silencieusement les listes brisées, donc distribuer un export brisé est pire que de n'en distribuer aucun — et un score d'audiogramme est un classement des endroits où regarder en premier, calculé à partir du seul texte de la transcription. Ce n'est jamais une prédiction qu'un moment sera performant, et un plan n'est jamais un audiogramme rendu.

Quand utiliser / ne pas utiliser

À utiliser quand :

• Un épisode existe (ou peut être écrit) sous forme d'un seul JSON d'épisode : le terminer signifie produire des notes d'émission, des chapitres pour YouTube et les applications de podcast, et décider quoi clipper.
• Un pipeline a besoin d'une porte oui/non pour les chapitres : chapters sortie 0 = la liste est valide et les exports sont dans la sortie ; sortie 1 = ne publiez pas les chapitres en l'état.
• Un éditeur veut les cinq horodatages qui valent la peine d'être écoutés avant de parcourir tout un enregistrement.

Ne PAS utiliser quand :

• Vous avez besoin de transcription — la transcription est une entrée ici. Produisez d'abord les segments avec un outil de transcription.
• Vous avez besoin d'audio ou de vidéo rendu — audiogram-plan est un plan (horodatages + mots + raisons). Apportez-le à un éditeur ou un outil de rendu.
• Vous avez besoin de RSS, d'hébergement ou de traitement par lots — cet outil termine un fichier épisode à la fois, délibérément.

Commandes

Chaque commande prend le fichier épisode comme argument positionnel et prend en charge --json.

# Notes d'émission — Markdown (par défaut) ou texte brut
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# Valider + exporter les chapitres (sortie 1 + pas d'export en cas d'invalidité)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# Classer les moments dignes d'être clippés (sortie 1 quand aucun ne se qualifie)
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

Champs de l'épisode : show (optionnel), episode (optionnel int), title (obligatoire pour show-notes), published (optionnel, affiché tel quel), duration_seconds (obligatoire pour chapters ; secondes ou chaîne d'horodatage), summary (obligatoire pour show-notes), guests — liste de {"name", "role"?}, links — liste de {"label", "url"}, chapters — liste de {"start", "title"}, transcript — liste de {"start", "end", "speaker"?, "text"}. Les horodatages acceptent les secondes (754), "M:SS" ou "H:MM:SS" partout. Le fichier est validé à chaque lecture ; les problèmes structurels (champs manquants, mauvais horodatages, un segment qui se termine avant de commencer, un segment qui dépasse la durée) sont des erreurs de sortie 2 qui nomment le chapitre ou le segment concerné.

Validation des chapitres (exacte)

Problèmes (sortie 1, pas d'export) : le premier chapitre ne commence pas à 0 ; un début n'est pas strictement après le début précédent ; un début est à ou après duration_seconds (un début à durée − 1 est valide) ; un titre est vide.

Avertissements (signalés, export quand même produit) : moins de 3 chapitres ; un chapitre plus court que 10 secondes. Les deux sont les règles de YouTube, pas celles de Podcasting 2.0 — l'export est valide de toute façon, YouTube peut l'ignorer.

Exports : Les lignes YouTube sont MM:SS Titre (ou H:MM:SS quand l'épisode dure une heure ou plus). Podcasting 2.0 est {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} — l'endTime de chaque chapitre est le startTime du chapitre suivant, et l'endTime du dernier chapitre est la durée.

Le score d'audiogramme (exact)

Par segment de transcription, à partir de son texte uniquement :

• points d'interrogation : +2 chacun, plafonné à +4
• nombres (suites de chiffres, ex. 18, 1 900) : +2 chacun, plafonné +4
• points d'exclamation : +1 chacun, plafonné à +2
• expressions fortes — la liste fixe "the truth is", "biggest mistake", "nobody tells you", "everyone gets wrong", "never", "always", "secret", "myth" (mot entier, insensible à la casse) : +3 chacun, plafonné +6
• longueur du segment entre 15 et 60 secondes inclus : +2

Seuil : un segment a besoin d'un total de 5 pour être listé. Ordre : score décroissant, égalités par début le plus tôt. --top N limite la liste (0 ou négatif = tous les segments qualifiés). Chaque moment listé affiche ses raisons avec les signaux réels trouvés — un score sans raisons n'existe pas dans cet outil.

Schéma JSON de sortie (--json)

Champs communs : tool ("podcast-kit"), version, command, episode_file (nom du fichier).

show-notes : title, format ("markdown" ou "text"), notes — les notes rendues sous forme d'une chaîne, exactement ce que affiche la vue texte. chapters : title, duration_seconds, valid (bool), problems (liste de chaînes), warnings (liste de chaînes), chapters — chaque {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (le texte d'export, ou null lorsqu'invalide), podcasting20 (l'objet d'export, ou null lorsqu'invalide). audiogram-plan : title, segments_scanned, floor (5), moments — chaque {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. Lorsque aucun segment ne se qualifie, moments est [] et un champ note explique que le seuil n'a pas été atteint (sortie 1).

En cas d'erreur, stdout est un objet unique : {"error": "<message>"} avec le code de sortie 2 — y compris les erreurs d'utilisation argparse en mode --json. Jamais de texte brut, jamais de traceback.

Codes de sortie

• 0 — commande réussie ; pour audiogram-plan, au moins un segment a franchi le seuil.
• 1 — constatation : chapters a trouvé des problèmes de validation (aucun export n'a été produit), ou audiogram-plan n'a trouvé aucun segment digne d'être clippé. Aucun des deux n'est un crash — agissez sur la constatation.
• 2 — ERREUR : fichier épisode manquant ou JSON non valide, un champ obligatoire manquant, un mauvais horodatage, un chapitre ou segment mal formé, un indicateur invalide. Aucun fait de sortie ne doit être cité à partir d'une exécution échouée.

Limites et règles d'honnêteté que l'agent doit respecter

• Les chapitres invalides n'exportent rien. Lorsque chapters se termine avec le code 1, ne reconstruisez pas un export à partir du tableau chapters dans la sortie JSON et ne le publiez pas — les problèmes listés sont exactement la raison pour laquelle les lecteurs l'ignoreraient. Corrigez le fichier épisode et ré-exécutez.
• Les avertissements ne sont pas des problèmes. Une liste valide avec des avertissements peut être publiée ; dites clairement que YouTube pourrait ne pas afficher les chapitres (trop peu, ou un trop court) alors que les applications de podcast le feront.
• Un score n'est pas une prédiction. Rapportez un moment comme « classé premier par les signaux textuels », jamais comme « le meilleur moment » ou « le clip qui va performer ». L'outil ne peut pas entendre l'enregistrement ; la prestation peut faire d'un segment faiblement noté le bon clip, et le plan le dit.
• La sortie 1 de audiogram-plan n'est pas un épisode vide. Cela signifie qu'aucun segment ne portait les signaux classés. Ne rapportez jamais cela comme « aucun bon moment » sans la précision que l'outil ne lit que le texte.
• Un plan n'est pas un fichier. audiogram-plan produit des horodatages et du texte. Ne dites jamais à l'utilisateur qu'un audiogramme existe tant qu'un outil de rendu n'en a pas réellement créé un à partir du plan.
• Local uniquement : l'outil ne lit que le fichier épisode nommé sur la ligne de commande et n'envoie rien nulle part.