# clase-scribe

Grabá tus clases virtuales (Zoom, Meet, Teams o lo que sea) y pedile a Claude que te arme un **resumen académico**. El audio se transcribe **en tu PC** con Whisper: nada se sube a ningún servidor de transcripción.

> ⚠️ **Pedile consentimiento al docente antes de grabar.** Grabar sin permiso puede ser ilegal o ir contra las reglas de tu institución.

> 🪟 **Solo funciona en Windows 10/11.** Usa WASAPI loopback, una función de audio exclusiva de Windows.

---

## ¿Qué es esto? (si nunca usaste un MCP)

Claude, por sí solo, no puede grabar audio ni leer archivos de tu PC. Un **MCP** (Model Context Protocol) es un pequeño programa que instalás en tu compu y que le da a Claude **herramientas nuevas**. Es como enchufarle un accesorio.

clase-scribe le agrega a Claude herramientas para:

1. **Grabar** todo lo que suena en tu PC (la voz del profe en Zoom, por ejemplo).
2. **Transcribir** esa grabación a texto.
3. **Guardar un resumen** de la clase, armado por Claude.

Vos no usás comandos raros: le hablás a Claude normalmente ("empezá a grabar la clase de Historia") y él usa las herramientas.

---

## Instalación (una sola vez, ~10 minutos)

Necesitás **una** de estas apps de Claude:

- **Claude Code**: la versión de Claude para la terminal, o la pestaña *Code* de la app de escritorio.
- **Claude Desktop**: la app de escritorio de chat.

### Paso 1: instalar `uv`

`uv` es la herramienta que descarga e instala clase-scribe con todo lo que necesita (incluido Python). Abrí **PowerShell** (tecla Windows → escribí "PowerShell" → Enter) y pegá:

```powershell
winget install --id astral-sh.uv -e
```

Cuando termine, **cerrá PowerShell y abrilo de nuevo**, para que Windows reconozca el comando nuevo. Comprobá que quedó instalado:

```powershell
uvx --version
```

Si muestra un número de versión, vas bien.

### Paso 2: conectar clase-scribe a Claude

#### Opción A: Claude Code

En PowerShell, pegá este comando completo:

```powershell
claude mcp add clase-scribe --scope user -- uvx --from git+https://github.com/juanoxidev/clase-scribe.git clase-scribe
```

Para comprobarlo, corré `claude mcp list` y fijate que aparezca `clase-scribe` como conectado (✓). La primera vez puede tardar un minuto porque descarga todo.

#### Opción B: Claude Desktop

1. Abrí Claude Desktop → **Settings** → **Developer** → **Edit Config**. Se abre el archivo `claude_desktop_config.json`.
2. Reemplazá su contenido por esto (o, si ya tenía otros servidores dentro de `"mcpServers"`, agregá solo el bloque `"clase-scribe"`):

   ```json
   {
     "mcpServers": {
       "clase-scribe": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/juanoxidev/clase-scribe.git", "clase-scribe"]
       }
     }
   }
   ```

3. Guardá el archivo y **cerrá Claude Desktop por completo** (también desde el ícono junto al reloj) y volvé a abrirlo.

### Paso 3: la primera transcripción

La primera vez que transcribas algo, se descarga el modelo de reconocimiento de voz (unos **460 MB**). Solo se descarga esa vez. Transcribir lleva tiempo: según tu PC, una clase de una hora puede tardar varios minutos.

---

## Cómo se usa

Hablale a Claude en lenguaje normal. Por ejemplo:

| Vos decís | Qué pasa |
|-----------|----------|
| "Empezá a grabar la clase de Análisis II" | Arranca la grabación |
| "Pará la grabación" | Corta y empieza a transcribir en segundo plano |
| "¿Cómo va la transcripción?" | Te muestra el progreso |
| "Resumí la clase académicamente" | Claude lee la transcripción y guarda un resumen |
| "Transcribí `C:\Users\yo\Downloads\clase.m4a`" | Transcribe una grabación que ya tenías (por ejemplo, la de Zoom) |
| "¿Qué clases tengo grabadas?" | Lista tus sesiones |

En Claude Code también podés usar el comando `/mcp__clase-scribe__resumen_academico`, que arma el resumen con un formato académico prolijo.

### ¿Dónde quedan los archivos?

En la carpeta `ClaseScribe` dentro de tu usuario (`C:\Users\<tu-usuario>\ClaseScribe\`). Cada clase tiene su carpeta con:

- `audio.wav`: la grabación
- `transcript.md`: la transcripción
- `resumen.md`: el resumen
- `meta.json`: datos de la sesión

### Tips para grabar bien

- **Se graba TODO lo que suena en la PC.** Silenciá Spotify, Discord y las notificaciones durante la clase.
- **Tu voz no se graba por defecto**, solo lo que sale por los parlantes o auriculares. Si querés que tus preguntas queden en la grabación, decile a Claude "grabá también mi micrófono".
- Si la PC se cuelga a mitad de la clase, **lo grabado hasta ese momento no se pierde**.

---

## Problemas comunes

**"uvx no se reconoce como un comando"**
¿Cerraste y volviste a abrir PowerShell después de instalar `uv`? Si sigue fallando, corré `where.exe uvx` y, en la configuración de Claude, usá la ruta completa que te muestre en lugar de `uvx`.

**Claude no muestra las herramientas de clase-scribe**
En Claude Code, corré `claude mcp list`. En Claude Desktop, cerrá la app por completo (también desde el ícono junto al reloj) y volvé a abrirla. La primera conexión puede tardar porque descarga todo.

**La grabación sale vacía o en silencio**
Fijate que el audio de la clase salga por el dispositivo predeterminado de Windows. Podés pedirle a Claude "listá los dispositivos de audio" y "grabá usando los auriculares X".

**¿Cómo actualizo a la última versión?**
Corré `uvx --refresh --from git+https://github.com/juanoxidev/clase-scribe.git clase-scribe` una vez (cerralo con Ctrl+C) y reiniciá Claude.

---

## Configuración avanzada (opcional)

Se configura con variables de entorno:

| Variable | Default | Para qué sirve |
|----------|---------|----------------|
| `CLASE_SCRIBE_DIR` | `~/ClaseScribe` | Dónde se guardan las sesiones |
| `CLASE_SCRIBE_MODEL` | `small` | Precisión: `tiny`, `base`, `small`, `medium`, `large-v3`, `turbo`. Más grande = más preciso pero más lento |
| `CLASE_SCRIBE_DEVICE` | `auto` | `cpu` o `cuda` (placa NVIDIA) |
| `CLASE_SCRIBE_COMPUTE_TYPE` | `int8` | `float16` si usás GPU |
| `CLASE_SCRIBE_LANGUAGE` | `es` | Idioma de la clase; dejalo vacío para autodetectar |

Ejemplo en Claude Code, con un modelo más preciso:

```powershell
claude mcp add clase-scribe --scope user -e CLASE_SCRIBE_MODEL=medium -- uvx --from git+https://github.com/juanoxidev/clase-scribe.git clase-scribe
```

En Claude Desktop, agregá `"env": { "CLASE_SCRIBE_MODEL": "medium" }` dentro del bloque `"clase-scribe"`.

---

## Para desarrolladores

### Instalación local editable

```bash
git clone https://github.com/juanoxidev/clase-scribe.git
cd clase-scribe
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"
claude mcp add clase-scribe --scope user -- <ruta-donde-clonaste>/.venv/Scripts/clase-scribe.exe
```

### Tests

```bash
.venv/Scripts/python -m pytest
```

### Arquitectura

```
Audio del sistema (WASAPI loopback) ─┐
Micrófono (opcional) ────────────────┴─► audio.wav ─► faster-whisper ─► transcript.md ─► Claude ─► resumen.md
```

### Tools del MCP

| Tool | Descripción |
|------|-------------|
| `list_audio_devices` | Parlantes (para loopback) y micrófonos |
| `start_recording(title, include_mic?, device?)` | Empieza a grabar |
| `stop_recording(transcribe?)` | Frena y transcribe en background |
| `status(session_id?)` | Estado y progreso |
| `transcribe_file(audio_path, title?)` | Transcribe un audio existente |
| `get_transcript(session_id, part?)` | Transcripción paginada (8000 palabras por parte) |
| `save_summary(session_id, markdown)` | Guarda `resumen.md` |
| `list_sessions` | Historial |

Prompt: `resumen_academico(session_id)`.

### Detalles técnicos que importan

- **Silencio y WASAPI**: el loopback no entrega audio cuando no suena nada, y la lectura se bloquea. Por eso `SilenceKeepAlive` reproduce silencio mientras graba.
- **COM por thread**: cada thread que usa WASAPI llama a `CoInitializeEx`.
- **WAV incremental**: si algo se corta a mitad de la clase, el audio grabado hasta ese momento queda.
- **`mcp` 2.x**: usa `MCPServer`, que reemplazó a `FastMCP` de la 1.x.

## Licencia

[MIT](LICENSE)