clipoteca
<div align="center">
<img src="https://raw.githubusercontent.com/riquelmechile/clipoteca-comunitaria/main/assets/clipoteca-banner.svg" width="100%" alt="Clipoteca: encuentra, guarda y comparte escenas. Klipi, la mascota, explora clips con una lupa." />
<br/>
**Una biblioteca comunitaria de clips, pensada para personas y agentes de IA.**
**Multilingüe · Abierta · Reutilizable · Hasta 20 segundos**
[📋 Roadmap](docs/ROADMAP.md) · [🧭 Arquitectura](docs/ARQUITECTURA.md) · [🌐 Fuentes e idiomas](docs/FUENTES_IDIOMAS.md) · [🎨 Identidad](docs/IDENTIDAD.md) · [🤝 Colaborar](CONTRIBUTING.md)
</div>
---
> **Estado v1.0.0: Worker desplegado y flujos E2E reales comprobados.** Servicio: [clipoteca-worker.sc-plasticov.workers.dev](https://clipoteca-worker.sc-plasticov.workers.dev), con API REST `/v1/*` y MCP Streamable HTTP `/mcp`. Hay **8 clips reales publicados** en el catálogo, con material de Pexels, PeerTube y un aporte comunitario ([Issue #26](https://github.com/riquelmechile/clipoteca-comunitaria/issues/26), `clip-000008`). La ingesta admite consultas ES/EN/ZH/RU. Los proveedores que requieren credenciales ausentes se clasifican `AUTH_REQUIRED`; Bilibili bloquea solicitudes desde determinadas IP de centros de datos. La verificación real no equivale a disponibilidad universal de las 15 fuentes ni a costos facturados conocidos. Ver [evidencias v1](docs/INFORME_V1.md) y [operación M10](docs/OPERACION_M10.md).
## Uso
Buscar clips públicos desde la API REST (el filtro `aspect_ratio` usa URL encoding):
```bash
curl --fail-with-body -sS 'https://clipoteca-worker.sc-plasticov.workers.dev/v1/clips?q=lluvia&aspect_ratio=9%3A16'
```
Conectar un cliente MCP compatible con HTTP remoto usando la dirección `https://clipoteca-worker.sc-plasticov.workers.dev/mcp`. Ejemplo de configuración para un cliente que acepta `mcpServers`:
```json
{
"mcpServers": {
"clipoteca": {
"url": "https://clipoteca-worker.sc-plasticov.workers.dev/mcp"
}
}
}
```
Para aportar una escena, [abre el formulario «Aportar escena»](https://github.com/riquelmechile/clipoteca-comunitaria/issues/new/choose) en GitHub Issues, indica una URL HTTPS directa a MP4/WebM/OGV y los datos de procedencia. El Issue se procesa automáticamente; no requiere permisos de escritura del repositorio. Ver [guía de colaboración](CONTRIBUTING.md).
## La idea
Buscar una escena no debería significar encontrarla y descargarla de cero una y otra vez.
**Clipoteca** está diseñada para que un agente solicite, por ejemplo, **«lluvia, vertical 9:16»**. El sistema consultará su catálogo y, cuando haga falta, buscará en fuentes externas usando cuatro idiomas, procesará clips nuevos de hasta 20 segundos y conservará sus archivos en **GitHub Releases** para futuras consultas.
### Cuatro idiomas, una biblioteca
| Español | English | 中文 | Русский |
|---|---|---|---|
| **lluvia** | **rain** | **下雨** | **дождь** |
| Metadatos ES | Metadata EN | Búsqueda ZH | Búsqueda RU |
Las búsquedas externas en **español, inglés, chino y ruso son requisitos obligatorios**, no características opcionales. Todos los clips se catalogarán con títulos, descripciones y etiquetas en **español e inglés**, conservando el idioma y fuente de origen.
## Componentes de v1
| Componente | Responsabilidad |
|---|---|
| **API REST + MCP** | Buscar clips por concepto, duración, proporción, orientación y fuente; obtener sus archivos |
| **Motor multilingüe** | Ejecutar búsquedas paralelas ES/EN/ZH/RU con límites y fallos aislados |
| **Ingesta automática** | Descargar material nuevo accesible, deduplicar, normalizar con FFmpeg y generar miniaturas |
| **Catálogo público** | Metadatos ES/EN, 9:16 o 16:9, resolución, FPS, duración y procedencia |
| **GitHub Releases** | Almacenar los clips procesados y hacerlos recuperables sin buscar dos veces |
**Stack:** Cloudflare Workers + TypeScript (API y MCP), GitHub Actions + Python/FFmpeg (procesamiento), GitHub Releases y catálogo JSON. No se necesita un servidor Oracle ni una web Astro.
## Fuentes del roadmap
**Stock:** Pexels, Pixabay. **Archivos:** Wikimedia Commons, Internet Archive, NASA. **Video:** YouTube, RuTube, PeerTube, Odysee, VK Video, Bilibili. **Redes:** Douyin, TikTok, Instagram Reels y Snapchat.
Cada fuente tendrá un adaptador con capacidades y estados verificables. La posibilidad técnica de descargar archivos varía entre plataformas; no se considera integrado un proveedor solo por figurar en esta lista.
[Leer matriz de fuentes e idiomas](docs/FUENTES_IDIOMAS.md)
## Ruta de trabajo
El roadmap tiene **11 hitos, de M0 a M10**: estructura inicial, catálogo y Releases, FFmpeg, motor multilingüe obligatorio, grupos de proveedores, API/MCP, publicación automática, aportes comunitarios y validación final.
**[Consultar el roadmap completo con criterios de aceptación](docs/ROADMAP.md)**
### Documentación técnica
| Documento | Contenido |
|---|---|
| [Proyecto y alcance](docs/PROYECTO.md) | Requisitos, casos de uso y límites |
| [Arquitectura](docs/ARQUITECTURA.md) | Componentes y ejecución sin servidor propio |
| [Fuentes e idiomas](docs/FUENTES_IDIOMAS.md) | Proveedores y cuatro idiomas obligatorios |
| [Contratos REST/MCP](docs/CONTRATOS_API_MCP.md) | Interfaces y metadatos previstos |
| [Roadmap](docs/ROADMAP.md) | Hitos, pruebas y condiciones de cierre |
| [QA y operación](docs/QA_OPERACION.md) | Verificación, controles y costos |
| [Especificación completa](docs/ESPECIFICACION_COMPLETA.md) | Documento integral original, conservado sin cambios de contenido |
| [Identidad visual](docs/IDENTIDAD.md) | Mascota Klipi, paleta y SVG |
## Conoce a Klipi
<img src="https://raw.githubusercontent.com/riquelmechile/clipoteca-comunitaria/main/assets/klipi-mascot.svg" width="190" align="right" alt="Klipi, mascota exploradora de Clipoteca" />
**Klipi** es el explorador de fotogramas de la biblioteca: un personaje original que combina el contorno de una película, un botón de reproducción y una lupa para descubrir escenas.
Los SVG originales del [banner](assets/clipoteca-banner.svg), [logotipo](assets/clipoteca-logo.svg), [isotipo](assets/clipoteca-mark.svg), [mascota](assets/klipi-mascot.svg) y [tarjeta social](assets/clipoteca-social.svg) están incluidos en este repositorio.
## Colaboración y licencia
El proyecto se publica con **[licencia MIT](LICENSE)**, compatible con desarrollar en el futuro funciones de créditos, servicios comerciales u otras modalidades de acceso. La implementación de créditos no forma parte de esta primera fase; los recursos almacenados públicamente en GitHub no se vuelven privados por incorporar créditos a una API.
Puedes [proponer ideas y mejoras](CONTRIBUTING.md). Las políticas comunitarias para los clips y sus aportes se debatirán posteriormente.
---
<div align="center">
**Una escena encontrada. Una biblioteca que crece.**
<img src="https://raw.githubusercontent.com/riquelmechile/clipoteca-comunitaria/main/assets/clipoteca-logo.svg" width="280" alt="Logotipo Clipoteca" />
</div>
TDQS
Scored across 6 tools
search_clips and search_and_import are the closest pair, but the descriptions clearly separate read-only search from a write-token-gated async import queue. get_clip, download_clip, get_job_status, and list_sources each target a distinct resource or action with no real overlap.
All six tools use snake_case verb_noun form (search_clips, get_clip, download_clip, get_job_status, list_sources), which is highly predictable. The only deviation is search_and_import, which embeds a conjunction rather than a single verb.
Six tools is well-scoped for a clip catalogue with an asynchronous import pipeline; each tool maps to a necessary step (discover, inspect, download, import, poll, check credentials). Nothing appears redundant or padded.
The surface covers discovery, metadata retrieval, download, async import, job polling, and credential status, which is solid lifecycle coverage for a read-mostly catalogue. Minor gaps exist: no way to list or cancel outstanding jobs, and no browse/list-all tool beyond search.