add background service for fetching game metadata from Steam Store API

aanderse · aanderse · commit 5990592d9954 · 2025-12-26T11:32:15.000-05:00
diff --git a/addon.xml b/addon.xml
@@ -9,6 +9,7 @@
     <extension point="xbmc.python.pluginsource" library="addon.py">
         <provides>game executable</provides>
     </extension>
+    <extension point="xbmc.service" library="service.py" start="login" />
     <extension point="xbmc.addon.metadata">
         <summary lang="en">Access your Steam library from Kodi</summary>
         <description lang="en">With this addon you can view your entire Steam library right from Kodi.[CR]This addon requires that you have a Steam account, have the Steam application installed, know your 17 digit Steam ID, and create a Steam API key.[CR][CR]To find your 17 digit Steam ID log into https://steamcommunity.com/, click on your username in the top right corner, and select view profile. Your 17 digit Steam ID will be in your web browsers address bar as the last 17 digits of the url.[CR][CR]To create a Steam API key log into https://steamcommunity.com/dev/apikey and create one. You could use "localhost" for the domain when prompted.</description>
diff --git a/resources/main.py b/resources/main.py
@@ -5,6 +5,7 @@
 import xbmcplugin
 
 from . import arts
+from . import metadata
 from . import registry
 from . import steam
 from .util import *
@@ -134,6 +135,7 @@ def run(appid):
 def delete_cache():
     steam.delete_cache()
     arts.delete_cache()
+    metadata.delete_cache()
 
 
 def create_directory_items(app_entries):
@@ -154,15 +156,44 @@ def create_directory_items(app_entries):
     # Resolve all artwork URLs in parallel (with fallback checking)
     all_art = arts.resolve_art_for_all_games(app_entries)
 
+    # Fetch metadata for all games (cached or from API)
+    appids = [str(app['appid']) for app in app_entries]
+    all_metadata = metadata.get_metadata_for_games(appids)
+
     directory_items = []
     for app_entry in app_entries:
         appid = str(app_entry['appid'])
         name = app_entry['name']
+        game_metadata = all_metadata.get(appid, {})
 
         run_url = plugin.url_for(run, appid=appid)
         item = xbmcgui.ListItem(name)
         item.setUniqueIDs({'steam': appid, 'steam_img_icon': app_entry['img_icon_url']})
-        item.setInfo('video', {'playcount': app_entry.get('playtime_forever', 0)})
+
+        # Build info labels with metadata
+        info_labels = {
+            'title': name,
+            'playcount': app_entry.get('playtime_forever', 0),
+        }
+
+        if game_metadata:
+            if game_metadata.get('short_description'):
+                info_labels['plot'] = game_metadata['short_description']
+            if game_metadata.get('genres'):
+                info_labels['genre'] = ', '.join(game_metadata['genres'])
+            if game_metadata.get('developers'):
+                info_labels['studio'] = game_metadata['developers'][0]
+            if game_metadata.get('release_date'):
+                # Try to extract year from release date
+                try:
+                    year = int(game_metadata['release_date'].split()[-1])
+                    info_labels['year'] = year
+                except:
+                    pass
+            if game_metadata.get('metacritic'):
+                info_labels['rating'] = game_metadata['metacritic'] / 10.0
+
+        item.setInfo('video', info_labels)
         item.setContentLookup(False)  # Tells Kodi not to send HEAD requests (used to determine MIME type for example) to the item's run URL.
 
         item.addContextMenuItems([('Play', 'RunPlugin(' + run_url + ')'),
diff --git a/resources/metadata.py b/resources/metadata.py
@@ -0,0 +1,252 @@
+"""
+Fetch and cache game metadata from Steam Store API.
+
+Rate limited to respect Steam's API limits (~200 requests per 5 minutes).
+Metadata is fetched by a background service and cached for 30 days.
+"""
+import json
+import os
+import sqlite3
+import time
+
+import requests
+import xbmcaddon
+import xbmcvfs
+
+from .util import log
+
+__addon__ = xbmcaddon.Addon()
+
+# Cache setup
+addonUserDataFolder = xbmcvfs.translatePath(__addon__.getAddonInfo('profile'))
+METADATA_CACHE_FILE = xbmcvfs.translatePath(os.path.join(addonUserDataFolder, 'metadata_cache.sqlite'))
+
+# Cache duration: 30 days in seconds
+CACHE_DURATION = 30 * 24 * 60 * 60
+
+# Steam Store API
+STEAM_STORE_API = 'https://store.steampowered.com/api/appdetails'
+
+# Rate limiting: Steam allows ~200 requests per 5 minutes
+# We'll be conservative: 1 request per 2 seconds
+RATE_LIMIT_DELAY = 2.0  # seconds between requests
+
+
+def _get_last_request_time():
+    """Get the last API request timestamp from the database."""
+    try:
+        conn = sqlite3.connect(METADATA_CACHE_FILE)
+        cursor = conn.execute(
+            "SELECT value FROM settings WHERE key = 'last_request_time'"
+        )
+        row = cursor.fetchone()
+        conn.close()
+        if row:
+            return float(row[0])
+    except:
+        pass
+    return 0
+
+
+def _set_last_request_time(timestamp):
+    """Store the last API request timestamp in the database."""
+    try:
+        conn = sqlite3.connect(METADATA_CACHE_FILE)
+        conn.execute(
+            "INSERT OR REPLACE INTO settings (key, value) VALUES ('last_request_time', ?)",
+            (str(timestamp),)
+        )
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        log("Failed to store last_request_time: {}".format(e))
+
+
+def get_time_until_next_request():
+    """Get seconds until we can make another API request. Returns 0 if ready."""
+    last_time = _get_last_request_time()
+    elapsed = time.time() - last_time
+    if elapsed >= RATE_LIMIT_DELAY:
+        return 0
+    return RATE_LIMIT_DELAY - elapsed
+
+
+def can_make_request():
+    """Check if we can make an API request without violating rate limits."""
+    return get_time_until_next_request() <= 0
+
+
+def init_cache():
+    """Initialize the metadata cache database."""
+    os.makedirs(os.path.dirname(METADATA_CACHE_FILE), exist_ok=True)
+    conn = sqlite3.connect(METADATA_CACHE_FILE)
+    conn.execute('''
+        CREATE TABLE IF NOT EXISTS metadata (
+            appid TEXT PRIMARY KEY,
+            data TEXT,
+            fetched_at INTEGER
+        )
+    ''')
+    conn.execute('''
+        CREATE TABLE IF NOT EXISTS settings (
+            key TEXT PRIMARY KEY,
+            value TEXT
+        )
+    ''')
+    conn.commit()
+    conn.close()
+
+
+def get_cached_metadata(appid):
+    """Get cached metadata for an appid, or None if not cached/expired."""
+    try:
+        conn = sqlite3.connect(METADATA_CACHE_FILE)
+        cursor = conn.execute(
+            'SELECT data, fetched_at FROM metadata WHERE appid = ?',
+            (str(appid),)
+        )
+        row = cursor.fetchone()
+        conn.close()
+
+        if row:
+            data, fetched_at = row
+            # Check if cache is still valid
+            if time.time() - fetched_at < CACHE_DURATION:
+                return json.loads(data)
+    except:
+        pass
+    return None
+
+
+def cache_metadata(appid, data):
+    """Store metadata in cache."""
+    try:
+        conn = sqlite3.connect(METADATA_CACHE_FILE)
+        conn.execute(
+            'INSERT OR REPLACE INTO metadata (appid, data, fetched_at) VALUES (?, ?, ?)',
+            (str(appid), json.dumps(data), int(time.time()))
+        )
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        log("Failed to cache metadata for {}: {}".format(appid, e))
+
+
+def fetch_metadata_from_api(appid):
+    """Fetch metadata for a single game from Steam Store API."""
+    # Record the request time BEFORE making the request
+    _set_last_request_time(time.time())
+
+    try:
+        response = requests.get(
+            STEAM_STORE_API,
+            params={'appids': appid, 'l': 'english'},
+            timeout=10
+        )
+        response.raise_for_status()
+
+        result = response.json()
+        app_data = result.get(str(appid), {})
+
+        if app_data.get('success') and 'data' in app_data:
+            data = app_data['data']
+            # Extract the fields we care about
+            metadata = {
+                'short_description': data.get('short_description', ''),
+                'developers': data.get('developers', []),
+                'publishers': data.get('publishers', []),
+                'genres': [g['description'] for g in data.get('genres', [])],
+                'release_date': data.get('release_date', {}).get('date', ''),
+                'metacritic': data.get('metacritic', {}).get('score'),
+                'categories': [c['description'] for c in data.get('categories', [])],
+            }
+            return metadata
+    except Exception as e:
+        log("Failed to fetch metadata for {}: {}".format(appid, e))
+
+    return None
+
+
+def get_metadata(appid):
+    """
+    Get cached metadata for a game.
+    Returns dict with metadata or empty dict if not cached.
+    Does NOT fetch from API - that's handled by the background service.
+    """
+    cached = get_cached_metadata(appid)
+    return cached if cached is not None else {}
+
+
+def get_metadata_for_games(appids):
+    """
+    Get cached metadata for multiple games.
+    Returns dict mapping appid -> metadata (empty dict if not cached).
+    Does NOT fetch from API - that's handled by the background service.
+
+    :param appids: list of appids to fetch
+    :return: dict mapping appid -> metadata
+    """
+    init_cache()
+    results = {}
+    cached_count = 0
+
+    for appid in appids:
+        appid = str(appid)
+        cached = get_cached_metadata(appid)
+        if cached is not None:
+            results[appid] = cached
+            cached_count += 1
+        else:
+            results[appid] = {}
+
+    log("Metadata: {} cached, {} pending".format(cached_count, len(appids) - cached_count))
+    return results
+
+
+def get_uncached_appids(appids):
+    """
+    Get list of appids that don't have cached metadata.
+    Used by the background service to know what to fetch.
+
+    :param appids: list of appids to check
+    :return: list of appids needing metadata
+    """
+    init_cache()
+    uncached = []
+
+    for appid in appids:
+        appid = str(appid)
+        if get_cached_metadata(appid) is None:
+            uncached.append(appid)
+
+    return uncached
+
+
+def fetch_and_cache_metadata(appid):
+    """
+    Fetch metadata for a single game and cache it.
+    Called by the background service.
+    Returns True if successful, False otherwise.
+    """
+    if not can_make_request():
+        return False
+
+    metadata = fetch_metadata_from_api(appid)
+
+    if metadata:
+        cache_metadata(appid, metadata)
+        return True
+
+    # Cache empty result to avoid re-fetching failed games
+    cache_metadata(appid, {})
+    return True
+
+
+def delete_cache():
+    """Delete the metadata cache."""
+    try:
+        if os.path.exists(METADATA_CACHE_FILE):
+            os.remove(METADATA_CACHE_FILE)
+            log("Metadata cache deleted")
+    except Exception as e:
+        log("Failed to delete metadata cache: {}".format(e))
diff --git a/service.py b/service.py
