🎥 Video Speed HUD & Question Time Watcher

An ultra-lightweight, feature-packed browser extension for precision video playback control, real-time HUD overlays, intelligent silence skipping, and exam pace stopwatch tracking.

---

⚡ Overview

Video Speed HUD & Question Time Watcher is an open-source productivity extension engineered for online students, competitive exam aspirants, and power video consumers. Built on Manifest V3, it seamlessly injects into web video players (including PhysicsWallah, YouTube, Coursera, standard HTML5, and VideoJS players) to provide frictionless speed micro-adjustments, automatic dead-air skipping via the Web Audio API, and an interactive glassmorphic question timer.

---

✨ Key Features

⚡ Playback & Environmental Controls

• Precision Speed Micro-Adjustments: Fine-tune video playback speed from 0.25x up to 4.0x using Alt + Scroll or Alt + ← / → in fine 0.05x increments.
• Speed Ramping (Progression Mode): Toggle with Ctrl + / to gradually accelerate video speed by +0.1x in scaling intervals (waitTime = currentStep * 20 seconds) up to 2.5x maximum.
• Instant Hold Fast-Forward: Hold Spacebar (for > 250ms) to temporarily accelerate playback to 2.0x. Releasing restores your exact speed; quick tap toggles standard Play/Pause.
• 2x Speed Toggle: Press S to instantly jump to 2.0x playback speed. Press S again to restore your exact previous speed — a quick one-key toggle for rapid fast-forwarding.
• Remaining Time Badge: Toggle with R to display real remaining video time alongside speed-adjusted time (e.g. -10:00 | 05:00 at 2.0x).
• Screen Brightness Overlay: Adjust video brightness from 0.3x to 2.5x using Alt + ↑ / ↓.

⏱️ Question Time Watcher (Stopwatch HUD)

• Glassmorphic Floating Widget: A translucent, liquid-glass widget docked on the video container so behind-player content remains readable.
• Exam Pace Benchmark ("Beat the Clock"): Cycle target pacing benchmarks (1m / 2m / 3m / 5m) with Alt + B:
  • 🟢 Green Glass Glow: Time spent $\le$ 70% of benchmark.
  • 🟡 Yellow Glass Glow: Time spent between 70% and 100%.
  • 🔴 Red Glass Glow (Overtime): Time spent exceeds benchmark limit.
• Smart Auto-Timer: Automatically starts timing when you pause a video to solve a problem and logs laps when playback resumes.
• Click-Through Mode: Toggle with Alt + C or click 🎯 to pass clicks directly through the widget onto underlying video player controls.
• Per-URL Persistence: Stopwatch status, logs, widget positions, and minimized states are stored in chrome.storage.local indexed by URL.

⏩ Web Audio Silence Skipper

• Real-time Dead-Air Suppression: Uses Web Audio API (AnalyserNode) to monitor real-time RMS volume.
• Temporal Acceleration: If audio falls below the 0.02 threshold for > 600ms, playback accelerates to 2.0x and ramps by +0.1x per second up to 4.0x max.
• Instant Speech Detection & Restore: Restores previous speed instantly when voice or sound is detected.
• Temporary Suspension: Hold Shift to pause silence skipping while writing notes.

📚 Productivity, Analytics & Integrations

• Automation Macros & 10s Fast-Trigger: Record repetitive click sequences and navigation directly from the popup dashboard. Whenever you open that website, a sleek 10-second liquid glass prompt appears with 1-click buttons to instantly replay the recorded macro!
• Lecture Slides & Timeline Drawer: When watching lectures on pw.live/watch/?..., automatically extracts lecture IDs (parentId, batchSubjectId, scheduleId) to load slides from the proxy API. Displays an interactive liquid glass drawer with high-res thumbnails and timestamps. Opening the drawer automatically center-scrolls to the slide nearest to the current playback time. Click any slide to immediately seek playback to that topic, or press D to toggle!
• Focus Mode: Press Alt + F to mute floating HUD toasts while keeping the stopwatch active.
• Auto-Hide Idle Cursor: Automatically hides the mouse cursor if left motionless for 10 seconds to eliminate screen distractions during playback; instantly restores cursor on any mouse movement or click.
• Study Hour Tracker & Streaks: Automatically logs active video consumption, real clock time vs. speed-adjusted content coverage, daily goals (4h, 6h, 8h, 10h), and streaks (🔥).
• YouTube Shorts & Playables Remover: Toggle on/off from the popup dashboard to hide distracting Shorts shelves, sidebar buttons, search filters, and YouTube Playables in real-time without refreshing.
• Popup Dashboard: Tap Alt + Shift + D to manage toggles, view daily statistics, copy question logs, and export sessions to .csv.

---

🏗️ Architecture

flowchart TD
    subgraph Browser ["Web Page & Video Players"]
        DOM[HTML5 / VideoJS Player]
        AudioStream[Web Audio API Node]
    end

    subgraph CoreEngine ["Extension Core Modules"]
        HUD[HUD Notification System]
        SpeedCtrl[Speed & Brightness Controller]
        SilenceSkip[Silence Skipper Analyser]
        QTimer[Question Time Watcher]
        Tracker[Study Tracker & Streaks]
        PWEnhance[PW Slides & Enhancements Plugin]
    end

    subgraph UI ["User Interfaces"]
        Widget[Glassmorphic HUD Overlay]
        Popup[Popup Dashboard & Analytics]
    end

    subgraph Storage ["chrome.storage.local"]
        URLState[(Per-URL Stopwatch Logs)]
        StudyStats[(Daily Study Records)]
        Config[(User Preferences)]
    end

    DOM --> SpeedCtrl
    DOM --> QTimer
    AudioStream --> SilenceSkip
    SilenceSkip --> SpeedCtrl
    SpeedCtrl --> HUD
    QTimer --> Widget
    QTimer --> URLState
    Tracker --> StudyStats
    Popup --> Config
    Popup --> StudyStats
    Popup --> URLState

Loading

---

🎮 Complete Keyboard Shortcut Reference

🎥 Playback & HUD Controls

Shortcut	Action	Description
Alt + Scroll	Adjust Speed	Increments by 0.05x (Range: 0.25x - 4.0x)
Alt + →	Increase Speed	Smooth +0.05x increment with key-repeat
Alt + ←	Decrease Speed	Smooth -0.05x decrement with key-repeat
Alt + ↑	Increase Brightness	Increases brightness overlay by +0.1x
Alt + ↓	Decrease Brightness	Decreases brightness overlay by -0.1x
Hold Spacebar	2.0x Fast-Forward	Accelerates after 250ms; restores on release
Hold Shift	1.5x Fast-Forward	Accelerates after 250ms; restores on release (also suspends silence skipper)
Tap Spacebar	Play / Pause	Standard player control
S	Toggle 2x Speed	Instantly jumps to 2.0x; press again to restore previous speed
Ctrl + /	Toggle Speed Ramp	Incrementally steps up speed over time
R	Toggle Time Badge	Displays remaining real & speed-adjusted time
Alt + S	Toggle Silence Skipper	Enables / disables Web Audio volume monitoring
Hold Shift	Suspend Silence Skip	Pauses silence skipper while holding key
Alt + F	Toggle Focus Mode	Mutes HUD toasts (Stopwatch stays visible)
Alt + Shift + D	Open Popup Dashboard	Opens extension popup window

⏱️ Question Stopwatch Widget Controls

Shortcut	Action	Description
T	Play / Pause Stopwatch	Starts / stops the floating stopwatch
Shift + T	Next Question / Lap	Logs question time and resets stopwatch to 00:00
Alt + T	Open Question Log	Opens summary modal with question timestamps
Alt + B	Cycle Benchmark	Cycles OFF ➔ 1m ➔ 2m ➔ 3m ➔ 5m
Alt + C	Toggle Click-Through	Allows clicking through widget to video controls
Shift + H	Hide / Show Widget	Toggles floating widget visibility on screen
Alt + Shift + T	Hard Reset Stopwatch	Purges logs and resets counter for current URL

🎯 PhysicsWallah Platform Shortcuts (*.pw.live)

Shortcut	Action	Description
D	Toggle Slides Drawer	Opens/closes lecture slides timeline & jumping drawer
Esc	Close Slides / Lightbox	Closes the slide drawer or full-screen image zoom
</kbd>	Trigger Poll	Automatically triggers active poll button on page
'	Trigger Chat	Clicks live chat toggle button on page
/	Trigger Poll Icon	Focuses #poll-icon element

---

🚀 Installation & Setup Guide

Compatible with Google Chrome, Microsoft Edge, Brave, Opera, Arc, and Vivaldi.

---

🪟 Windows (PowerShell)

1. Open PowerShell (Win + X ➔ Terminal).
2. Clone the repository:

   cd $HOME\Documents
   git clone https://github.com/Fire162/PW-extension.git
   cd PW-extension

3. Open the Extensions management page:

   Start-Process "chrome://extensions"

4. Toggle Developer mode to ON in the top-right corner.
5. Click Load unpacked (top-left) and select the PW-extension directory.
6. Pin the extension icon to your toolbar.

---

🐧 Linux / macOS (Terminal)

1. Open your terminal (Ctrl + Alt + T).
2. Clone the repository:

   git clone https://github.com/Fire162/PW-extension.git
   cd PW-extension

3. Open your browser's extension dashboard:

   # Chrome
   google-chrome "chrome://extensions" &
   
   # Brave
   brave-browser "brave://extensions" &

4. Toggle Developer mode to ON.
5. Click Load unpacked and select the PW-extension directory.
6. Pin the extension to your toolbar.

---

🔄 Updating the Extension

⚡ 1-Click Update Scripts

• Windows: Double-click update.bat in the project root.
• Linux / macOS: Run ./update.sh in terminal.
• Then navigate to chrome://extensions and click the 🔄 Reload button on the extension card.

💻 Manual Git Pull

git pull origin main

Reload the extension in chrome://extensions afterwards.

---

💾 Storage Schema

All states are persisted via chrome.storage.local:

interface StorageSchema {
  // Mapped per video URL
  [qt_log_key: `qt_log_${string}`]: {
    activeQuestionIndex: number;
    currentLapStart: number;
    laps: Array<{ question: number; timeSec: number; timestamp: string }>;
    widgetPos: { top: string; left: string };
    isMinimized: boolean;
  };

  // Aggregated study analytics
  studyTrackerData: {
    dailySeconds: { [dateString: string]: number };
    dailySpeedAdjustedSeconds: { [dateString: string]: number };
    currentStreak: number;
    lastActiveDate: string;
    targetGoalHours: number;
  };

  // User preferences
  autoTimerOnPause: boolean;
  autoSkipSilence: boolean;
  focusMode: boolean;
  quickNotesEnabled: boolean;
  targetBenchmarkSec: number;
  totalSilenceTimeSavedSec: number;
}

---

📂 Project Structure

PW-extension/
├── manifest.json            # Manifest V3 permissions & content script definitions
├── rules.json               # DeclarativeNetRequest routing rules
├── update.bat               # Windows 1-click update script
├── update.sh                # Linux/macOS 1-click update script
├── icons/                   # Extension icon assets (16px, 48px, 128px)
├── src/
│   ├── popup/
│   │   ├── popup.html       # Translucent dashboard layout
│   │   ├── popup.css        # Dashboard styling sheet
│   │   └── popup.js         # Preferences manager, analytics aggregator & CSV exporter
│   ├── styles/
│   │   ├── hud.css          # Glassmorphic overlay styling & CSS animations
│   │   └── pw-custom.css    # Scoped styles for PhysicsWallah layout enhancements
│   ├── core/
│   │   ├── hud.js           # Toast notification system
│   │   ├── speed-controller.js # Video playback rate, brightness & speed ramp logic
│   │   ├── remaining-time.js   # Real & speed-adjusted remaining time calculations
│   │   ├── question-timer.js   # Drag-and-drop stopwatch widget & lap logger
│   │   ├── silence-skipper.js  # Audio AnalyserNode volume detection & dead-air acceleration
│   │   ├── study-tracker.js    # Activity-based study hour & streak logging
│   │   └── macro-runner.js     # Macro recorder & 10s auto fast-trigger prompt
│   └── plugins/
│       └── pw-enhancements.js  # Dedicated lecture slides drawer & platform tools for *.pw.live
├── AGENT.md                 # AI coding agent configuration & guidelines
├── CONTRIBUTING.md          # Open-source contribution guidelines
└── LICENSE                  # MIT License

---

🤝 Contributing

Contributions, issues, and feature suggestions are always welcome! Check out CONTRIBUTING.md to get started.

---

📜 License

Distributed under the MIT License.