AGENTS.md · diff

git:20260317.b219538 to git:20260317.be6ec32

1 added, 0 removed. Audit A to A.

# Agent Instructions

## Goal

Use this repository to export a podcast transcript as:

- `<title> [<id>].txt`

- `<title> [<id>].meta.json`

The user will usually give you a link or a plain episode title.

## Required First Steps

Before the first real transcript run on a machine:

```bash

python3 -m pip install -r requirements.txt

python3 scripts/podcast_transcript_txt.py --doctor

```

Only continue to the real transcript command when `--doctor` exits with code `0`.

If `--doctor` fails:

1. Stop the transcript run.

2. Show the failing `DOCTOR` lines.

3. Tell the user to fix the missing dependency or permission issue first.

## Real Transcript Command

```bash

python3 scripts/podcast_transcript_txt.py \

--input "<episode-link-or-title>" \

--out-dir "<output-dir>"

```

If the input is likely to require audio fallback, you may use:

```bash

python3 scripts/podcast_transcript_txt.py \

--input "<episode-link-or-title>" \

--asr-model small \

--out-dir "<output-dir>"

```

Use `small` by default unless the user explicitly wants the slower `medium` model.

## Output Contract

Treat the run as successful only when stdout contains:

- `OK <txt-path>`

- `META <meta-path>`

After success:

1. Return the generated `.txt` path.

2. Return the generated `.meta.json` path.

3. Briefly state which resolver path was used if you inspect the meta file.

4. Remind the user that the transcript is a draft and should get one proofreading pass before publishing.

## Failure Contract

If stdout/stderr contains:

- `FAIL <input> <error>`

then do not pretend the run worked.

Return:

1. the exact failed input,

2. the exact error,

3. the next concrete fix.

## Notes

- This repo is designed for direct agent use after dependency install and `--doctor` success.

+ - For YouTube links, try the built-in chain: official transcript -> subtitles -> local audio ASR fallback.

- Do not assume YouTube subtitles or official transcripts always exist.

- Local ASR fallback depends on `faster-whisper`.

- Do not describe the repo as publish-ready transcript quality; it produces a working draft.