---
## ❓ ¿Por qué YTSage?
YTSage está diseñado para usuarios que desean un **descargador de YouTube simple pero potente**. A diferencia de otras herramientas, ofrece:
- Interfaz PySide6 moderna y limpia
- Descarga con un solo clic para video, audio y subtítulos
- Funciones avanzadas como SponsorBlock, fusión de subtítulos y selección de listas de reproducción
- Modo genérico (Generic Mode) opcional para sitios compatibles con yt-dlp más allá de YouTube
- Soporte multiplataforma e instalación sencilla
## ✨ Características
| Características básicas | Características avanzadas | Características adicionales |
|-----------------------------------|-----------------------------------------|------------------------------------|
| 🎥 Tabla de formatos | 🚫 Integración de SponsorBlock | 🎞️ Pantalla FPS/HDR |
| 🎵 Extracción de audio | 📝 Selección y fusión de subtítulos | 🔄 Actualización automática de yt-dlp |
| ✨ Interfaz de usuario simple | 💾 Guarda descripción y miniatura | 🛠️ Detección de FFmpeg/yt-dlp/Deno |
| 📋 Soporte y selector de listas de reproducción | 🚀 Limitador de velocidad | ⚙️ Comandos personalizados |
| 📑 Integración de capítulos | ✂️ Recorte de secciones de video | 🍪 Inicio de sesión con cookies |
| 📜 Historial de descargas | 🔄 Selección de canal de lanzamiento | 🌐 Soporte de proxy |
| 🎚️ Conversión de formato de audio | 🎬 Configuración de formato de video | 🆙 Pestaña de actualización integrada |
| 🌍 Modo genérico | 🔊 Normalización de audio (EBU R128) | 🌍 Localización en 14 idiomas |
| 💾 Exportación de listas de reproducción | ⚙️ Calidad y subtítulos predeterminados | |
## 🚀 Instalación
### ⚡ Instalación rápida (Recomendado)
Instala YTSage vía PyPI:
```bash
pip install ytsage
```
🔄 Actualizar instalación existente
```bash
pip install --upgrade ytsage
```
Luego, ejecuta la aplicación:
```bash
ytsage
```
### 📦 Ejecutables precompilados
> [👉 Descargar el último lanzamiento](https://github.com/oop7/YTSage/releases/latest)
#### 🪟 Windows
| Formato | Descripción |
|--------|-------------|
|  | Instalador estándar |
|  | Con FFmpeg incorporado |
|  | Versión portable, no requiere instalación |
|  | Portable con FFmpeg, comprimido |
🛠️ Pasos de instalación
1. **Instalador EXE (`.exe`)**: Haz doble clic en el archivo y sigue el asistente de configuración.
2. **Versión portable (`.zip`)**: Extrae el archivo en el lugar deseado y ejecuta `ytsage.exe`.
3. **FFmpeg incorporado**: Elige las versiones con FFmpeg incorporado si no tienes FFmpeg instalado en tu sistema.
#### 🐧 Linux
| Formato | Descripción |
|--------|-------------|
|  | Paquete Debian |
|  | AppImage, portable |
|  | Paquete RPM |
|  | Flatpak Bundle |
🛠️ Pasos de instalación
- **DEB (`.deb`)**:
```bash
sudo dpkg -i ytsage_*.deb
sudo apt-get install -f # Repara dependencias faltantes si es necesario
```
- **RPM (`.rpm`)**:
```bash
sudo rpm -i ytsage-*.rpm
```
- **AppImage (`.AppImage`)**:
```bash
chmod +x YTSage-*.AppImage
./YTSage-*.AppImage
```
- **Flatpak**: Sigue las instrucciones en Flathub o ejecuta:
```bash
flatpak install flathub io.github.oop7.ytsage
```
#### 🍎 macOS
| Formato | Descripción |
|--------|-------------|
|  | Aplicación comprimida para Apple Silicon |
|  | Instalador de imagen de disco para Apple Silicon |
🛠️ Pasos de instalación
- **Instalador DMG (`.dmg`)**: Haz doble clic para montar, luego arrastra `YTSage.app` a tu carpeta de Aplicaciones.
- **Archivo de aplicación (`.zip`)**: Extrae el zip y mueve `YTSage.app` a tu carpeta de Aplicaciones.
*Nota: Si encuentras el error "La aplicación está dañada", consulta la sección de solución de problemas de macOS a continuación.*
---
💻 Instalación manual desde el código fuente
### 1. Clonar el repositorio
```bash
git clone https://github.com/oop7/YTSage.git
cd YTSage
```
### 2. Instalar dependencias
#### ⚡ Con uv
```bash
uv pip install .
```
#### 📦 O con pip estándar
```bash
pip install .
```
### 3. Ejecutar la aplicación
```bash
python -m ytsage.main
```
## 📸 Capturas de pantalla
Ajustes de descarga
Descarga de lista de reproducción
Formato de audio
Opción personalizada
## 📖 Uso
🎯 Uso básico
1. **Lanza YTSage**
2. **Pega la URL de YouTube** (o usa el botón "Paste URL")
3. **Haz clic en "Analyze"**
4. **Selecciona el formato:**
- `Video` para descargas de video
- `Audio Only` para extracción de audio
5. **Elige opciones:**
- Activar subtítulos y elegir idioma
- Activar fusión de subtítulos
- Guardar miniatura
- Eliminar segmentos patrocinados
- Guardar descripción
- Integrar capítulos
6. **Selecciona directorio de salida**
7. **Haz clic en "Download"**
> 💡 El directorio de descarga predeterminado es la carpeta "Downloads" del usuario.
📋 Descarga de listas de reproducción
1. **Pega la URL de la lista de reproducción**
2. **Haz clic en "Analyze"**
3. **Selecciona videos del selector de listas (opcional, todos por defecto)**
4. **Elige formato/calidad deseada**
5. **Haz clic en "Download"**
> 💡 La aplicación gestiona las colas de descarga automáticamente, y puedes exportar entradas de la lista como archivos `.txt`, `.csv`, `.m3u` o `.json`.
🌍 Modo genérico para sitios que no son YouTube
Usa el modo genérico (Generic Mode) cuando desees que YTSage acepte URLs de sitios compatibles con yt-dlp, como Dailymotion, CBC Gem, TikTok y otros.
Cómo usarlo:
1. Abre `Download Settings`.
2. Activa `Generic Mode`.
3. Pega una URL de video o lista de reproducción compatible que no sea de YouTube.
4. Haz clic en `Analyze`.
5. Elige el formato y descarga como de costumbre.
Notas:
- El modo genérico solo cambia la validación de la URL dentro de YTSage. El sitio debe ser compatible con tu versión instalada de yt-dlp.
- Algunos sitios requieren cookies, inicio de sesión, proxy o argumentos adicionales de yt-dlp dependiendo del extractor.
- Si un sitio falla, actualiza primero yt-dlp desde la pestaña de actualización integrada antes de informar del problema.
🧰 Opciones de medios y descarga
- **Opciones de subtítulos:** Filtra idiomas e incrusta subtítulos en el archivo de video.
- **Fusión de subtítulos:** Fusiona subtítulos en el archivo de video para subtítulos fijos (hardcoded).
- **Guardar descripción:** Guarda la descripción del video como un archivo de texto.
- **Guardar miniatura:** Guarda la miniatura del video como un archivo de imagen.
- **Integrar capítulos:** Incluye marcas de capítulo como metadatos para reproductores de video compatibles.
- **Eliminar segmentos patrocinados:** Elimina segmentos patrocinados del video usando SponsorBlock.
- **Recortar video:** Descarga solo partes específicas de un video especificando rangos de tiempo en formato `HH:MM:SS`.
⚙️ Ajustes de salida y archivos
- **Limitador de velocidad:** Limita la velocidad de descarga, p. ej., `500K` para 500 KB/s.
- **Guardar ruta de descarga:** Guarda la ruta de descarga predeterminada para futuras descargas. Disponible en **Download Settings → Download Path**.
- **Resolución de video predeterminada:** Establece tu resolución de video preferida para selección automática (p. ej., 1080p, 720p). Disponible en **Download Settings → Default Video Resolution**.
- **Idiomas de subtítulos predeterminados:** Establece idiomas de subtítulos para selección automática (separados por comas, p. ej., `es,en`). Disponible en **Download Settings → Default Subtitle Languages**.
- **Formato de nombre de archivo:** Personaliza el formato del nombre de archivo usando variables como `%(title)s`, `%(uploader)s`, `%(playlist_index)s` y `%(resolution)s`. Disponible en **Download Settings → Filename Format**.
- **Forzar formato de salida:** Fuerza las descargas de video a un formato de contenedor específico como `mp4`, `webm` o `mkv`. Disponible en **Download Settings → Output Format Settings**.
- **Conversión de formato de audio:** Convierte descargas de solo audio a formatos preferidos como `AAC`, `MP3`, `FLAC`, `WAV`, `Opus`, `M4A`, `Vorbis` o `Best`. Disponible en **Download Settings → Audio Format Settings**.
- **Normalización de audio:** Estandariza el volumen para descargas de solo audio usando EBU R128.
- **Conexiones simultáneas:** Aumenta drásticamente la velocidad de descarga descargando archivos en múltiples fragmentos a la vez. Disponible en **Download Settings → General → Concurrent Connections** (1 por defecto, máximo recomendado 8-10 para evitar bloqueos por IP).
🌐 Acceso y red
- **Inicio de sesión con cookies:** Inicia sesión en YouTube usando cookies para acceder a contenido privado.
Cómo usarlo:
1. **Recomendado:** Usa la opción integrada `Extract cookies from browser` en la aplicación, luego selecciona tu navegador y opcionalmente un perfil.
2. Alternativamente, extrae las cookies manualmente:
a. Exporta cookies de tu navegador usando una extensión como [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file)
b. Copia las cookies en formato Netscape
c. Crea un archivo llamado `cookies.txt` y pega las cookies
d. Selecciona el archivo `cookies.txt` en la aplicación
- **Soporte de proxy:** Usa un servidor proxy para las descargas, p. ej., `http://:`
- **Modo genérico:** Permite a YTSage analizar y descargar desde sitios que no son YouTube compatibles con yt-dlp. Actívalo en **Download Settings → Generic Mode**.
🛠️ Herramientas y mantenimiento
- **Comandos personalizados:** Accede a funciones avanzadas de yt-dlp mediante argumentos de línea de comandos.
- **Pestaña de actualización:** Gestiona herramientas de actualización desde un solo lugar en Opciones personalizadas:
- **Actualizaciones de yt-dlp:** Busca actualizaciones y cambia entre canales estable y nightly.
- **Verificador de versión de FFmpeg:** Verifica tu versión de FFmpeg y abre guías de instalación.
- **Actualizaciones de Deno:** Verifica y actualiza el motor de ejecución Deno.
- **Detección de FFmpeg/yt-dlp/Deno:** Detecta automáticamente rutas y versiones de FFmpeg, yt-dlp y Deno desde el diálogo Acerca de.
- **Historial de descargas:** Visualiza descargas pasadas con miniaturas y estados desde el botón **History**.
🌍 Localización
YTSage soporta **14 idiomas** para accesibilidad global. Selecciona tu idioma preferido en **Custom Options → Language**.
### Idiomas soportados
| Idioma | Código | Idioma | Código |
|----------|------|----------|------|
| 🇺🇸 Inglés | `en` | 🇪🇸 Español | `es` |
| 🇸🇦 Árabe | `ar` | 🇫🇷 Francés | `fr` |
| 🇩🇪 Alemán | `de` | 🇮🇳 Hindi | `hi` |
| 🇮🇩 Indonesio | `id` | 🇮🇹 Italiano | `it` |
| 🇯🇵 Japonés | `ja` | 🇵🇱 Polaco | `pl` |
| 🇧🇷 Portugués | `pt` | 🇷🇺 Ruso | `ru` |
| 🇹🇷 Turco | `tr` | 🇨🇳 Chino | `zh` |
### Traducciones del README
| Idioma | Archivo | Idioma | Archivo |
|----------|------|----------|------|
| 🇺🇸 Inglés | [README.md](../README.md) | 🇪🇸 Español | [README.es.md](README.es.md) |
| 🇸🇦 Árabe | [README.ar.md](README.ar.md) | 🇫🇷 Francés | [README.fr.md](README.fr.md) |
| 🇩🇪 Alemán | [README.de.md](README.de.md) | 🇮🇳 Hindi | [README.hi.md](README.hi.md) |
| 🇮🇩 Indonesio | [README.id.md](README.id.md) | 🇮🇹 Italiano | [README.it.md](README.it.md) |
| 🇯🇵 Japonés | [README.ja.md](README.ja.md) | 🇵🇱 Polaco | [README.pl.md](README.pl.md) |
| 🇧🇷 Portugués | [README.pt.md](README.pt.md) | 🇷🇺 Ruso | [README.ru.md](README.ru.md) |
| 🇹🇷 Turco | [README.tr.md](README.tr.md) | 🇨🇳 Chino | [README.zh.md](README.zh.md) |
> 💡 **¿Quieres contribuir con una traducción?** ¡Consulta la sección de [Contribución](#contributing) para ayudarnos a añadir más idiomas!
## 🛠️ Solución de problemas
Haz clic para ver problemas comunes y soluciones
- **La tabla de formatos no aparece:** Actualiza yt-dlp a la última versión y cambia a yt-dlp nightly.
- **Fallo de descarga:** Verifica tu conexión a internet y asegúrate de que el video esté disponible.
- **Errores de descarga específicos:**
- **Videos privados:** Usa autenticación por cookies para acceder a contenido privado.
- **Contenido con restricción de edad:** Inicia sesión en tu cuenta de YouTube para ver videos restringidos.
- **Videos bloqueados geográficamente:** Considera usar una VPN para saltar restricciones regionales.
- **Videos eliminados:** El video ya no está disponible en YouTube.
- **Transmisiones en vivo:** Los directos no se pueden descargar; espera a que la transmisión termine.
- **Errores de red:** Verifica tu conexión a internet e inténtalo de nuevo.
- **URLs no válidas:** Asegúrate de que la URL sea correcta y de una plataforma compatible.
- **Contenido Premium:** Requiere suscripción a YouTube Premium.
- **Bloqueos por copyright:** El contenido está bloqueado por restricciones de derechos de autor.
- **Archivos de video y audio separados tras descarga:** Esto sucede cuando falta FFmpeg o no se detecta. YTSage requiere FFmpeg para fusionar flujos de video y audio de alta calidad.
- **Solución:** Asegúrate de que FFmpeg esté instalado y accesible en el PATH de tu sistema. Para usuarios de Windows, la opción más fácil es descargar el archivo `YTSage-v-ffmpeg.exe`, que incluye FFmpeg.
---
#### 🛡️ Advertencia de Windows Defender / Antivirus
Algunos programas antivirus pueden marcar archivos `.exe` como falsos positivos. Esta es una **limitación conocida** de las aplicaciones empaquetadas.
**Por qué sucede esto:**
- La heurística de los antivirus puede identificar erróneamente ejecutables empaquetados como sospechosos.
**Alternativas seguras:**
- ✅ **Usa la instalación de pip:** `pip install ytsage` (Recomendado)
- ✅ **Construye desde el código fuente**: siguiendo esta [guía](../.github/CI_CD_README.md)
- ✅ **Añade la aplicación a la lista blanca** en tu software antivirus.
#### 🍎 macOS: "La aplicación está dañada y no se puede abrir"
Si ves este error en macOS Sonoma o más reciente, necesitas eliminar el atributo de cuarentena.
1. **Abre el Terminal** (puedes encontrarlo usando Spotlight).
2. **Escribe el siguiente comando** pero **no presiones** Enter todavía. Asegúrate de incluir el espacio al final:
```bash
xattr -d com.apple.quarantine
```
3. **Arrastra el archivo `YTSage.app`** desde tu ventana de Finder y suéltalo directamente en la ventana del Terminal. Esto pegará automáticamente la ruta correcta del archivo.
4. **Presiona Enter** para ejecutar el comando.
5. **Intenta abrir YTSage.app de nuevo.** Ahora debería lanzarse correctamente.
---
#### **Ubicaciones de configuración (Avanzado)**
- **Windows:** `%LOCALAPPDATA%\YTSage`
- **macOS:** `~/Library/Application Support/YTSage`
- **Linux:** `~/.local/share/YTSage`
## 💖 Patrocinar
Si YTSage te ahorra tiempo, considera patrocinar el proyecto. El patrocinio ayuda a cubrir tiempo de desarrollo, pruebas en todas las plataformas y futuras mejoras.
- GitHub Sponsors: https://github.com/sponsors/oop7
- El enlace de patrocinio también está disponible directamente en la aplicación a través del diálogo Acerca de.
[](https://github.com/sponsors/oop7)
## 👥 Contribuir
¡Agradecemos las contribuciones! Aquí tienes cómo puedes ayudar:
1. 🍴 Haz un Fork del repositorio
2. 🌿 Crea tu rama de características:
```bash
git checkout -b feature/AmazingFeature
```
3. 💾 Haz commit de tus cambios:
```bash
git commit -m 'Add some AmazingFeature'
```
4. 📤 Haz Push a la rama:
```bash
git push origin feature/AmazingFeature
```
5. 🔄 Abre un Pull Request
### 🌍 Contribuir con traducciones
- Actualiza el archivo README localizado correspondiente (p. ej., `readme-translations/README.es.md`)
- Mantén las cadenas de la aplicación sincronizadas editando `ytsage/languages/.json`
- Si falta tu idioma, comienza desde `README.md` y crea `README..md`
📂 Estructura del proyecto
## YTSage - Estructura del proyecto
Este documento describe la estructura de carpetas organizada de YTSage.
### 📁 Estructura del proyecto
```
YTSage/
├── 📁 .github/ # Configuración de GitHub
│ ├── 📁 ISSUE_TEMPLATE/ # Plantillas de problemas
│ │ └── 🐛-bug-report.md # Plantilla de informe de errores
│ ├─── 📁 workflows/ # Flujos de trabajo de GitHub Actions
│ │ ├── build-linux.yml # Flujo de construcción para Linux
│ │ ├── build-macos.yml # Flujo de construcción para macOS
│ │ │── build-windows.yml # Flujo de construcción para Windows
| | └── release-all.yml # Flujo de liberación maestra
│ └── 📄 CI_CD_README.md # Documentación de CI/CD
├── 📁 branding/ # Activos de marca (Capturas de pantalla, SVGs)
│ ├── 📁 icons/ # Iconos de la aplicación
│ ├── 📁 screenshots/ # Capturas de pantalla para documentación
│ └── 📁 svg/ # Activos SVG
├── 📄 LICENSE # Archivo de licencia
├── 📄 pyproject.toml # Metadatos del proyecto y dependencias
├── 📄 README.md # Documentación del proyecto
├── 📄 requirements.txt # Dependencias de Python (dev)
└── 📁 ytsage/ # Paquete de código fuente
├── 📁 assets/ # Activos en tiempo de ejecución
│ ├── 📁 Icon/ # Iconos de la aplicación
│ └── 📁 sound/ # Archivos de audio
├── 📁 languages/ # Archivos de localización
│ ├── 📄 ar.json # Traducción al árabe
│ ├── 📄 de.json # Traducción al alemán
│ ├── 📄 en.json # Traducción al inglés
│ └── ... # Otros idiomas
├── 📁 core/ # Lógica de negocio principal
│ ├── 📄 __init__.py # Init del paquete core
│ ├── 📄 ytsage_deno.py # Integración con Deno
│ ├── 📄 ytsage_downloader.py # Funcionalidad de descarga
│ ├── 📄 ytsage_ffmpeg.py # Integración con FFmpeg
│ ├── 📄 ytsage_utils.py # Funciones de utilidad
│ └── 📄 ytsage_yt_dlp.py # Integración con yt-dlp
├── 📁 gui/ # Componentes de interfaz de usuario
│ ├── 📄 __init__.py # Init del paquete GUI
│ ├── 📄 ytsage_gui_main.py # Ventana principal de la aplicación
│ └── 📁 ytsage_gui_dialogs/ # Clases de diálogos
├── 📁 utils/ # Módulos de utilidad
│ ├── 📄 __init__.py # Init del paquete utils
│ ├── 📄 ytsage_config_manager.py # Gestión de configuración
│ └── 📄 ytsage_logger.py # Utilidad de registro
├── 📄 __init__.py # Punto de entrada del paquete
└── 📄 main.py # Script de ejecución principal
```
## ⭐️ Historial de estrellas
## Star History
## 📜 Licencia
Este proyecto está bajo la Licencia MIT - mira el archivo [LICENSE](../LICENSE) para más detalles.
## 🙏 Agradecimientos
Ver agradecimientos
Muchas gracias a todos los que han contribuido a este proyecto abriendo un problema para sugerir una mejora o informar de un error.
## ⚠️ Descargo de responsabilidad
Esta herramienta es solo para uso personal. Por favor, respeta los términos de servicio de YouTube y los derechos de los creadores de contenido.
---
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](https://github.com/oop7/YTSage/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/oop7/YTSage/releases)
[](https://github.com/oop7/YTSage/stargazers)
[](https://pypi.org/project/ytsage/)
[](https://github.com/sponsors/oop7)
**Un moderno descargador de YouTube con una interfaz PySide6 elegante.**
Descarga videos en cualquier calidad, extrae audio, obtén subtítulos y más.
### 🌍 Idiomas del README
Inglés: [EN](../README.md)
| Árabe: [AR](README.ar.md)
| Alemán: [DE](README.de.md)
| Español: [ES](README.es.md)
| Francés: [FR](README.fr.md)
| Hindi: [HI](README.hi.md)
| Indonesio: [ID](README.id.md)
| Italiano: [IT](README.it.md)
| Japonés: [JA](README.ja.md)
| Polaco: [PL](README.pl.md)
| Portugués: [PT](README.pt.md)
| Ruso: [RU](README.ru.md)
| Turco: [TR](README.tr.md)
| Chino: [ZH](README.zh.md)
