Metadata-Version: 2.4
Name: aurclips
Version: 0.3.0
Summary: De videos largos a YouTube Shorts verticales con subtítulos, 100% local
Project-URL: Homepage, https://github.com/feliivk/aurclips
Author: Felii
License: MIT License
        
        Copyright (c) 2026 Felii
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ffmpeg,local,shorts,subtitles,video,whisper,youtube
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.12
Requires-Dist: faster-whisper>=1.1.0
Requires-Dist: google-api-python-client>=2.140
Requires-Dist: google-auth-oauthlib>=1.2
Requires-Dist: opencv-python-headless>=4.9
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Requires-Dist: yt-dlp>=2025.1.1
Provides-Extra: cuda
Requires-Dist: nvidia-cublas-cu12; (sys_platform != 'darwin' and platform_machine == 'x86_64') and extra == 'cuda'
Requires-Dist: nvidia-cudnn-cu12; (sys_platform != 'darwin' and platform_machine == 'x86_64') and extra == 'cuda'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🎬 aurclips

[![tests](https://github.com/feliivk/aurclips/actions/workflows/ci.yml/badge.svg)](https://github.com/feliivk/aurclips/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aurclips)](https://pypi.org/project/aurclips/)

Convierte videos largos en Shorts verticales con subtítulos, **completamente
local**. Corre en **Windows, Linux y macOS**.

```bash
aurclips clip mi_partida.mp4
```

```
data/output/mi_partida/
  0001_El_truco_que_nadie_conoce.mp4    ← 9:16, subtítulos quemados
  0001_El_truco_que_nadie_conoce.txt    ← título, descripción y hashtags
  0002_Por_que_nadie_termina_el_juego.mp4
  0002_Por_que_nadie_termina_el_juego.txt
```

Sin API keys, sin cuenta, sin mandar tu material a ningún servidor: transcribir,
elegir y editar pasa todo en tu máquina.

## Qué hace

- **Transcribe** con Whisper local, con tiempos por palabra (usa tu GPU NVIDIA
  si la tienes).
- **Elige los momentos**: lo que marcaste al grabar manda; si no marcaste,
  puntúa estructura (gancho, preguntas, cierre de idea, densidad) y energía de
  audio según tu género.
- **Recorta a 9:16**, quita las pausas muertas (jump cuts) y encuadra en el
  rostro si lo pides.
- **Quema subtítulos** estilo viral, palabra a palabra.
- **Escribe la metadata** de cada recorte en un `.txt` al lado: título,
  descripción y hashtags, listos para copiar y pegar. Con
  [Ollama](https://ollama.com) los redacta un modelo local; sin Ollama, una
  heurística.

## Qué NO hace

- **No adivina bien sin tu ayuda.** Sin marcas, cuenta con **~1 recorte bueno
  por grabación**: el filtro de calidad prefiere quedarse corto antes que
  rellenar. Marcar cambia eso por completo — y no exige grabar distinto:
  también puedes marcar después, **repasando la grabación**.
- **No hay magia de IA en la selección.** Es una heurística simple y a propósito
  ([ADR-0001](docs/adr/0001-extremos-apretados-centro-simple.md)): no modela
  arcos narrativos ni persigue la viralidad. El criterio lo pones tú.
- **No sube nada.** Publicar en YouTube existe, pero es opcional y viene
  apagado.
- **No acelera en GPU en macOS.** La GPU NVIDIA acelera la transcripción en
  Windows y Linux; en macOS (incluido Apple Silicon) se transcribe en CPU. En
  CPU funciona en todas partes, solo más lento.
- **Está en beta.** Los defaults siguen en calibración: espera cambios de
  configuración entre versiones y **mira lo que genera antes de publicarlo**.

## Instalación

Necesitas **[Python 3.12](https://www.python.org/downloads/)** y **ffmpeg**. La
fuente de los subtítulos ya viene con el paquete.

**ffmpeg** (una vez, con tu gestor de paquetes):

| SO | Comando |
| --- | --- |
| macOS | `brew install ffmpeg` |
| Debian/Ubuntu | `sudo apt install ffmpeg` |
| Fedora | `sudo dnf install ffmpeg` |
| Windows | `winget install ffmpeg` (o lo descarga `setup.ps1` a `tools\`) |

**aurclips**:

```bash
# Linux / macOS
git clone https://github.com/feliivk/aurclips && cd aurclips
sh setup.sh
```

```powershell
# Windows
git clone https://github.com/feliivk/aurclips; cd aurclips
powershell -ExecutionPolicy Bypass -File setup.ps1
```

Ambos crean un entorno virtual e instalan el comando `aurclips`. Si tienes GPU
NVIDIA (Windows/Linux), el setup detecta `nvidia-smi` y ofrece el soporte CUDA;
en CPU también funciona (baja `whisper.model` a `small`).

¿Prefieres instalarlo como un paquete más, sin clonar nada? Está en
[PyPI](https://pypi.org/project/aurclips/):

```bash
pipx install aurclips        # aislado, comando global
# o, dentro de tu propio entorno:
pip install aurclips
# con soporte GPU NVIDIA (Windows/Linux x86_64):
pip install "aurclips[cuda]"
```

Instalado así, aurclips guarda `config.yaml` y los datos en las carpetas de
usuario de tu SO (las crea y te dice dónde en el primer arranque); corriendo
desde el checkout usa `./config.yaml` y `./data`, como hasta ahora.

Opcional pero recomendado — un modelo local que escriba los títulos:

```bash
ollama pull qwen2.5:7b
```

aurclips lo detecta solo. Sigue siendo local y gratis.

> Los ejemplos usan el comando `aurclips` que crea el setup. Si prefieres no
> activar el entorno, es equivalente a `.venv/bin/python -m aurclips` (Linux/mac)
> o `.venv\Scripts\python -m aurclips` (Windows).

## Ejemplo

```bash
aurclips clip "~/grabaciones/partida 12.mkv"
aurclips clip "https://youtube.com/watch?v=..."   # también URLs: baja una vez y recorta
aurclips clip partida.mp4 --out ~/edicion
aurclips clip partida.mp4 --clips 1
```

`--out` cambia la carpeta de destino y `--clips` pone un tope solo para esa
corrida. Nada de esto toca `config.yaml`, ni deja cola pendiente, ni necesita
credenciales: un recorte suelto entra y sale.

Recortar dos veces la misma grabación no la vuelve a transcribir — la
transcripción queda en caché, así que probar parámetros es barato. La segunda
corrida **reemplaza** los recortes de la primera en esa carpeta: si quieres
conservar los anteriores, dales otro `--out`.

Los mandos completos están en [Configuración](docs/config.md) y
[Selección](docs/selection.md).

## Luego: graba pensando en el recorte

Cuando tú controlas la fuente, el problema deja de ser *"detectar buenos
momentos en footage desconocido"* y pasa a ser *"grabar de forma que extraer sea
fácil"*. Es la palanca más grande que tienes y no toca código:

- **Graba en beats**: unidades de 20-45 s con gancho, punto y cierre.
- **Marca en vivo**: di **"esto es un short"** mientras grabas y ese momento
  gana sobre cualquier puntuación. El segmento con la frase se silencia, así que
  marca el clip pero no entra en él. No hace falta decirla clavada (se compara
  por parecido) ni marcar todos los videos.
- **O por timestamps**: un `<video>.marks.txt` al lado de la grabación, que
  puedes escribir con el hotkey de tu grabadora o con `aurclips mark`.
- **O repasando después**: `aurclips mark grabacion.mp4` abre el video y cada
  Enter marca el momento que está sonando. Para lo que grabaste sin marcar y
  para el material descargado. También acepta una URL de YouTube — el flujo de
  completo para material ajeno es `mark <URL>` y luego `clip <URL>`, con una sola
  descarga. (Necesita [mpv](https://mpv.io): `winget`/`brew`/`apt install mpv`
  — solo este modo lo usa.)

Guía completa: [Grabar en beats](docs/grabar-en-beats.md).

## Luego: que se publique solo

Si los recortes ya te convencen, aurclips también lleva el ciclo completo: sube
a YouTube en privado con fecha programada, y YouTube publica uno por día a la
hora que fijes.

```bash
aurclips run       # ingesta -> recortes -> subida (corrida única)
aurclips watch     # modo continuo: vigila el inbox y procesa lo que llegue
aurclips review    # aprobar o corregir antes de subir
aurclips status    # qué hay en cola y cómo terminó la última corrida
aurclips doctor    # salud: dependencias, colas, disco
aurclips report    # métricas y qué está funcionando
aurclips retry     # reencolar lo que falló
```

`watch` es el modo demonio: deja caer una grabación al inbox (o que OBS grabe
directo ahí — no se procesa nada a medio escribir) y sale procesada en
minutos. Un ciclo fallido no lo mata, Ctrl+C guarda y sale ordenado, y lo
fallido transitorio se reencola solo.

A diferencia del modo recortador, esto sí lleva una base de estado: cada clip
tiene progreso (pendiente, renderizado, subido) y criterio tuyo (sin revisar,
aprobado, descartado). Mientras `review.enabled` sea `true`, nada se sube sin
pasar por tu criterio.

Para dejarlo corriendo solo cada día, hay una receta por SO —cron/systemd en
Linux, launchd en macOS, Programador de tareas en Windows— en
[`packaging/`](packaging/README.md).

Cómo dar de alta las credenciales, la cuota diaria, la programación y qué hacer
si un Short salió mal: [Publicar en YouTube](docs/upload-youtube.md).

Para vigilar canales y descargar material de YouTube en vez de usar tu propio
inbox, mira `channels` en [Configuración](docs/config.md).

## Documentación

| | |
| --- | --- |
| [Cómo funciona](docs/pipeline.md) | El motor y los dos niveles, con el flujo de punta a punta |
| [Grabar en beats](docs/grabar-en-beats.md) | Cómo grabar y marcar para que recortar sea trivial |
| [Selección](docs/selection.md) | Cuántos clips salen y cuáles: piso de calidad y pesos |
| [Configuración](docs/config.md) | Todas las claves de `config.yaml` |
| [Publicar en YouTube](docs/upload-youtube.md) | Credenciales, cuota, programación, despublicar |
| [CONTEXT.md](CONTEXT.md) | El vocabulario del proyecto |
| [ADR](docs/adr/) | Decisiones de arquitectura y por qué |

## Desarrollo

```bash
pip install -e .[dev]
pytest
```

Los tests corren en segundos, sin GPU, sin video real y sin Ollama.

## Licencia

[MIT](LICENSE). El modelo de detección de rostros embebido
([YuNet](https://github.com/opencv/opencv_zoo), int8) es también MIT.

Eres responsable de tener derechos sobre el contenido que recortas y de cumplir
los [términos de servicio de YouTube](https://www.youtube.com/t/terms) y las
políticas de la YouTube Data API al usar la subida automática.
