podcast-kit

podcast-kit — agent skill

목적

에피소드를 게시하는 것은 한 가지 사실 집합에서 여러 개의 작은 복사 작업을 수행하는 과정입니다: 노트, YouTube 챕터, Podcasting 2.0 챕터 파일, 그리고 클립할 가치가 있는 순간을 찾는 작업. 이 도구는 하나의 에피소드 JSON을 받아 모든 것을 생성하므로, 사실은 정확히 한 번만 존재합니다. 순수 Python 표준 라이브러리; 로컬 전용; 에피소드 파일만 읽습니다.

이 도구의 정직성 핵심: 챕터 목록은 유효할 때만 내보냅니다 — 플레이어는 잘못된 목록을 조용히 무시하므로, 잘못된 내보내기는 내보내지 않는 것보다 더 나쁩니다. 그리고 오디오그램 점수는 대본 텍스트만으로 계산된, 어디를 먼저 살펴볼지에 대한 순위입니다. 특정 순간이 반드시 좋은 성과를 낼 것이라는 예측이 아니며, 계획은 렌더링된 오디오그램이 아닙니다.

사용 시기 / 사용하지 말아야 할 시기

다음과 같을 때 사용하세요:

• 에피소드가 하나의 에피소드 JSON으로 존재하거나 작성될 수 있는 경우: 마무리란 쇼 노트, YouTube 및 포드캐스트 앱용 챕터를 생성하고 무엇을 클립할지 결정하는 것을 의미합니다.
• 파이프라인에서 챕터 통과 여부 게이트가 필요한 경우: chapters exit 0 = 목록이 유효하고 내보내기가 출력에 존재함; exit 1 = 현재 상태로 챕터를 게시하지 마십시오.
• 편집자가 전체 녹음을 훑기 전에 들을 가치가 있는 다섯 개의 타임스탬프를 원하는 경우.

다음과 같을 때는 사용하지 마십시오:

• 전사(transcription)가 필요한 경우 — 대본은 여기서 입력입니다. 먼저 전사 도구로 세그먼트를 생성하세요.
• 오디오나 비디오 렌더링이 필요한 경우 — audiogram-plan은 계획(타임스탬프 + 단어 + 이유)입니다. 편집기나 렌더링 도구로 가져가세요.
• RSS, 호스팅 또는 배치 처리가 필요한 경우 — 이 도구는 의도적으로 한 번에 하나의 에피소드 파일을 마무리합니다.

명령어

모든 명령어는 위치 인수로 에피소드 파일을 받으며 --json을 지원합니다.

# 쇼 노트 — 마크다운(기본) 또는 일반 텍스트
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# 챕터 검증 + 내보내기 (유효하지 않으면 exit 1 및 내보내기 없음)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# 클립할 가치가 있는 순간 순위 매기기 (자격 미달 시 exit 1)
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

에피소드 필드: show (선택), episode (선택적 정수), title (show-notes에 필수), published (선택, 그대로 출력), duration_seconds (chapters에 필수; 초 또는 타임스탬프 문자열), summary (show-notes에 필수), guests — {"name", "role"?} 목록, links — {"label", "url"} 목록, chapters — {"start", "title"} 목록, transcript — {"start", "end", "speaker"?, "text"} 목록. 타임스탬프는 초(754), "M:SS" 또는 "H:MM:SS" 형식을 모든 곳에서 허용합니다. 파일은 매 읽기 시 검증됩니다. 구조적 문제(필드 누락, 잘못된 타임스탬프, 시작보다 먼저 끝나는 세그먼트, duration을 초과하는 세그먼트)는 문제가 되는 챕터나 세그먼트를 명시하는 exit 2 오류입니다.

챕터 검증 (정확한 규칙)

문제 (exit 1, 내보내기 없음): 첫 번째 챕터가 0에서 시작하지 않음; 시작이 이전 시작보다 엄격히 크지 않음; 시작이 duration_seconds 이상임 (duration - 1에서 시작은 유효); 제목이 비어 있음.

경고 (보고되지만 내보내기는 생성됨): 챕터가 3개 미만; 챕터 길이가 10초 미만. 둘 다 Podcasting 2.0이 아닌 YouTube의 규칙입니다 — 내보내기는 어느 쪽이든 유효하며, YouTube는 무시할 수 있습니다.

내보내기: YouTube 라인은 MM:SS 제목 (또는 에피소드가 1시간 이상이면 H:MM:SS) 형식입니다. Podcasting 2.0은 {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} 형식입니다. 각 챕터의 endTime은 다음 챕터의 startTime이며, 마지막 챕터의 endTime은 duration입니다.

오디오그램 점수 (정확한 규칙)

대본 세그먼트당, 텍스트만을 기준으로:

• 물음표: 각 +2, 최대 +4
• 숫자 (숫자 연속, 예: 18, 1,900): 각 +2, 최대 +4
• 느낌표: 각 +1, 최대 +2
• 강조 구문 — 고정 목록 "the truth is", "biggest mistake", "nobody tells you", "everyone gets wrong", "never", "always", "secret", "myth" (전체 단어, 대소문자 구분 없음): 각 +3, 최대 +6
• 세그먼트 길이 15~60초 포함: +2

최소 점수: 세그먼트는 목록에 포함되려면 총 5점이 필요합니다. 정렬: 점수 내림차순, 동점은 가장 빠른 시작 순. --top N은 목록을 제한합니다 (0 또는 음수 = 모든 자격 충족 세그먼트). 나열된 각 순간은 발견된 실제 신호와 함께 이유를 출력합니다. 이 도구에서는 이유 없는 점수가 존재하지 않습니다.

출력 JSON 스키마 (--json)

공통 필드: tool ("podcast-kit"), version, command, episode_file (파일 이름).

show-notes: title, format ("markdown" 또는 "text"), notes — 텍스트 뷰가 출력하는 것과 정확히 같은 렌더링된 노트 문자열. chapters: title, duration_seconds, valid (bool), problems (문자열 목록), warnings (문자열 목록), chapters — 각 {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (내보내기 텍스트, 유효하지 않으면 null), podcasting20 (내보내기 객체, 유효하지 않으면 null). audiogram-plan: title, segments_scanned, floor (5), moments — 각 {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. 자격을 충족하는 세그먼트가 없으면 moments는 []이고 note 필드가 최소 점수를 넘지 못했음을 설명합니다 (exit 1).

오류 발생 시, stdout은 단일 객체: {"error": "<메시지>"}이며 exit 코드는 2입니다. --json 모드에서는 argparse 사용법 오류도 포함됩니다. 일반 텍스트나 traceback이 출력되지 않습니다.

종료 코드

• 0 — 명령어 성공; audiogram-plan의 경우 최소 하나의 세그먼트가 최소 점수를 넘음.
• 1 — 결과 발견: chapters에서 검증 문제 발견(내보내기 생성되지 않음), 또는 audiogram-plan에서 클립할 가치가 있는 세그먼트를 찾지 못함. 어느 쪽도 충돌이 아닙니다 — 발견 결과에 따라 조치하세요.
• 2 — 오류: 에피소드 파일이 없거나 유효한 JSON이 아님, 필수 필드 누락, 잘못된 타임스탬프, 잘못된 챕터 또는 세그먼트, 유효하지 않은 플래그. 실패한 실행의 출력 사실을 인용해서는 안 됩니다.

agent가 반드시 준수해야 할 한계 및 정직성 규칙

• 잘못된 챕터는 아무것도 내보내지 않습니다. chapters가 exit 1로 종료될 때, JSON 출력의 chapters 배열에서 내보내기를 재구성하여 게시하지 마십시오 — 나열된 문제가 바로 플레이어가 이를 무시하는 이유입니다. 에피소드 파일을 수정하고 다시 실행하세요.
• 경고는 문제가 아닙니다. 경고가 있는 유효한 목록은 게시될 수 있습니다. YouTube는 챕터를 표시하지 않을 수 있지만(너무 적거나 하나가 너무 짧음) 포드캐스트 앱에서는 표시될 것이라고 명확히 말하세요.
• 점수는 예측이 아닙니다. 순간을 "텍스트 신호에 의해 1순위로 선정됨"이라고 보고하고, 절대 "최고의 순간" 또는 "좋은 성과를 낼 클립"이라고 하지 마십시오. 이 도구는 녹음을 들을 수 없습니다. 전달 방식에 따라 낮은 점수의 세그먼트가 올바른 클립이 될 수 있으며, 계획은 그렇게 말합니다.
• audiogram-plan의 exit 1은 빈 에피소드를 의미하지 않습니다. 순위가 매겨진 신호를 가진 세그먼트가 없다는 뜻입니다. "좋은 순간이 없다"고 보고할 때는 이 도구가 텍스트만 읽는다는 조건을 반드시 함께 명시하세요.
• 계획은 파일이 아닙니다. audiogram-plan은 타임스탬프와 텍스트를 생성합니다. 렌더링 도구가 실제로 계획에서 오디오그램을 만들기 전까지는 오디오그램이 존재한다고 사용자에게 알리지 마십시오.
• 로컬 전용: 이 도구는 명령줄에 지정된 에피소드 파일만 읽고 아무 곳에도 데이터를 보내지 않습니다.