Metadata-Version: 2.4
Name: deep-transcribe
Version: 0.1.14
Summary: High-quality transcription, formatting, and analysis of videos and podcasts
Project-URL: Repository, https://github.com/jlevy/deep-transcribe
Author-email: Joshua Levy <joshua@cal.berkeley.edu>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.13
Requires-Dist: frontmatter-format<0.5,>=0.4.0
Requires-Dist: kash-media<0.5,>=0.4.8
Requires-Dist: kash-shell<0.5,>=0.4.10
Requires-Dist: prettyfmt>=0.4.1
Requires-Dist: rich>=14.0.0
Requires-Dist: sidematter-format<0.2,>=0.1.0
Requires-Dist: yt-dlp[default]>=2026.8.19
Provides-Extra: youtube
Requires-Dist: deno<3,>=2.9; extra == 'youtube'
Description-Content-Type: text/markdown

# deep-transcribe

High-quality transcription, formatting, and analysis of videos and podcasts.

Deep Transcribe accepts YouTube and other media URLs or local audio and video files.
It uses Deepgram Nova-3 with the current batch diarizer, then can identify speakers,
format paragraphs and timestamps, add sections, write a brief synopsis and structural
outline, research key passages, capture video frames, and export browser-ready HTML.

Speech-to-text goes through Deepgram, chosen for its speaker diarization.
Speaker correction, sections, outline, and synopsis all read speaker-labeled text.

LLM processing uses configurable [kash](https://github.com/jlevy/kash) model roles.
New workspaces use the current Anthropic profile by default, and an equivalent OpenAI
profile is included.

## Example: Hotel Check In — SNL

The public example uses the official [Saturday Night Live sketch][example-video]. Its
five speaking roles, short interjections, repeated hotel terminology, running joke, and
scene changes exercise speaker correction, key terms, summaries, outlines, timestamps,
and frame captures in just over four minutes.

| Source Video | Formatted Transcript |
| :---: | :---: |
| [![Mikey Day and Kumail Nanjiani in the SNL Hotel Check In sketch](https://img.youtube.com/vi/kq9Q9-U0vrc/maxresdefault.jpg)][example-video] | [![Formatted Hotel Check In transcript title, synopsis, and outline](docs/examples/snl-hotel-check-in-transcript-preview.png)][example-pdf] |
| [Watch the video][example-video] | [View the PDF][example-pdf] |

[example-video]: https://www.youtube.com/watch?v=kq9Q9-U0vrc
[example-pdf]: docs/examples/snl-hotel-check-in-transcript.pdf

A URL is enough to start:

```shell
uvx "deep-transcribe[youtube]" --annotated "https://www.youtube.com/watch?v=kq9Q9-U0vrc"
```

Deep Transcribe fetches the source metadata through the media extractor and gives the
models a bounded version of the title, description, canonical URL, channel, categories,
and tags.
For this sketch that already names four of the five performers.
What the metadata cannot say is which performer plays which role, so the two guests who
speak once each are absorbed into other speakers.

Add `--web-search` and the roster step researches the source before labeling anyone:

```shell
uvx "deep-transcribe[youtube]" --annotated --web-search \
    "https://www.youtube.com/watch?v=kq9Q9-U0vrc"
```

That recovers all five speakers, including both Room 904 guests and the agent the
metadata never mentions, with no context of your own.
Search is off by default because it can mislead.
With or without it, the models may state only what your context, the fetched metadata, or
a corroborated search result supports; they are told where each piece of evidence came
from and are not permitted to add anything else.

You can also just say what you know, which is faster and free:

```shell
uvx "deep-transcribe[youtube]" --annotated \
    --context "Saturday Night Live sketch. Five speakers: Mr. Adams (Mikey Day), the Front Desk Employee (Kumail Nanjiani), a Government Representative (Beck Bennett), and two Room 904 Guests (Chris Redd and Leslie Jones)." \
    "https://www.youtube.com/watch?v=kq9Q9-U0vrc"
```

That labels all five roles too, and picks up “Chatsworth House, a Marriott experience,”
the Stargazer Lounge, and the Indulge spa without being told about them.

### Steering the Output

Add flags when you want a specific shape rather than a good default.
This is the command behind the PDF above: it fixes the labels for the two unnamed guests,
pins spellings that matter, and asks for a particular synopsis and outline.

```shell
uvx "deep-transcribe[youtube]" \
    --workspace ./snl-hotel-output \
    --annotated \
    --title "Hotel Check In — SNL" \
    --context "This is the Saturday Night Live sketch Hotel Check In. The five speaking roles are Mr. Adams (Mikey Day), the Front Desk Employee (Kumail Nanjiani), the Government Representative (Beck Bennett), and two unnamed Room 904 Guests (Chris Redd and Leslie Jones). Label the unnamed roles Room 904 Guest (Chris Redd) and Room 904 Guest (Leslie Jones)." \
    --instructions "Write two short synopsis paragraphs. In the first, identify the SNL sketch and name all five performers with their roles. In the second, explain how the escalating hotel sales pitches drive the joke. Give every outline section exactly two concise bullets." \
    --key-term "Mr. Adams" \
    --key-term "Chatsworth Marriott Experience" \
    --key-term "Stargazer Lounge" \
    --key-term "North Korea" \
    "https://www.youtube.com/watch?v=kq9Q9-U0vrc"
```

### Local Files and Sources Without Metadata

A local recording, or a podcast whose publisher says little, has no useful metadata to
fetch and nothing for search to corroborate.
Your own context is the only evidence, so say who is speaking:

```shell
uvx deep-transcribe --annotated \
    --context "Board meeting recording. Three speakers: Dana Ortiz chairing, Sam Weber presenting the budget, and one board member asking questions." \
    ./board-meeting.m4a
```

Local files need no JavaScript runtime, so the plain `deep-transcribe` install is enough.
Without context the transcript still comes out correct; the speakers are just labeled
generically.

The command produces cached media and intermediate results, a processed Markdown
transcript, and browser-ready HTML. Review the result, revise the prose, and run the
same command again to correct context or request a different synopsis or outline.
Use `--context-file notes.txt` when the context is long or will be edited repeatedly.
Deep Transcribe reuses the raw transcript and resumes at the first affected stage.
Context is saved with the source, so a later run that omits `--context` keeps the text
you supplied before.
A cached URL resource created without extractor metadata is enriched on the next run
without repeating speech-to-text.

The static HTML is also the source for the PDF above.
Open it in Chrome or Chromium, choose **Print → Save as PDF**, disable the browser’s own
headers and footers, and keep background graphics enabled.
For an automated, reproducible print on macOS, substitute the absolute HTML path that
Deep Transcribe reports:

```shell
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
    --headless=new \
    --disable-background-networking \
    --no-pdf-header-footer \
    --print-to-pdf=transcript.pdf \
    "file:///absolute/path/to/transcript.html"
```

Use `google-chrome` or `chromium` as the executable on other platforms.
Deep Transcribe does not require or use a separate PDF renderer.

Run `deep-transcribe --docs` for speaker rosters, cache behavior, custom stages, model
profiles, and deliberate full reruns.

## Getting Started

Deep Transcribe runs through [uv](https://docs.astral.sh/uv/), which fetches Python and
Deep Transcribe itself.
Install uv and [ffmpeg](https://ffmpeg.org/) yourself.
Nothing else needs a manual install.

Speech-to-text always goes through Deepgram, so a
[Deepgram API key](https://console.deepgram.com/signup) is required.
New accounts start with $200 of credit and no credit card.
Add one LLM provider key for the formatting and analysis stages:

- `DEEPGRAM_API_KEY` for speech-to-text and diarization (required)
- `ANTHROPIC_API_KEY` for the default Anthropic profile
- `OPENAI_API_KEY` for the OpenAI profile

Set them in the process environment, a `.env` or `.env.local` file in the current
directory or one of its parents, or `~/.env.local`.
Do not commit API keys.

Then run it without installing anything:

```shell
uvx "deep-transcribe[youtube]" --help
```

The `youtube` extra supplies Deno, which yt-dlp needs to solve the JavaScript challenges
YouTube applies to media URLs.
Plain `uvx deep-transcribe` is enough for local audio and video files.

For repeated use, install it as a persistent tool:

```shell
uv tool install "deep-transcribe[youtube]"
deep-transcribe --help
```

## Cross-Agent Skill

Install the public discovery skill through the cross-agent skills installer:

```shell
npx skills add jlevy/deep-transcribe@deep-transcribe
```

The skill uses the source checkout or installed CLI when available and reads the guide
packaged with that executable.

If the CLI is already available, install its complete skill bundle directly from a
project root:

```shell
deep-transcribe --install-skill
```

This writes the portable `.agents/skills/deep-transcribe/` bundle, the
`.claude/skills/deep-transcribe/` mirror, and a marker-bounded project instruction block
in `AGENTS.md`. The install is idempotent.
Run `deep-transcribe --docs` for surface selection and explicit global-install options.

## Self-Documenting CLI

Start with the single help page:

```shell
deep-transcribe --help
deep-transcribe --docs
deep-transcribe --skill
deep-transcribe --models
```

The help page documents all presets, individual processing stages, Deepgram language and
model selection, natural-language context and exact speaker overrides, caching and rerun
behavior, JSON output, model profiles, and examples.
`--docs` prints the complete guide packaged with the installed release, including the
review-and-rerun workflow and skill installation.
The transcription interface is `deep-transcribe OPTIONS INPUT`.

### Model Provider

Inspect the exact current Anthropic and OpenAI role mappings before selecting one:

```shell
deep-transcribe --models
deep-transcribe --models anthropic
deep-transcribe --models openai
```

The selection is saved in the chosen workspace.
Pass `--workspace` when using a location other than `./transcriptions`. Add an input to
the selection command to save the profile and transcribe in one run:
`deep-transcribe --models openai INPUT`.

## Output

Each run reports:

- the workspace containing cached media and intermediate results
- the transcript source
- browser-ready HTML

Use `--json` when another tool or agent needs stable artifact paths.
You can also open the workspace with `kash` to inspect cached and intermediate items.

## Built-in Guide

Run `deep-transcribe --docs` for the complete operational guide.
It includes environment setup, natural-language context, speaker correction, incremental
reruns, cache verification, model-profile comparisons, output review, privacy,
troubleshooting, and agent-skill installation.
Because the guide ships inside the package, agents can read documentation that matches
the executable they are about to use.

## Project Docs

For environment setup, see [installation.md](docs/installation.md).

For development workflows, see [development.md](docs/development.md).

For the manual, agent-reviewed release test, see
[e2e-test.runbook.md](tests/e2e-test.runbook.md).

For publishing, see [publishing.md](docs/publishing.md).

* * *

*This project was built from
[simple-modern-uv](https://github.com/jlevy/simple-modern-uv).*

<!-- This document follows common-doc-guidelines.md.
See github.com/jlevy/practical-prose and review guidelines before editing.
-->
