{"id":27804017,"url":"https://github.com/gastonzalba/capture-video-frame-api","last_synced_at":"2026-04-14T06:33:13.609Z","repository":{"id":290437981,"uuid":"974363507","full_name":"GastonZalba/capture-video-frame-api","owner":"GastonZalba","description":"Api pequeña en FastAPI que devuelve una captura de video en base a un ID, un servicio (como YouTube), un tiempo de captura en la calidad especificada","archived":false,"fork":false,"pushed_at":"2025-04-30T16:22:39.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-01T08:15:09.899Z","etag":null,"topics":["api","fastapi","youtube","ytdl"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GastonZalba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T16:57:46.000Z","updated_at":"2025-04-30T16:22:43.000Z","dependencies_parsed_at":"2025-04-28T21:24:14.540Z","dependency_job_id":"0258f405-afa1-423c-9d03-91664f203e5f","html_url":"https://github.com/GastonZalba/capture-video-frame-api","commit_stats":null,"previous_names":["gastonzalba/capture-video-frame-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GastonZalba%2Fcapture-video-frame-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GastonZalba%2Fcapture-video-frame-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GastonZalba%2Fcapture-video-frame-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GastonZalba%2Fcapture-video-frame-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GastonZalba","download_url":"https://codeload.github.com/GastonZalba/capture-video-frame-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251843657,"owners_count":21652855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","fastapi","youtube","ytdl"],"created_at":"2025-05-01T08:15:20.362Z","updated_at":"2025-10-15T00:37:47.728Z","avatar_url":"https://github.com/GastonZalba.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Capture Video Frame API\n\n**FastAPI** que devuelve una captura de video en base a un ID, un servicio (como YouTube) y un tiempo de video en una calidad especificada. También permite averiguar qué calidades de video existen antes de realizar la descarga.\n\n## Funcionamiento general\n- Captura de imagen de YouTube: se utiliza el módulo [yt_dlp](https://pypi.org/project/yt-dlp/) para realizar la descarga en el segundo solicitado, en formato video webm (de 0.1 segundo de duración) y en la calidad requerida. \n- Usando [ffmpeg](https://www.ffmpeg.org/) se captura el primer frame de ese fragmento, retornándolo al cliente como imagen jpg.\n- Cacheado de recursos: como los tiempos de las peticiones usando yt_dlp son muy largos, se utiliza el módulo [diskcache](https://pypi.org/project/diskcache/) para almacenar temporalmente cada respuesta (30 días para imágenes, 360 para los `.json` de calidades existentes), posibilitando responder instantáneamente futuras peticiones. Los elementos cacheados se almacenan en la carpeta temporal del sistema (retornada por `tempfile.gettempdir()`), pudiendo alcanzar un limíte máximo de 200 MB.\n\n---\n\n## Requisitos\n\n- Python 3.8+\n- pip\n- ffmpeg\n\n---\n\n## Instalación\n\n1. Cloná o descargá el proyecto.\n\n2. Creá un entorno virtual (opcional pero recomendado):\n\n    ```bash\n    python -m venv .venv\n    source .venv/bin/activate  # Linux/macOS\n    .venv/Scripts/activate     # Windows\n    ```\n\n3. Instalá las dependencias:\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n---\n\n## Cómo iniciar la aplicación\n\n1. Asegurate de estar en el directorio raíz del proyecto.\n\n2. Ejecutá el servidor con **Uvicorn**:\n\n    ```bash\n    uvicorn app.main:app --reload\n    ```\n\n3. La API estará disponible en:\n\n    ```\n    http://localhost:8000\n    ```\n\n---\n## Uso\n### Endpoint `/capture-frame`\n\nRealizar una petición GET para obtener una imagen con los siguientes parámetros:\n\n| Parámetro | Tipo  | Descripción                                 |\n|-----------|-------|---------------------------------------------|\n| vid       | str   | ID del video      |\n| source   | SourceOption   | Origen del video (ej: youtube)        |\n| time   | float   | Tiempo de inicio en segundos (ej: 30)        |\n| resolution   | int   | Resolución vertical del video (por defecto 360)  |\n| vcodec   | VideoCodecOption   | Codec de video prioritario (por defecto avc1)  |\n| disable_cache   | bool   | Deshabilita el uso de caché  |\n\n#### Resoluciones habituales\n* 144\n* 240\n* 360\n* 480\n* 720\n* 1080    \n* 1440\n* 2160\n\n**Ejemplo de URL de petición**:\n[http://localhost:8000/capture-frame?vid=dQw4w9WgXcQ\u0026source=youtube\u0026time=6.6\u0026resolution=360](http://localhost:8000/capture-frame?vid=dQw4w9WgXcQ\u0026source=youtube\u0026time=6.6\u0026resolution=360)\n\n\n### Endpoint `/get-qualities`\n\nRealizar una petición GET para obtener todas las calidades exitentes del video, con los siguientes parámetros:\n\n| Parámetro | Tipo  | Descripción                                 |\n|-----------|-------|---------------------------------------------|\n| vid       | str   | ID del video      |\n| source   | SourceOption   | Origen del video (ej: youtube)        |\n| disable_cache   | bool   | Deshabilita el uso de caché  |\n\n**Ejemplo de URL de petición**:\n[http://localhost:8000/get-qualities?vid=dQw4w9WgXcQ\u0026source=youtube](http://localhost:8000/get-qualities?vid=dQw4w9WgXcQ\u0026source=youtube)\n\n---\n\n## Tests\n\nHay un archivo `test.py` que hace una petición de prueba al servidor, obtiene las calidades disponibles del video y una imagen en el disco.\n\n1. Asegurate de que la API esté corriendo (`uvicorn` abierto).\n\n2. Ejecutá el test:\n\n    ```bash\n    python test.py\n    ```\n\n3. Si todo sale bien, se generará un archivo `test.jpg` en el mismo directorio.\n\n---\n\n## Notas\n\n- La aplicación está configurada para permitir solicitudes CORS únicamente desde dominios `*.minfra.gba.gob.ar`.\n\n---\n\n## @TODO\n- Usar env para manejo de variables por entorno","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonzalba%2Fcapture-video-frame-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgastonzalba%2Fcapture-video-frame-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonzalba%2Fcapture-video-frame-api/lists"}