Metadata-Version: 2.4
Name: deep-transcribe
Version: 0.1.10
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 :: 4 - Beta
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.4,>=0.3.0
Requires-Dist: kash-media<0.5,>=0.4.4
Requires-Dist: prettyfmt>=0.4.1
Requires-Dist: rich>=14.0.0
Requires-Dist: sidematter-format<0.2,>=0.1.0
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 and summaries, research key passages, capture
video frames, and export browser-ready HTML.

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.

## Requirements

Install [uv](https://docs.astral.sh/uv/) and
[ffmpeg](https://ffmpeg.org/). Deep Transcribe requires Python 3.13, which uv fetches
automatically.

Set `DEEPGRAM_API_KEY` and one LLM provider key in the process environment or a
`.env` file in the current directory or one of its parents:

- `ANTHROPIC_API_KEY` for the default Anthropic profile
- `OPENAI_API_KEY` for the OpenAI profile

Do not commit API keys.

## Zero-Install CLI

Run the pinned release without installing it globally:

```shell
uvx --from deep-transcribe==0.1.9 deep-transcribe --help
```

For repeated human use, a persistent tool install is also available:

```shell
uv tool install deep-transcribe
deep-transcribe --help
```

## Cross-Agent Skill

Install the repository skill through the cross-agent skills installer:

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

The skill uses a local `deep-transcribe` executable when available and otherwise uses
the pinned zero-install runner. It routes agents to CLI help rather than carrying a
second copy of the command manual.

## Self-Documenting CLI

Start with the top-level command directory, then open the help page for the relevant
task:

```shell
deep-transcribe --help
deep-transcribe transcribe --help
deep-transcribe models --help
deep-transcribe mcp --help
deep-transcribe logs --help
```

The command pages document all presets, individual processing stages, Deepgram language
and model selection, source metadata and speaker hints, caching and rerun behavior, JSON
output, model profiles, MCP tools, and examples. Existing flag-only invocations remain
supported for backward compatibility.

### Model Provider

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

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

The selection is saved in the chosen workspace. Pass `--workspace` to `models` and
`transcribe` when using a location other than `./transcriptions`.

### Quick Demo

This short two-person hotel dialogue exercises transcription and diarization:

```shell
deep-transcribe transcribe --basic \
    "https://www.youtube.com/watch?v=wyqfYJX23lg"
```

Use `deep-transcribe transcribe --help` to choose formatted, annotated, deep, or custom
processing.

### Source Context and Corrections

Add context directly or use one reusable YAML file for URLs and raw media files:

```yaml
title: Acme product interview
description: Alice Chen interviews Bob Diaz about SignalFlow.
additional_context: Alice is the host and Bob is the product lead.
key_terms:
  - Alice Chen
  - Bob Diaz
  - SignalFlow
speaker_hints:
  "0": Alice Chen
  "1": Bob Diaz
```

```shell
deep-transcribe transcribe --annotated --metadata interview.yml ./interview.mp3
```

Update the metadata and rerun the same command to correct speaker names, descriptions, or
other semantic context. Those corrections reuse the cached Deepgram transcript. Changing
`key_terms` deliberately requests a new transcript because the terms affect speech
recognition. Use `--rerun-processing` to force every downstream stage while preserving the
raw transcript; `--rerun` intentionally requests fresh speech-to-text processing. Run
`deep-transcribe transcribe --help` for the equivalent concise flags. If Deepgram merges
distinct voices under one ID, replace direct ID hints with a complete `speaker_roster` list
and describe role or dialogue transitions in `additional_context`; Deep Transcribe will
correct turn-level boundaries with the selected careful model profile.

## 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.

## MCP Server

Run `deep-transcribe mcp --help` for the available transcription tools and transports.
Run `deep-transcribe logs --help` for server log handling.

## 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.
-->
