# 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

```bash
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.

```python
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.

```python
# 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.

```python
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).

```python
# 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+).

```python
# 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.