Uncover the story of your musical taste with this powerful AppDaemon script for Home Assistant. Go beyond simple play counts and dive deep into your listening habits with automatically generated, beautiful, and insightful music charts.
This isn't just a tracker; it's your personal music historian, complete with an optional AI musicologist that provides stunning visual and analytical reports on what you've been listening to.
Ever wonder what the real soundtrack to your life is? Go beyond simple play counts and discover the true story of your musical taste with Music Tracker & AI Insights, a powerful AppDaemon application for Home Assistant.
This isn't just a scrobbler; it's your personal music historian that passively logs your listening habits and transforms that data into beautiful, insightful, and dynamic charts. Plus, with an optional AI musicologist, you can receive stunning analytical reports, artist visualizations, and even music-themed mini-games based on your unique listening DNA.
Best of all, it's designed to be self-maintaining, automatically cleaning and optimizing its own database to stay fast and efficient forever.
- ✅ Passive Music Tracking: Automatically logs every song you listen to across configured Home Assistant media players (Sonos, Volumio, Spotify, etc.).
- 📊 Dynamic Charts: Generates daily, weekly, monthly, and yearly charts for your top songs, artists, albums, and even your favorite radio stations or playlists.
- 📈 Historical Analysis: See how your top songs rise and fall with position change indicators (▲, ▼, NEW).
- 🚀 Self-Maintaining Database:
- Intelligently identifies and removes "skipped" tracks (songs played for less than a minute).
- Automatically prunes old chart data to keep the database lean and fast.
- Reclaims disk space by running
VACUUMafter cleanup. Set it and forget it!
- 🧠 AI-Powered Insights (Optional):
- Connect a Generative AI service (like the
google_generative_ai_conversationintegration). - Receive stunning, self-contained HTML reports with deep analysis, new music recommendations, and fun facts.
- Get a unique, AI-generated image of your top artist and interactive music trivia games!
- Connect a Generative AI service (like the
- 📱 Modern Web Interface: All charts are rendered into a single, clean HTML page that looks great on both desktop and mobile.
- 🌓 Light & Dark Mode: Automatically adapts to your system's theme with a manual override toggle.
- ⚡ On-Demand Updates: Trigger chart refreshes instantly from the web interface via a webhook or directly from a Home Assistant automation.
- A working Home Assistant installation.
- The AppDaemon Add-on installed and running.
- (Optional) A configured Generative AI integration (e.g., Google Generative AI) to enable the AI features.
- Navigate to your AppDaemon configuration folder (e.g.,
/config/appdaemon/apps). - Create a new file inside the
appsfolder namedmusic_tracker.py. - Copy the entire content of the
music_tracker.pyscript from this repository and paste it into your new file.
Open your apps.yaml file (in the /config/appdaemon/apps directory) and add the following block. Customize it to fit your setup.
music_tracker:
module: music_tracker
class: MusicTracker
# --- Required Settings ---
# A list of all media_player entities you want to monitor.
media_players:
- media_player.living_room_sonos
- media_player.kitchen_display
- media_player.bedroom_speaker
# The full path to the database file. Using the /config/ folder is recommended.
db_path: "/config/music_data_history.db"
# The full path where the final HTML page will be saved.
# This MUST be inside your Home Assistant 'www' directory.
html_output_path: "/config/www/music_charts.html"
# --- AI & Chart Generation ---
# The service call for your Generative AI integration. Set to false to disable.
ai_service: "google_generative_ai_conversation/generate_content"
# Time of day (24-hour HH:MM:SS format) to automatically update the charts.
update_time: "23:59:00"
# --- Database Optimization (Highly Recommended!) ---
# Schedule to run the cleanup process.
# This example runs every Sunday at 3:05 AM.
cleanup_schedule: "03:05:00"
cleanup_day_of_week: "sun"
# Enable this to actually delete/prune records.
cleanup_execute_on_run: true
# Enable this to shrink the database file size after cleanup.
cleanup_vacuum_on_complete: true
# --- Fine-Tuning ---
# How long a song must play (in seconds) to be counted.
duration: 30
# How many unique songs from an album must be played for it to appear.
min_songs_for_album: 4
# Set to true if you want the "Update Charts" button in the web interface.
# See Step 4 below to set up the required automation.
webhook: true
# This is the helper toggle the script listens to for manual or webhook updates.
chart_trigger_boolean: "input_boolean.music_charts_update"
# Run the chart generation immediately when AppDaemon starts.
run_on_startup: TrueTo allow Home Assistant to serve the music_charts.html page, you must explicitly whitelist the www directory.
-
Open your main
configuration.yamlfile. -
Add the following lines. If you already have a
homeassistant:block, add theallowlist_external_dirsline under it.homeassistant: # This line is essential for serving files from the www folder. allowlist_external_dirs: - /config/www
-
Save the
configuration.yamlfile. -
Restart Home Assistant (not just AppDaemon) for this change to take effect. You can do this from Settings > System > Restart.
To trigger updates from Home Assistant or from the chart page itself, you need a helper toggle and an automation.
This toggle is the "switch" that tells the script to run an update.
- In Home Assistant, go to Settings > Devices & Services > Helpers.
- Click Create Helper and select Toggle.
- Name it
Music Charts Update. This creates an entityinput_boolean.music_charts_update, which matches thechart_trigger_booleanin the config above.
You can now turn this toggle on anytime in Home Assistant to trigger an immediate update.
This automation connects the "Update Charts" button on the HTML page to the toggle you just created.
- Go to Settings > Automations & Scenes.
- Click Create Automation and choose Start with an empty automation.
- Switch to YAML mode by clicking the three-dots menu in the top right.
- Paste the following YAML code and save it:
alias: "Trigger Music Charts Update via Webhook"
description: "Listens for a webhook from the music chart page and turns on the update toggle."
trigger:
- platform: webhook
webhook_id: Update_Music_Charts # This ID must be exact
action:
- service: input_boolean.turn_on
target:
entity_id: input_boolean.music_charts_update # The helper you created
mode: singleThe update flow is now complete: Button on HTML Page → Webhook → Automation → Turns on Helper Toggle → AppDaemon Script Runs.
Once the script has run and generated the file, you can access your personal music charts at:
http://<your-home-assistant-ip>:8123/local/music_charts.html
- Replace
<your-home-assistant-ip>with the actual IP address or hostname of your Home Assistant instance. - Bookmark this page, or add it as a
webpagecard to one of your dashboards for easy access!
-
I get a 404 Not Found error when trying to view the page:
- This is the most common issue. You almost certainly missed or made a mistake in Step 3: Configure Home Assistant
configuration.yaml. - Ensure
allowlist_external_dirs: - /config/wwwis in yourconfiguration.yaml. - Make sure you restarted Home Assistant after adding it.
- Verify that the
music_charts.htmlfile actually exists inside your/config/wwwfolder.
- This is the most common issue. You almost certainly missed or made a mistake in Step 3: Configure Home Assistant
-
Charts are not updating:
- Check the AppDaemon logs for any errors related to
music_tracker. Errors are usually very descriptive. - Ensure your
db_pathandhtml_output_pathare correct and that AppDaemon has permission to write to those locations. - Manually trigger an update by turning on your helper toggle in Developer Tools > States.
- Check the AppDaemon logs for any errors related to
-
The "Update Charts" button doesn't work:
- Confirm that
webhook: Trueis set in yourapps.yaml. - Double-check that your automation's Webhook ID is exactly
Update_Music_Charts. - Open your browser's developer tools (F12) on the charts page, go to the Console tab, click the button, and see if any network errors appear.
- Confirm that
-
AI Analysis is missing:
- Verify your
ai_serviceis correctly configured and that the integration is working in Home Assistant. - Check the AppDaemon logs. AI generation can sometimes fail or time out, and the logs will contain the error details.
- Generating the report can take 30-120 seconds. Be patient after triggering an update.
- Verify your