{"id":50797817,"url":"https://github.com/modem-dev/podguy","last_synced_at":"2026-06-12T16:01:37.784Z","repository":{"id":358090164,"uuid":"1239869762","full_name":"modem-dev/podguy","owner":"modem-dev","description":"Agent-driven post-production workflow for video podcasts","archived":false,"fork":false,"pushed_at":"2026-06-10T16:31:03.000Z","size":263,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T18:13:47.627Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modem-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T14:25:26.000Z","updated_at":"2026-06-10T17:47:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/modem-dev/podguy","commit_stats":null,"previous_names":["modem-dev/podguy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/modem-dev/podguy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fpodguy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fpodguy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fpodguy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fpodguy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modem-dev","download_url":"https://codeload.github.com/modem-dev/podguy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fpodguy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34251773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T16:01:36.436Z","updated_at":"2026-06-12T16:01:37.776Z","avatar_url":"https://github.com/modem-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# podguy\n\nPi-first post-production tooling for podcast and video-podcast editors who want transcripts, chapters, clip candidates, cuts, and social review exports from local media.\n\n[![CI](https://github.com/modem-dev/podguy/actions/workflows/ci.yml/badge.svg)](https://github.com/modem-dev/podguy/actions/workflows/ci.yml)\n\n## What it does\n\n- Launches `pi` with podcast-specific skills, prompts, and a startup widget.\n- Transcribes local audio/video files with Whisper-compatible backends.\n- Prepares long transcripts into timecoded chunks for editorial review.\n- Scans video episodes for likely interstitials and non-host inserts.\n- Generates chapters, clip candidates, cut reports, show notes, quotes, and proper noun checks.\n- Cuts selected highlight ranges into review exports for TikTok, Reels, YouTube Shorts, trailers, or social posts.\n\nGenerated transcripts, scans, thumbnails, notes, and clip exports go under gitignored `dist/` by default.\n\n## Install\n\nClone the repo and install the local Node tooling:\n\n```bash\ngit clone https://github.com/modem-dev/podguy.git\ncd podguy\nnpm install\n```\n\nInstall the required system tools:\n\n```bash\nbrew install uv ffmpeg\n```\n\nNotes:\n\n- `ffmpeg` is used for fixtures, transcription backends, and clip cutting.\n- `uv` runs the Python scripts and optional transcription dependency groups.\n- The video scanner is macOS-only and uses Swift / AVFoundation / Vision.\n\nBefore first use, authenticate pi with `/login` or your usual provider API key setup.\n\nSet up a real transcription backend when you are ready to transcribe episodes:\n\n```bash\nuv sync --group transcribe-mlx      # Apple Silicon\nuv sync --group transcribe-faster   # Cross-platform\nuv sync --group transcribe-whisper  # OpenAI Whisper package\n```\n\n## Quick start\n\nCreate an optional show profile:\n\n```bash\ncp podguy.example.toml podguy.toml\n```\n\nStart podguy from the repo root:\n\n```bash\n./podguy\n```\n\nThen ask pi for a concrete episode task:\n\n```text\nAnalyze \"episode-006-draft.mp4\" as ep006.\n\nGenerate chapters for ep006 in timestamp-title format.\n\nFind likely TikTok/Shorts clips for ep006 and cut vertical review exports.\n```\n\nFor broad requests, podguy should clarify between:\n\n- **quick pass**: optional video scan + transcript + prepared transcript artifacts + short summary\n- **full review**: quick pass + chapters + clips + cuts + show notes + quotes + proper noun review\n\n## Common workflows\n\n### Scan a video\n\n```bash\nswift scripts/scan_podcast.swift \"episode-006-draft.mp4\" dist/analysis/ep006/scan 0.5\nopen dist/analysis/ep006/scan/report.html\n```\n\nKey outputs:\n\n- `interstitial_candidates.csv`\n- `non_host_candidates.csv`\n- `report.html`\n- `thumbs/`\n\nScanner results are heuristic review aids, not exact edit points.\n\n### Transcribe media\n\n```bash\nuv run python scripts/transcribe_video.py --list-backends\n\nuv run --group transcribe-mlx python scripts/transcribe_video.py \\\n  \"episode-006-draft.mp4\" \\\n  dist/analysis/ep006/transcript \\\n  --backend mlx-whisper\n```\n\nKey outputs:\n\n- `segments.json`\n- `transcript.txt`\n- `transcript.srt`\n- `transcript.vtt`\n- `summary.txt`\n\nUse `--backend mock` only for tests and setup validation.\n\n### Prepare transcript artifacts\n\n```bash\nuv run python scripts/prepare_transcript_analysis.py \\\n  dist/analysis/ep006/transcript \\\n  --output-dir dist/analysis/ep006 \\\n  --slug ep006 \\\n  --plain-output-names\n```\n\nKey outputs:\n\n- `dist/analysis/ep006/transcript_chunks.md`\n- `dist/analysis/ep006/transcript_index.json`\n\nThese are the main inputs for chaptering and editorial analysis.\n\n### Cut selected clips\n\nAfter pi writes `dist/analysis/ep006/clips.md`, cut original-aspect review exports:\n\n```bash\nuv run python scripts/cut_clips.py \\\n  \"episode-006-draft.mp4\" \\\n  dist/analysis/ep006/clips.md \\\n  dist/analysis/ep006/clips/cuts\n```\n\nFor simple vertical Shorts/TikTok/Reels review exports:\n\n```bash\nuv run python scripts/cut_clips.py \\\n  \"episode-006-draft.mp4\" \\\n  dist/analysis/ep006/clips.md \\\n  dist/analysis/ep006/clips/shorts \\\n  --aspect vertical \\\n  --pad-start 1 \\\n  --pad-end 1\n```\n\nThe cutter writes generated media plus `manifest.json`. Vertical and square modes use center-crop framing, so treat them as review exports unless the framing has been checked.\n\n### Download real sample media\n\nUse the Cordkillers open-license video-podcast excerpt for local evaluation:\n\n```bash\nscripts/download_sample_media.sh\n```\n\nThis writes to:\n\n```text\ndist/test-fixtures/open-license/cordkillers-572/\n```\n\nThe default sample is a 3m50s excerpt from `00:08:00` of Cordkillers 572, licensed CC BY-SA 4.0. The range includes multiple podcast layouts, lower thirds, chat/sidebar graphics, a Patreon bumper, and an outro/interstitial card. The script writes `ATTRIBUTION.md` next to the generated media.\n\n## Configuration\n\n`podguy.toml` lets you define show-specific context without changing the workflow:\n\n```toml\nshow_name = \"Example Podcast\"\nshow_slug = \"example\"\nhosts = [\"Host One\", \"Host Two\"]\ntone = \"curious, direct, practical\"\naudience = \"builders and technical operators\"\nchapter_style = \"concise descriptive titles\"\npreferred_review = \"quick pass\"\n```\n\n`podcast.toml` is also accepted as a compatible profile name.\n\n## Project layout\n\n- [`podguy`](podguy): launcher for pi with repo-local skills, prompts, and startup extension.\n- [`src/podguy-post-production/SKILL.md`](src/podguy-post-production/SKILL.md): main editorial workflow skill.\n- [`src/podguy-clip-cutter/SKILL.md`](src/podguy-clip-cutter/SKILL.md): social clip export workflow skill.\n- [`src/podguy-startup.ts`](src/podguy-startup.ts): pi startup widget.\n- [`prompts/`](prompts): optional prompt shortcuts.\n- [`scripts/`](scripts): deterministic scanner, transcript, prep, fixture, sample, and clip-cutting tools.\n- [`tests/`](tests): smoke tests wrapped by Vitest.\n- [`AGENTS.md`](AGENTS.md): repo guidance for coding agents.\n\n## Development\n\nRun the full validation surface:\n\n```bash\nnpm run format:check\nnpm run lint\nnpm run typecheck\nnpm test\n```\n\nRun the shell smoke tests directly:\n\n```bash\nbash scripts/test.sh\n```\n\nCI runs the same checks on macOS because the scanner depends on macOS media APIs.\n\n## Contributing\n\nSmall, focused PRs are welcome. Before opening a PR, run the validation commands above.\n\nFor workflow or heuristic changes, include:\n\n- media type and OS/backend details\n- expected vs actual output\n- relevant transcript, scan, or manifest paths when available\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for user-visible changes and [`AGENTS.md`](AGENTS.md) for repo maintenance guidance.\n\n## Security\n\nThis repo does not have a published security policy yet. If you find a sensitive issue, do not open a public issue. Contact the maintainers privately first.\n\n## Sponsor\n\nSponsored by [Modem](https://modem.dev?utm_source=github\u0026utm_medium=oss\u0026utm_campaign=oss_podguy\u0026utm_content=readme_footer).\n\n\u003ca href=\"https://modem.dev?utm_source=github\u0026utm_medium=oss\u0026utm_campaign=oss_podguy\u0026utm_content=readme_footer\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://modem.dev/images/logo/svg/modem-combined-white.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://modem.dev/images/logo/svg/modem-combined-black.svg\"\u003e\n    \u003cimg src=\"https://modem.dev/images/logo/svg/modem-combined-black.svg\" alt=\"Modem\" width=\"220\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n\n## Support\n\nUse [GitHub issues](https://github.com/modem-dev/podguy/issues) for bugs, questions, and workflow discussion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodem-dev%2Fpodguy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodem-dev%2Fpodguy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodem-dev%2Fpodguy/lists"}