lushapp 2.0.0

package/src/lush/stats.py

@@ -0,0 +1,555 @@
+"""
+LUSH Audiophile Listening Diary & Analytics Engine
+Tracks local scrobbles, listening habits, 24-hour rhythms, FLAC recordings,
+and generates GitHub-style contribution heatmaps. 100% private & offline.
+"""
+
+from collections import Counter
+from datetime import datetime, timedelta
+import json
+import os
+from pathlib import Path
+import re
+import threading
+import time
+
+
+class StatsEngine:
+    def __init__(self, stats_file: Path, history_file: Path, recordings_dir: Path):
+        self.stats_file = Path(stats_file)
+        self.history_file = Path(history_file)
+        self.recordings_dir = Path(recordings_dir)
+        self.lock = threading.RLock()
+
+        # Analytics Storage
+        self.total_scrobbles = 0
+        self.daily_counts = {}       # "YYYY-MM-DD" -> count
+        self.hourly_counts = [0] * 24 # 0..23 -> count
+        self.artist_counts = Counter()
+        self.station_counts = Counter()
+        self.genre_counts = Counter()
+        self.recent_events = []      # list of dicts (last 500)
+        self.total_seconds_listened = 0.0
+
+        # SSD Wear Reduction & In-Memory Caching
+        self._dirty = False
+        self._last_save_time = time.time()
+        self._cached_vault = None
+        self._last_vault_time = 0.0
+        self._cached_heatmap = None
+        self._last_heatmap_time = 0.0
+        self._cached_rhythm = None
+        self._last_rhythm_time = 0.0
+
+        # Load existing stats or backfill from history
+        self._load_or_backfill()
+
+    def _clean_artist_name(self, track_title: str, station_name: str) -> str:
+        """Extract clean artist name from 'Artist - Title' or station."""
+        if not track_title:
+            return station_name or "Unknown Artist"
+        
+        # If 'Artist - Title' pattern exists
+        if " - " in track_title:
+            parts = track_title.split(" - ", 1)
+            candidate = parts[0].strip()
+            candidate = re.sub(r'^[0-9\.\s]+', '', candidate)
+            if candidate and len(candidate) > 1:
+                # Check for existing case-insensitive match to merge duplicates
+                for existing in self.artist_counts:
+                    if candidate.lower() == existing.lower():
+                        return existing
+                return candidate
+        
+        # If station represents an artist channel
+        if station_name and not any(k in station_name.lower() for k in ["somafm", "radio", "chill", "def con", "nightride", "stream"]):
+            cand = station_name.strip()
+            for existing in self.artist_counts:
+                if cand.lower() == existing.lower():
+                    return existing
+            return cand
+
+        return track_title.strip()
+
+    def _load_or_backfill(self):
+        with self.lock:
+            # 1. Load saved stats if exists
+            if self.stats_file.exists():
+                try:
+                    with open(self.stats_file, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                    self.total_scrobbles = data.get("total_scrobbles", 0)
+                    self.daily_counts = data.get("daily_counts", {})
+                    self.hourly_counts = data.get("hourly_counts", [0] * 24)
+                    self.artist_counts = Counter(data.get("artist_counts", {}))
+                    self.station_counts = Counter(data.get("station_counts", {}))
+                    self.genre_counts = Counter(data.get("genre_counts", {}))
+                    self.recent_events = data.get("recent_events", [])
+                    self.total_seconds_listened = data.get("total_seconds_listened", 0.0)
+                except Exception:
+                    pass
+
+            # 2. Ingest / backfill from history.json if stats are empty or sparse
+            if self.history_file.exists():
+                try:
+                    with open(self.history_file, "r", encoding="utf-8") as f:
+                        history_records = json.load(f)
+                    
+                    # Backfill records not already in stats
+                    if self.total_scrobbles < len(history_records):
+                        today_str = datetime.now().strftime("%Y-%m-%d")
+                        for rec in reversed(history_records):
+                            track_name = rec.get("name", "")
+                            station = rec.get("station", "Live Stream")
+                            genre = rec.get("genre", "Radio")
+                            t_str = rec.get("time", "12:00")
+                            d_str = rec.get("date", today_str)
+
+                            # Hourly inference
+                            try:
+                                hour = int(t_str.split(":")[0])
+                            except Exception:
+                                hour = 14
+
+                            artist = self._clean_artist_name(track_name, station)
+                            self.daily_counts[d_str] = self.daily_counts.get(d_str, 0) + 1
+                            if 0 <= hour <= 23:
+                                self.hourly_counts[hour] += 1
+                            self.artist_counts[artist] += 1
+                            self.station_counts[station] += 1
+                            self.genre_counts[genre] += 1
+
+                            self.recent_events.append({
+                                "track": track_name,
+                                "artist": artist,
+                                "station": station,
+                                "genre": genre,
+                                "date": d_str,
+                                "time": t_str,
+                                "timestamp": rec.get("timestamp", time.time())
+                            })
+
+                        self.total_scrobbles = len(self.recent_events)
+                        self.total_seconds_listened = self.total_scrobbles * 210.0 # ~3.5 min average per song
+                        self._save_unlocked()
+                except Exception:
+                    pass
+
+    def record_track(self, track_name: str, station: str, genre: str, url: str = ""):
+        """Record a live track event in thread-safe, non-blocking fashion."""
+        if not track_name:
+            return
+
+        with self.lock:
+            now = datetime.now()
+            d_str = now.strftime("%Y-%m-%d")
+            t_str = now.strftime("%H:%M")
+            hour = now.hour
+
+            artist = self._clean_artist_name(track_name, station)
+
+            # Prevent duplicate immediate consecutive counts
+            if self.recent_events and self.recent_events[-1].get("track") == track_name:
+                return
+
+            self.total_scrobbles += 1
+            self.total_seconds_listened += 210.0 # Average track length
+            self.daily_counts[d_str] = self.daily_counts.get(d_str, 0) + 1
+            self.hourly_counts[hour] += 1
+            self.artist_counts[artist] += 1
+            self.station_counts[station] += 1
+            self.genre_counts[genre] += 1
+
+            self.recent_events.append({
+                "track": track_name,
+                "artist": artist,
+                "station": station,
+                "genre": genre,
+                "url": url,
+                "date": d_str,
+                "time": t_str,
+                "timestamp": time.time()
+            })
+
+            # Trim history to 500 events
+            if len(self.recent_events) > 500:
+                self.recent_events = self.recent_events[-500:]
+
+            self._dirty = True
+            # Invalidate transient in-memory caches
+            self._cached_heatmap = None
+            self._cached_rhythm = None
+
+            # SSD Protection: Debounce disk writes to at most once per 60s of active playback
+            t_now = time.time()
+            if t_now - self._last_save_time >= 60.0:
+                self._last_save_time = t_now
+                threading.Thread(target=self._save_async, daemon=True).start()
+
+    def _save_unlocked(self):
+        """Atomically saves stats to disk with tempfile rename to eliminate NAND write amplification."""
+        try:
+            self.stats_file.parent.mkdir(parents=True, exist_ok=True)
+            data = {
+                "total_scrobbles": self.total_scrobbles,
+                "total_seconds_listened": self.total_seconds_listened,
+                "daily_counts": self.daily_counts,
+                "hourly_counts": self.hourly_counts,
+                "artist_counts": dict(self.artist_counts.most_common(100)),
+                "station_counts": dict(self.station_counts.most_common(100)),
+                "genre_counts": dict(self.genre_counts.most_common(50)),
+                "recent_events": self.recent_events[-100:]
+            }
+            tmp_file = self.stats_file.with_suffix(".tmp")
+            with open(tmp_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            tmp_file.replace(self.stats_file)
+            self._dirty = False
+            self._last_save_time = time.time()
+        except Exception:
+            pass
+
+    def flush(self):
+        """Force flush dirty in-memory stats to SSD on demand or shutdown."""
+        with self.lock:
+            if self._dirty:
+                self._save_unlocked()
+
+    def _save_async(self):
+        with self.lock:
+            self._save_unlocked()
+
+    # -------------------------------------------------------------
+    # Heatmap Matrix (GitHub-Style 7 rows x N weeks)
+    # -------------------------------------------------------------
+    def get_heatmap_matrix(self, num_weeks: int = 16, force: bool = False):
+        """
+        Returns a 7-row (Monday=0 to Sunday=6) by num_weeks matrix
+        of days ending on the current week. Cached in RAM to prevent CPU cycles.
+        """
+        with self.lock:
+            t_now = time.time()
+            if not force and self._cached_heatmap is not None and (t_now - self._last_heatmap_time < 4.0):
+                return self._cached_heatmap
+            today = datetime.now().date()
+            # Find the Sunday of the current week (or end of week)
+            # Monday is 0, Sunday is 6
+            start_date = today - timedelta(days=today.weekday() + (num_weeks - 1) * 7)
+
+            matrix = [[] for _ in range(7)] # 7 days: Mon(0) to Sun(6)
+            month_labels = []
+            last_month = None
+
+            cur_date = start_date
+            col_idx = 0
+
+            for week in range(num_weeks):
+                # Check for month label at start of week
+                mid_week_date = cur_date + timedelta(days=3)
+                m_str = mid_week_date.strftime("%b")
+                if m_str != last_month:
+                    month_labels.append((week, m_str))
+                    last_month = m_str
+
+                for day_row in range(7):
+                    d_str = cur_date.strftime("%Y-%m-%d")
+                    count = self.daily_counts.get(d_str, 0)
+                    is_today = (cur_date == today)
+                    is_future = (cur_date > today)
+
+                    # Intensity scale: 0..4
+                    if is_future:
+                        intensity = -1
+                    elif count == 0:
+                        intensity = 0
+                    elif count <= 5:
+                        intensity = 1
+                    elif count <= 15:
+                        intensity = 2
+                    elif count <= 30:
+                        intensity = 3
+                    else:
+                        intensity = 4
+
+                    matrix[day_row].append({
+                        "date": d_str,
+                        "date_obj": cur_date,
+                        "count": count,
+                        "intensity": intensity,
+                        "is_today": is_today,
+                        "is_future": is_future,
+                        "day_name": cur_date.strftime("%a")
+                    })
+                    cur_date += timedelta(days=1)
+
+            # Streaks
+            streaks = self.get_streaks()
+            result = (matrix, month_labels, streaks)
+            self._cached_heatmap = result
+            self._last_heatmap_time = t_now
+            return result
+
+    def get_streaks(self):
+        """Calculates current streak, longest streak, and total active days."""
+        with self.lock:
+            if not self.daily_counts:
+                return {"current_streak": 0, "longest_streak": 0, "total_active_days": 0}
+
+            active_dates = sorted([datetime.strptime(k, "%Y-%m-%d").date() for k, v in self.daily_counts.items() if v > 0])
+            if not active_dates:
+                return {"current_streak": 0, "longest_streak": 0, "total_active_days": 0}
+
+            total_active_days = len(active_dates)
+            today = datetime.now().date()
+            yesterday = today - timedelta(days=1)
+
+            # Current streak
+            current_streak = 0
+            check_date = today if (today in active_dates) else yesterday
+            while check_date in active_dates:
+                current_streak += 1
+                check_date -= timedelta(days=1)
+
+            # Longest streak
+            longest_streak = 0
+            cur_seq = 0
+            for i in range(len(active_dates)):
+                if i == 0:
+                    cur_seq = 1
+                else:
+                    if active_dates[i] == active_dates[i-1] + timedelta(days=1):
+                        cur_seq += 1
+                    else:
+                        cur_seq = 1
+                longest_streak = max(longest_streak, cur_seq)
+
+            return {
+                "current_streak": max(1, current_streak) if (today in active_dates or yesterday in active_dates) else 0,
+                "longest_streak": max(longest_streak, current_streak),
+                "total_active_days": total_active_days
+            }
+
+    # -------------------------------------------------------------
+    # Top Charts & Leaderboards
+    # -------------------------------------------------------------
+    def get_top_artists(self, limit: int = 10, timeframe: str = "all"):
+        with self.lock:
+            if timeframe == "all":
+                return self.artist_counts.most_common(limit)
+
+            now = datetime.now()
+            if timeframe == "today":
+                d_match = now.strftime("%Y-%m-%d")
+            else: # this month
+                d_match = now.strftime("%Y-%m")
+
+            filtered_counts = Counter()
+            for ev in self.recent_events:
+                if ev.get("date", "").startswith(d_match):
+                    filtered_counts[ev.get("artist", "Unknown")] += 1
+            return filtered_counts.most_common(limit) or self.artist_counts.most_common(limit)
+
+    def get_top_stations(self, limit: int = 10, timeframe: str = "all"):
+        with self.lock:
+            if timeframe == "all":
+                return self.station_counts.most_common(limit)
+
+            now = datetime.now()
+            if timeframe == "today":
+                d_match = now.strftime("%Y-%m-%d")
+            else:
+                d_match = now.strftime("%Y-%m")
+
+            filtered_counts = Counter()
+            for ev in self.recent_events:
+                if ev.get("date", "").startswith(d_match):
+                    filtered_counts[ev.get("station", "Radio")] += 1
+            return filtered_counts.most_common(limit) or self.station_counts.most_common(limit)
+
+    def get_top_genres(self, limit: int = 6):
+        with self.lock:
+            total = sum(self.genre_counts.values()) or 1
+            items = []
+            for g, count in self.genre_counts.most_common(limit):
+                pct = int((count / total) * 100)
+                items.append((g, count, pct))
+            return items
+
+    # -------------------------------------------------------------
+    # 24-Hour Listening Rhythm & Sonic Persona
+    # -------------------------------------------------------------
+    def get_hourly_rhythm(self, force: bool = False):
+        with self.lock:
+            t_now = time.time()
+            if not force and self._cached_rhythm is not None and (t_now - self._last_rhythm_time < 4.0):
+                return self._cached_rhythm
+            max_val = max(self.hourly_counts) or 1
+            peak_hour = self.hourly_counts.index(max_val)
+
+            if 22 <= peak_hour or peak_hour <= 4:
+                persona = "The Midnight Coder (Night Owl)"
+                desc = f"Peak listening late at night ({peak_hour:02d}:00). Optimal for deep coding & chill sessions."
+            elif 5 <= peak_hour <= 11:
+                persona = "The Morning Scholar (Focused & Alert)"
+                desc = f"Peak listening in the morning ({peak_hour:02d}:00). Tuned for daily planning & flow."
+            elif 12 <= peak_hour <= 17:
+                persona = "The Afternoon Flow (Studio State)"
+                desc = f"Peak listening midday ({peak_hour:02d}:00). Sustained high-energy focus."
+            else:
+                persona = "The Sunset Voyager (Twilight Groove)"
+                desc = f"Peak listening evening ({peak_hour:02d}:00). Unwinding with ambient & beats."
+
+            res = {
+                "counts": list(self.hourly_counts),
+                "peak_hour": peak_hour,
+                "persona": persona,
+                "desc": desc
+            }
+            self._cached_rhythm = res
+            self._last_rhythm_time = t_now
+            return res
+
+    # -------------------------------------------------------------
+    # Audiophile Vault (Lossless FLAC recordings)
+    # -------------------------------------------------------------
+    def get_flac_vault(self, force: bool = False):
+        with self.lock:
+            t_now = time.time()
+            if not force and self._cached_vault is not None and (t_now - self._last_vault_time < 5.0):
+                return self._cached_vault
+
+            files = []
+            tot_bytes = 0
+            if self.recordings_dir.exists():
+                for p in self.recordings_dir.glob("*.*"):
+                    if p.suffix.lower() in (".flac", ".mp3", ".m4a", ".ogg"):
+                        try:
+                            sz = p.stat().st_size
+                            tot_bytes += sz
+                            mtime = p.stat().st_mtime
+                            d_str = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M")
+                            files.append({
+                                "name": p.name,
+                                "path": p,
+                                "size_mb": sz / (1024 * 1024),
+                                "format": "24-Bit FLAC" if p.suffix.lower() == ".flac" else p.suffix.upper()[1:],
+                                "date": d_str,
+                                "mtime": mtime
+                            })
+                        except Exception:
+                            pass
+
+            files.sort(key=lambda x: x["mtime"], reverse=True)
+            self._cached_vault = {
+                "files": files,
+                "total_files": len(files),
+                "total_mb": tot_bytes / (1024 * 1024)
+            }
+            self._last_vault_time = t_now
+            return self._cached_vault
+
+    # -------------------------------------------------------------
+    # Earned Badges
+    # -------------------------------------------------------------
+    def get_earned_badges(self, state=None):
+        with self.lock:
+            vault = self.get_flac_vault()
+            streaks = self.get_streaks()
+            badges = []
+
+            # 1. Pop Royalty Starrer
+            brit_count = sum(c for a, c in self.artist_counts.items() if "britney" in a.lower() or "pop" in a.lower())
+            if brit_count >= 5 or "Britney Spears" in self.artist_counts:
+                badges.append(("→", "Pop Royalty Starrer", "Tuned into Britney Spears & Pop Royalty"))
+
+            # 2. 24-Bit FLAC Archivist
+            flac_count = sum(1 for f in vault["files"] if f["format"] == "24-Bit FLAC")
+            if flac_count >= 1:
+                badges.append(("◆", "Lossless FLAC Master", f"Archived {flac_count} bit-perfect master tracks"))
+
+            # 3. Night Owl Certified
+            night_plays = sum(self.hourly_counts[22:]) + sum(self.hourly_counts[:5])
+            if night_plays >= 5:
+                badges.append(("◈", "Night Owl Certified", f"{night_plays} sessions during late night hours"))
+
+            # 4. Stream Streaker
+            if streaks["current_streak"] >= 3 or streaks["longest_streak"] >= 3:
+                badges.append(("▲", "Stream Streaker", f"{streaks['longest_streak']}-day listening streak"))
+
+            # 5. 144Hz Fluid Purist
+            if state and getattr(state, "framerate", 60) >= 120:
+                badges.append(("→", "144Hz Fluid Purist", "Configured for ultra-high refresh rate"))
+
+            # 6. Lo-Fi Scholar
+            lofi_count = sum(c for g, c in self.genre_counts.items() if "lofi" in g.lower() or "chill" in g.lower())
+            if lofi_count >= 10:
+                badges.append(("◈", "Lo-Fi Scholar", f"{lofi_count} study & chill sessions logged"))
+
+            # Fallback badges if new
+            if len(badges) < 4:
+                badges.append(("▶", "Audiophile Initiate", f"Logged {self.total_scrobbles} lifetime tracks"))
+                badges.append(("→", "Global Radio Explorer", f"Explored {len(self.station_counts)} distinct stations"))
+
+            return badges
+
+    # -------------------------------------------------------------
+    # Export ASCII Diary Report
+    # -------------------------------------------------------------
+    def export_report(self, dest_path: Path = None) -> Path:
+        with self.lock:
+            if not dest_path:
+                dest_dir = Path.home() / "Music"
+                dest_dir.mkdir(parents=True, exist_ok=True)
+                dest_path = dest_dir / f"lush_insights_{datetime.now().strftime('%Y%m%d_%H%M%S')}.txt"
+
+            vault = self.get_flac_vault()
+            streaks = self.get_streaks()
+            rhythm = self.get_hourly_rhythm()
+
+            hours_listened = self.total_seconds_listened / 3600.0
+            data_mb = (self.total_scrobbles * 210.0 * 16.0) / 1024.0 # ~128kbps approx
+
+            lines = [
+                "═══════════════════════════════════════════════════════════════════",
+                "          LUSH AUDIOPHILE LISTENING DIARY & INSIGHTS REPORT         ",
+                "═══════════════════════════════════════════════════════════════════",
+                f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+                "",
+                "▶ LIFETIME AUDIOPHILE TOTALS",
+                f"  • Total Tracks Scrobbled : {self.total_scrobbles:,}",
+                f"  • Estimated Listening Time: {hours_listened:.1f} hours",
+                f"  • FLAC Master Captures   : {vault['total_files']} files ({vault['total_mb']:.2f} MB)",
+                f"  • Data Streamed          : ~{data_mb:.1f} MB",
+                f"  • Current Streak         : {streaks['current_streak']} days (Best: {streaks['longest_streak']} days)",
+                f"  • Sonic Persona          : {rhythm['persona']}",
+                "",
+                "▶ TOP 10 ARTISTS",
+            ]
+
+            for idx, (artist, count) in enumerate(self.get_top_artists(10), 1):
+                pct = int((count / max(1, self.total_scrobbles)) * 100)
+                bar = "█" * min(20, max(1, int(pct * 0.4)))
+                lines.append(f"  {idx:>2}. {artist:<24} {bar:<20} {count:>3} plays ({pct:>2}%)")
+
+            lines.append("")
+            lines.append("▶ TOP 10 STATIONS & STREAMS")
+            for idx, (st, count) in enumerate(self.get_top_stations(10), 1):
+                pct = int((count / max(1, self.total_scrobbles)) * 100)
+                bar = "█" * min(20, max(1, int(pct * 0.4)))
+                lines.append(f"  {idx:>2}. {st:<24} {bar:<20} {count:>3} plays ({pct:>2}%)")
+
+            lines.append("")
+            lines.append("▶ GENRE BREAKDOWN")
+            for g, count, pct in self.get_top_genres(6):
+                bar = "█" * min(20, max(1, int(pct * 0.4)))
+                lines.append(f"  • {g:<22} {bar:<20} {pct:>2}% ({count} plays)")
+
+            lines.append("")
+            lines.append("═══════════════════════════════════════════════════════════════════")
+            lines.append("Generated by LUSH Terminal Audiophile Player (github.com/pseudoshell/lush)")
+
+            report_text = "\n".join(lines)
+            with open(dest_path, "w", encoding="utf-8") as f:
+                f.write(report_text)
+
+            return dest_path