Skip to main content
Glama
README.md
<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

B3.2/5.0

Scored across 6 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues