History marker reminder for coming back and having the track to about 10 seconds from last play

Author: MrDesjardins

.claude/rules/python-code.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "*.py"
+  - "services/**/*.py"
+  - "routes/**/*.py"
+  - "tests/**/test_*.py"
+---
+
+- Python code must have all their imports at the top of the files and never inside a function<
+- Python code must respect the ruff format
+- Python code must be typed and respect mypy
+- Python code must be unit tested with proper mock

.claude/rules/readme-update.md

@@ -0,0 +1,2 @@
+- Make sure that when you add new features that "Features" section in the readme.md is updated
+- Make sure when architecture change that the "Architecture" section of the readme.md is updated

README.md

@@ -9,55 +9,54 @@ A powerful FastAPI application that streams audio from YouTube videos as MP3 ove
 ## Features
 
 ### Core Streaming
-- **YouTube Audio Streaming**: Stream any YouTube video as MP3 audio in real-time
-- **Multi-Client Support**: Multiple users can listen to the same stream simultaneously with individual replay buffers
-- **Smart Queue System**: Build playlists with persistent queue that survives page refreshes
-- **Auto-Play**: Automatically plays next track when current track completes
-- **Prefetching**: Pre-downloads next queue item before current track ends for seamless transitions
-- **Play History**: Track all played videos with play counts, timestamps, and rich metadata
-- **Mobile-First Web UI**: Responsive interface optimized for phones, tablets, and desktops
-- **MediaSession API**: Rich media controls in car entertainment systems, lock screens, and notification panels
+- **YouTube Audio Streaming**: Stream any YouTube video as MP3 audio; supports full YouTube URLs, short `youtu.be` links, and raw video IDs
+- **Smart Queue System**: Build playlists with a persistent queue (survives page refreshes) that supports both YouTube videos and weekly summary audio as mixed items
+- **Auto-Play & Prefetching**: Automatically plays the next track when the current one finishes; pre-downloads the upcoming track in the background for seamless transitions
+- **Play History**: Tracks all played videos with play counts, relative timestamps, and rich metadata (title, channel, thumbnail); click any entry to replay
+- **Stream Resilience**: Automatic stalling detection with up to 50 reconnection retries and adaptive back-off delay
+
+### Playback Controls
+- **Audio Player**: HTML5 player with Play/Pause, Rewind (−15 s), Fast-Forward (+15 s), and Stop
+- **Speed Controls**: Switch between 1×, 1.15×, 1.3×, and 1.5× playback speed
+- **Keyboard Shortcuts**: Space to play/pause; ↑/↓ to skip forward/back 15 s
+- **MediaSession API**: Rich media controls in car entertainment systems (Tesla tested), lock screens, and notification panels — displays title, channel, and album art
+
+### Web Interface
+- **Mobile-First Design**: Responsive layout optimised for phones, tablets, and desktops
+- **Dark / Light Theme**: Automatic system-preference detection with manual toggle; preference saved in local storage
+- **Drag-and-Drop Queue Reordering**: Reorder queue items by dragging (mouse and touch); order saved instantly to the database
 
 ### AI-Powered Features
 
-#### Automatic Transcription
-- **Multi-Provider Support**: Choose between OpenAI Whisper, Mistral Voxtral, or Google Gemini for transcription
-- **Audio Optimization**: Automatic compression and speed-up to reduce API costs by ~33%
-- **Background Processing**: Transcription happens asynchronously without blocking playback
-- **Smart Caching**: Transcripts cached locally to avoid re-processing
+#### Automatic Transcription (`TRANSCRIPTION_ENABLED=true`)
+- **Multi-Provider**: OpenAI Whisper, Mistral Voxtral, or Google Gemini — switch via config
+- **Audio Optimisation**: Automatic compression (1.5× speed, mono, 32 kbps, 16 kHz) reduces Whisper API costs ~33 %
+- **Background Processing**: Runs asynchronously; transcription status visible in UI with polling every 5 s
+- **Smart Caching**: Transcripts cached locally; Trilium deduplication prevents re-processing the same video
 
-#### Intelligent Summarization
-- **Video Summaries**: AI-generated summaries of each video's content
+#### Intelligent Summarisation
+- **Video Summaries**: AI-generated summaries posted to Trilium Notes with video title, channel, thumbnail, and YouTube link
 - **Multi-Provider**: OpenAI GPT or Google Gemini (Gemini recommended for free tier)
-- **Knowledge Management**: Automatic posting to Trilium Notes with deduplication
-- **Rich Metadata**: Includes video title, channel, thumbnail, and YouTube link
-
-#### Weekly Summaries
-- **Automated Scheduling**: Runs every Sunday at 11 PM Pacific to summarize the week (Monday-Sunday)
-- **Comprehensive Analysis**: Synthesizes all videos watched during the week
-- **Key Learnings**: Extracts 15 most important insights across all content
-- **Theme Detection**: Identifies common themes and patterns in your viewing
-- **Text-to-Speech**: Optional TTS generation (OpenAI or ElevenLabs) for listening to summaries
-
-#### Smart Video Suggestions
-- **AI Content Discovery**: Analyzes your viewing history to suggest similar videos
-- **Theme-Based**: Identifies patterns in what you watch to find relevant content
-- **YouTube Integration**: Direct search with working YouTube links
-- **Configurable**: Control how many videos to analyze and suggestions to generate
+
+#### Weekly Summaries (`WEEKLY_SUMMARY_ENABLED=true`)
+- **Automated Scheduling**: Configurable schedule (default: Fridays at 11 PM) to summarise the week's viewing
+- **Comprehensive Analysis**: Synthesises all videos watched during the week; extracts key learnings and common themes
+- **Text-to-Speech**: Optional TTS (OpenAI or ElevenLabs) converts the written summary to audio you can queue and play
+
+#### Smart Video Suggestions (`BOOK_SUGGESTIONS_ENABLED=true`)
+- **AI Content Discovery**: Analyses viewing history and Trilium summaries to find thematically related YouTube videos
+- **Configurable**: Control how many recent videos to analyse and how many suggestions to generate
 
 ### Data & Analytics
-- **LLM Usage Tracking**: Detailed logging of all API calls with token counts
-- **Cost Monitoring**: Track spending across providers, models, and features
-- **Performance Metrics**: Audio duration, file sizes, processing times
-- **Flexible Filtering**: Query by date range, provider, model, or feature
+- **LLM Usage Dashboard**: HTML dashboard at `/admin/stats` plus JSON API with filtering by date range, provider, model, and feature
+- **Cost Monitoring**: Token counts and audio-duration tracking for accurate per-minute pricing (Whisper, Voxtral)
+- **Client-Side Logging**: Browser logs batched and forwarded to the server — essential for debugging on car displays and mobile devices without a console
 
 ### Developer Experience
-- **Modern Stack**: FastAPI, Python 3.12, SQLite with type-safe models
-- **Comprehensive Testing**: 76%+ test coverage with pytest
-- **CI/CD**: Automated testing and linting with GitHub Actions
-- **Pre-commit Hooks**: Automatic code formatting with Ruff and type checking with mypy
-- **Type Safety**: Full type annotations with mypy strict mode
-- **Docker Ready**: Easy deployment with systemd service support
+- **Modern Stack**: FastAPI, Python 3.12, SQLite with type-safe models and dataclasses
+- **Comprehensive Testing**: 76 %+ test coverage with pytest and pre-commit hooks
+- **CI/CD**: Automated testing with GitHub Actions on every push and pull request
+- **Type Safety**: Full return-type annotations; mypy-compatible throughout
 
 ## Quick Start
 

routes/stream.py

@@ -4,12 +4,20 @@
 
 import logging
 import threading
+from typing import Optional
 from fastapi import APIRouter, HTTPException
 from fastapi.responses import FileResponse, JSONResponse, Response
 from pydantic import BaseModel
 from config import get_config
 from services.background_tasks import get_transcription_queue, TranscriptionJob
-from services.database import add_to_history, get_history, clear_history
+from services.database import (
+    add_to_history,
+    get_history,
+    clear_history,
+    save_playback_position,
+    get_playback_position,
+    clear_playback_position,
+)
 from services.path_utils import expand_path
 from services.streaming import (
     get_audio_duration,
@@ -269,3 +277,31 @@ def clear_play_history() -> JSONResponse:
     except Exception as e:
         logger.error(f"Error clearing history: {e}")
         raise HTTPException(status_code=500, detail=str(e))
+
+
+class SavePositionRequest(BaseModel):
+    position_seconds: float
+    duration_seconds: Optional[float] = None
+
+
+@router.get("/playback-position/{video_id}")
+def get_position(video_id: str) -> JSONResponse:
+    """Get the saved playback position for a video."""
+    pos = get_playback_position(video_id)
+    if pos is None:
+        return JSONResponse({"position_seconds": 0, "duration_seconds": None})
+    return JSONResponse(pos.to_dict())
+
+
+@router.post("/playback-position/{video_id}")
+def save_position(video_id: str, request: SavePositionRequest) -> JSONResponse:
+    """Save or update the playback position for a video."""
+    save_playback_position(video_id, request.position_seconds, request.duration_seconds)
+    return JSONResponse({"status": "saved"})
+
+
+@router.delete("/playback-position/{video_id}")
+def delete_position(video_id: str) -> JSONResponse:
+    """Delete the saved playback position for a video."""
+    clear_playback_position(video_id)
+    return JSONResponse({"status": "cleared"})

services/database.py

@@ -7,7 +7,7 @@
 from queue import Queue, Empty
 import os
 
-from services.models import PlayHistoryItem, QueueItem, WeeklySummary
+from services.models import PlayHistoryItem, PlaybackPosition, QueueItem, WeeklySummary
 
 logger = logging.getLogger(__name__)
 
@@ -193,6 +193,22 @@ def init_database():
             ON llm_usage_stats(feature)
         """)
 
+        # Playback positions table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS playback_positions (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                youtube_id TEXT NOT NULL UNIQUE,
+                position_seconds REAL NOT NULL,
+                duration_seconds REAL,
+                last_updated_at TEXT NOT NULL
+            )
+        """)
+
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_playback_positions_youtube_id
+            ON playback_positions (youtube_id)
+        """)
+
         logger.info(f"Database initialized at {DB_PATH}")
 
 
@@ -881,3 +897,50 @@ def get_llm_usage_summary(
             results["totals"]["total_tokens"] += stat["total_tokens"]
 
         return results
+
+
+# Playback position functions
+
+
+def save_playback_position(
+    youtube_id: str,
+    position_seconds: float,
+    duration_seconds: Optional[float] = None,
+) -> None:
+    """Save or update the playback position for a video."""
+    timestamp = datetime.now(timezone.utc).isoformat()
+    with get_db_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute(
+            """
+            INSERT INTO playback_positions (youtube_id, position_seconds, duration_seconds, last_updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(youtube_id) DO UPDATE SET
+                position_seconds = excluded.position_seconds,
+                duration_seconds = excluded.duration_seconds,
+                last_updated_at  = excluded.last_updated_at
+        """,
+            (youtube_id, position_seconds, duration_seconds, timestamp),
+        )
+
+
+def get_playback_position(youtube_id: str) -> Optional[PlaybackPosition]:
+    """Get the saved playback position for a video, or None if not found."""
+    with get_db_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT * FROM playback_positions WHERE youtube_id = ?", (youtube_id,)
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return PlaybackPosition.from_db_row(row)
+
+
+def clear_playback_position(youtube_id: str) -> None:
+    """Delete the saved playback position for a video."""
+    with get_db_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute(
+            "DELETE FROM playback_positions WHERE youtube_id = ?", (youtube_id,)
+        )

services/models.py

@@ -1,7 +1,7 @@
 """Data models for database entities and API responses."""
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Any, Optional
 
 
 @dataclass
@@ -161,6 +161,35 @@ def to_dict(self) -> dict:
         return result
 
 
+@dataclass
+class PlaybackPosition:
+    """Represents a saved playback position for a video."""
+
+    youtube_id: str
+    position_seconds: float
+    duration_seconds: Optional[float]
+    last_updated_at: str
+
+    @classmethod
+    def from_db_row(cls, row: Any) -> "PlaybackPosition":
+        """Create instance from database row."""
+        return cls(
+            youtube_id=row["youtube_id"],
+            position_seconds=row["position_seconds"],
+            duration_seconds=row["duration_seconds"],
+            last_updated_at=row["last_updated_at"],
+        )
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "youtube_id": self.youtube_id,
+            "position_seconds": self.position_seconds,
+            "duration_seconds": self.duration_seconds,
+            "last_updated_at": self.last_updated_at,
+        }
+
+
 @dataclass
 class BookInfo:
     """Represents book information for weekly summaries."""

services/weekly_summary.py

@@ -544,25 +544,23 @@ def _check_audio_already_attached(note_id: str, filename: str) -> bool:
     """
     Check if audio file is already attached to a Trilium note.
 
+    Uses the local database as the source of truth: audio_file_path is only
+    set in weekly_summaries after a successful attach_audio_to_note call,
+    so its presence means the audio is already attached.
+
     Args:
-        note_id: The Trilium note ID
+        note_id: The Trilium note ID (unused, kept for signature compatibility)
         filename: Expected filename (e.g., "2024-W01.mp3")
 
     Returns:
         True if audio is already attached, False otherwise
     """
     try:
-        client = get_httpx_client()
-        children_url = _build_url(config.trilium_url, f"etapi/notes/{note_id}/children")
-        response = client.get(
-            children_url, headers=_get_trilium_headers(), timeout=10.0
-        )
-        response.raise_for_status()
-
-        children = response.json()
-        return any(child.get("title") == filename for child in children)
+        week_year = filename[:-4] if filename.endswith(".mp3") else filename
+        summary = get_summary_by_week_year(week_year)
+        return summary is not None and summary.audio_file_path is not None
     except Exception as e:
-        logger.warning(f"Could not check Trilium children: {e}")
+        logger.warning(f"Could not check audio attachment status: {e}")
         return False