# Home Assistant Integration Setup Guide

## 🏠 YouTube Predownloader Home Assistant Integration

This integration provides real-time monitoring of your YouTube predownloader through Home Assistant using MQTT.

### 📊 **Monitored Metrics:**

1. **Download Queue Length** - Number of videos waiting to download
2. **Conversion Queue Length** - Number of videos waiting for conversion  
3. **Download Progress** - Overall download completion percentage
4. **Conversion Progress** - Individual conversion progress
5. **Current Download Progress** - Real-time progress of active download (0-100%)
6. **Current Download File** - Name of currently downloading file
7. **Current Conversion Progress** - Real-time progress of active conversion (0-100%)
8. **Current Conversion File** - Name of currently converting file
9. **Download Speed** - Current download speed in MB/s
10. **CPU Usage** - Process CPU utilization percentage
11. **Memory Usage** - Process memory utilization (% and MB)
12. **Active Downloads** - Number of currently downloading videos
13. **Active Conversions** - Number of currently converting videos

### 🔧 **Setup Instructions:**

#### 1. **Enable MQTT in Home Assistant**

Add to your `configuration.yaml`:
```yaml
mqtt:
  broker: 192.168.1.100  # Your Home Assistant IP
  port: 1883
  username: mqtt_user     # Optional
  password: mqtt_pass     # Optional
```

Or install the "Mosquitto broker" add-on from the Home Assistant Add-on Store.

#### 2. **Configure MQTT Settings**

Copy `config_example.py` to `config.py` and update:
```python
MQTT_BROKER = "192.168.1.100"  # Your Home Assistant IP
MQTT_PORT = 1883
MQTT_USERNAME = "mqtt_user"    # If authentication enabled
MQTT_PASSWORD = "mqtt_pass"    # If authentication enabled
```

#### 3. **Install Dependencies**

```bash
# Install required Python packages
pip3 install paho-mqtt psutil

# Or using the included installation script:
sudo ./install.sh
```

The dependencies are automatically installed when using the `install.sh` script.

#### 4. **Run the YouTube Predownloader**

The integration will automatically start when you run:
```bash
python3 main.py
```

### 📱 **Home Assistant Dashboard**

The sensors will automatically appear in Home Assistant. Create a dashboard with:

```yaml
type: entities
title: YouTube Predownloader
entities:
  - sensor.youtube_download_queue
  - sensor.youtube_conversion_queue
  - sensor.youtube_download_progress
  - sensor.youtube_conversion_progress
  - sensor.youtube_current_download_progress
  - sensor.youtube_current_download_file
  - sensor.youtube_current_conversion_progress
  - sensor.youtube_current_conversion_file
  - sensor.youtube_download_speed
  - sensor.youtube_cpu_usage
  - sensor.youtube_memory_usage
  - sensor.youtube_active_downloads
  - sensor.youtube_active_conversions
```

### 📈 **Example Dashboard Cards:**

#### **Progress Cards:**
```yaml
type: gauge
entity: sensor.youtube_current_download_progress
min: 0
max: 100
name: Current Download
```

```yaml
type: gauge
entity: sensor.youtube_current_conversion_progress
min: 0
max: 100
name: Current Conversion
```

#### **Current Operation Cards:**
```yaml
type: markdown
content: |
  **Currently Downloading:**
  {{ states('sensor.youtube_current_download_file') }}
  
  **Currently Converting:**
  {{ states('sensor.youtube_current_conversion_file') }}
```

#### **Overall Progress Card:**
```yaml
type: gauge
entity: sensor.youtube_download_progress
min: 0
max: 100
name: Overall Progress
```

#### **Queue Status:**
```yaml
type: horizontal-stack
cards:
  - type: statistic
    entity: sensor.youtube_download_queue
    name: Download Queue
  - type: statistic
    entity: sensor.youtube_conversion_queue
    name: Conversion Queue
```

#### **System Performance:**
```yaml
type: history-graph
entities:
  - sensor.youtube_cpu_usage
  - sensor.youtube_memory_usage
hours_to_show: 2
```

### 🔔 **Automation Examples:**

#### **Notify when downloads complete:**
```yaml
automation:
  - alias: "YouTube Downloads Complete"
    trigger:
      platform: state
      entity_id: sensor.youtube_download_progress
      to: "100"
    action:
      service: notify.mobile_app
      data:
        message: "🎬 All YouTube videos downloaded!"
```

#### **Alert on high CPU usage:**
```yaml
automation:
  - alias: "YouTube High CPU Alert"
    trigger:
      platform: numeric_state
      entity_id: sensor.youtube_cpu_usage
      above: 80
      for: "00:05:00"
    action:
      service: notify.mobile_app
      data:
        message: "⚠️ YouTube predownloader using high CPU: {{ states('sensor.youtube_cpu_usage') }}%"
```

### 🐛 **Troubleshooting:**

#### **Connection Issues:**
- Verify MQTT broker is running in Home Assistant
- Check IP address and port in config.py
- Ensure firewall allows MQTT traffic (port 1883)

#### **No Sensors Appearing:**
- Check Home Assistant logs for MQTT discovery messages
- Restart Home Assistant after first run
- Verify MQTT integration is enabled

#### **Permission Errors:**
```bash
# If psutil can't access process info:
sudo python3 main.py
```

### 🎯 **MQTT Topics:**

The integration publishes to these topics:
- `youtube_predownloader/sensor/*/state` - Individual sensor values
- `youtube_predownloader/status` - Combined JSON status
- `homeassistant/sensor/youtube_predownloader_*/config` - Discovery configs

### 🚀 **Features:**

- ✅ **Auto-Discovery** - Sensors automatically appear in Home Assistant
- ✅ **Real-time Updates** - 10-second update intervals
- ✅ **Background Operation** - Continues monitoring after script completion
- ✅ **Resource Monitoring** - CPU and memory usage tracking
- ✅ **Queue Management** - Visual queue status and progress
- ✅ **Error Handling** - Graceful handling of connection issues