YouTube_predownloader/HOMEASSISTANT_SETUP.md

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:

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:

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

# 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:

python3 main.py

📱 Home Assistant Dashboard

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

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:

type: gauge
entity: sensor.youtube_current_download_progress
min: 0
max: 100
name: Current Download

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

Current Operation Cards:

type: markdown
content: |
  **Currently Downloading:**
  {{ states('sensor.youtube_current_download_file') }}
  
  **Currently Converting:**
  {{ states('sensor.youtube_current_conversion_file') }}

Overall Progress Card:

type: gauge
entity: sensor.youtube_download_progress
min: 0
max: 100
name: Overall Progress

Queue Status:

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:

type: history-graph
entities:
  - sensor.youtube_cpu_usage
  - sensor.youtube_memory_usage
hours_to_show: 2

🔔 Automation Examples:

Notify when downloads complete:

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:

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:

# 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