tidown 1.0

Cliente profesional para buscar y descargar música de Tidal en FLAC/MP3 con metadatos completos.

TiDown 🔱

TiDown es una librería de Python minimalista y potente para interactuar con Tidal. Diseñada bajo el patrón fachada: una sola clase maestra para buscar y descargar música en MP3, FLAC y Hi-Res (Master), preservando metadatos y carátulas en alta definición.

⚠️ Aviso: Esta herramienta fue creada exclusivamente con fines educativos y de archivado personal. Necesitas una cuenta válida de Tidal para obtener tu token.

🚀 Características

• Fachada Unificada: Todo se maneja desde la clase TiDown.
• Formatos Nativos: Descarga real en .mp3 (320kbps), .flac (16-bit) y Master (24-bit).
• Búsqueda JSON: Obtén resultados limpios y listos para usar en tu frontend o scripts.
• Tagging Automático: Metadatos completos (Artista, Álbum, Año, Track, Cover HD).
• Nombres Inteligentes: Plantillas personalizables (Ej: {Artist} - {Title}).
• Interfaz Limpia: Logs minimalistas y confirmaciones claras.

📋 Requisitos

1. Python 3.7+
2. FFmpeg: Debe estar instalado en tu sistema y accesible desde la terminal (PATH).
   • Windows: winget install ffmpeg
   • Linux: sudo apt install ffmpeg
   • Mac: brew install ffmpeg

📦 Instalación

pip install tidown

🛠️ Guía de Uso

1. Iniciar Sesión Necesitas tu Bearer Token y Client ID de una sesión Web válida.

from tidown import TiDown

TOKEN = "Bearer tu_token_largo_aqui..."
CLIENT = "CzET4vdadNUFQ5JU"  # Ejemplo de Client ID común

# Iniciamos la API
api = TiDown(token=TOKEN, client_id=CLIENT)

2. Buscar Canciones 🔎 El buscador retorna un JSON String con los resultados, ideal para procesar.

# Buscar 5 resultados
json_resultados = api.search("Daft Punk Get Lucky", limit=5)

print(json_resultados)

3. Descargar en MP3 (320kbps) 🎧 Ideal para ahorrar espacio. La librería convierte y etiqueta automáticamente.

track_id = "335104211"

# Guardar con nombre personalizado fijo
# Se guardará como: "mi_cancion.mp3"
api.save_mp3(track_id, name="mi_cancion")

4. Descargar en FLAC (Calidad CD) 💿 Calidad Lossless estándar (16-bit / 44.1kHz).

# Usando plantilla de nombre automática
# Se guardará como: "Daft Punk - Get Lucky.flac"
api.save_flac(track_id, name="{Artist} - {Title}")

5. Descargar en Hi-Res / Master 🌟 Máxima calidad disponible (24-bit / 96kHz+).

# Guardar en una carpeta específica con formato de Año
# Se guardará en: C:/Musica/2013 - Get Lucky.flac
api.save_hires(track_id, name="{Year} - {Title}", output_folder="C:/Musica/Master")

🧩 Plantillas de Nombre Disponibles Puedes combinar estas etiquetas en el parámetro name para que el archivo se renombre solo:

• *{Title}: Título de la canción.
• *{Artist}: Artista principal.
• *{Album}: Nombre del álbum.
• *{Year}: Año de lanzamiento.
• *{Track}: Número de pista.

Ejemplo complejo: "{Artist} - {Album} - {Track} {Title}"

⚖️ Licencia Distribuido bajo la licencia MIT. Consulta el archivo *LICENSE para más información.