Metadata-Version: 2.4
Name: amagi-listen
Version: 0.1.0
Summary: Let Claude hear a podcast or meeting recording: a chaptered, timestamped transcript from any local file or URL.
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
License: MIT
Project-URL: Homepage, https://github.com/amagilabs/amagi-listen
Project-URL: Source, https://github.com/amagilabs/amagi-listen
Project-URL: Issues, https://github.com/amagilabs/amagi-listen/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: av<19,>=15.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# amagi-listen

Give Claude a podcast, meeting recording, or any audio/video file and get
back a transcript it can actually use — chaptered, timestamped, and split
into speaker turns.

![demo](assets/demo.gif)

amagi-listen downloads the audio if you give it a URL (same yt-dlp pipeline
as amagi-watch), transcribes it locally with faster-whisper, splits the
transcript into chapters at the longest pauses, and optionally marks
probable speaker turn breaks. Everything lands in one `index.md`.

Everything runs locally. There are no API keys and nothing leaves your
machine except yt-dlp downloading the source, if you pass a URL.

## Install

```
pipx install amagi-listen
```

You also need these on your PATH:

- [yt-dlp](https://github.com/yt-dlp/yt-dlp) (only needed for URL input)
- [ffmpeg](https://ffmpeg.org/)

Python 3.10 or newer. faster-whisper is installed as a dependency; the
first transcription downloads the Whisper model you pick.

## Usage

```
amagi-listen <file-or-url> [-o OUTDIR] [--model small] [--chapters 6] [--speakers] [--pause-threshold 1.5]
```

| Option | What it does |
|---|---|
| `-o`, `--outdir` | Where run folders go (default `amagi_listen_out`) |
| `--model` | faster-whisper size: `tiny`, `base`, `small` (default), `medium`, `large-v3` |
| `--chapters` | Target number of chapters, split at the longest pauses (default 6) |
| `--speakers` | Mark speaker turn breaks (pause-length heuristic — see Limitations) |
| `--pause-threshold` | Seconds of silence that counts as a new turn (default 1.5) |
| `--keep-audio` | Keep the downloaded/normalized audio file |

Examples:

```
# A local meeting recording
amagi-listen ./standup_2026-10-19.m4a -o runs --speakers

# A podcast episode by URL
amagi-listen "https://example.com/episode-42" -o runs --chapters 8
```

The last line of stdout is the path to the run folder.

## Output

Each run writes `<outdir>/<name>/`:

- `index.md`: the file to read. Chapters in time order, each with an
  extractive title (the first ~12 words of its first line — not an LLM
  summary) and its timestamped lines.
- `transcript.md`: the flat, unchaptered transcript.
- `metadata.json`: title, source, duration, and segment/chapter counts.

Real output from a short synthesized two-speaker test clip:

```markdown
# demo_meeting

- Source: demo_meeting.wav
- Speaker turns: pause-length heuristic, not voice identification

## Chapters

### Chapter 1 — [00:00] Welcome to the AmagiLabs Weekly Sync.

**[00:00]** Speaker A: Welcome to the AmagiLabs Weekly Sync.
**[00:03]** Speaker A: Today we are covering three topics.
**[00:08]** Speaker A: First, the amagi screen launch went well.

### Chapter 2 — [00:11] Second, amagi listen is almost ready to ship.

**[00:11]** Speaker A: Second, amagi listen is almost ready to ship.
```

(That test clip used one synthesized voice for both halves, split only by
a silence gap — which is why it's one speaker label throughout. See
Limitations below.)

## Use it as a Claude Code skill

The repo includes a `SKILL.md`. Copy it into your skills folder:

```
mkdir -p ~/.claude/skills/amagi-listen
cp SKILL.md ~/.claude/skills/amagi-listen/SKILL.md
```

When you paste an audio file or URL and ask what was said, Claude runs
`amagi-listen` and reads `index.md`.

## Limitations

- `--speakers` is a pause-length heuristic, not voice-based diarization.
  It has no model of who is speaking — only that a long-enough silence
  probably means a new turn. Two people talking without a pause between
  them get mislabeled as one speaker. Treat the labels as approximate.
- Chapter titles are extractive (the first words of the chapter), not
  generated summaries — amagi-listen doesn't call an LLM.
- Whisper on CPU runs at roughly real time or slower with `small`.
- URL downloads depend on yt-dlp supporting the site and the content
  being publicly accessible.

## Related AmagiLabs projects

- [amagi-watch](https://github.com/amagilabs/amagi-watch) — give Claude a
  video URL and get back a transcript + key frames.
- [amagi-screen](https://github.com/amagilabs/amagi-screen) — give Claude
  a screen recording and get back a frame timeline.
- [legal-review-skills](https://github.com/amagilabs/legal-review-skills)
- More tools at [github.com/amagilabs](https://github.com/amagilabs).

If amagi-listen saves you from replaying a two-hour recording, a star
helps other people find it.

## Legal

Only download recordings you have the right to download. Follow each
platform's terms of service and respect copyright. amagi-listen is for
personal research and analysis.

## License

MIT. Copyright (c) 2026 AmagiLabs (Amagisolutionsgroup, Inc.). See [LICENSE](LICENSE).

Built by [AmagiLabs](https://amagilabs.ai).
