dashcam 1.4.13-beta.1 → 1.4.13-beta.3

package/PERFORMANCE_TRACKING.md

@@ -1,139 +0,0 @@
-# Performance Tracking
-
-The Dashcam CLI now includes comprehensive performance tracking during recordings. This feature monitors CPU and memory usage throughout the recording session and includes the data in the log files.
-
-## What's Tracked
-
-### 1. Dashcam Process Metrics
-- **CPU Usage**: Percentage of CPU used by the Dashcam process
-- **Memory Usage**: Memory consumed by the Dashcam process in bytes and MB
-- **Process Info**: PID, parent PID, CPU time, elapsed time
-
-### 2. System-Wide Metrics
-- **Total Memory**: System total and free memory
-- **Memory Usage Percentage**: Overall system memory utilization
-- **CPU Count**: Number of CPU cores available
-
-### 3. Top Processes
-- **Top 10 by CPU**: The most CPU-intensive processes running on the system
-- **Top 10 by Memory**: The most memory-intensive processes running on the system
-- **Process Details**: For each top process, tracks:
-  - Process name
-  - PID
-  - CPU usage percentage
-  - Memory usage in bytes
-  - Parent process ID
-  - CPU time and elapsed time
-
-## Sampling Frequency
-
-Performance metrics are sampled every **1 second** (1000ms) during the recording session.
-
-## Output Format
-
-Performance data is included in the recording result with the following structure:
-
-```javascript
-{
-  performance: {
-    samples: [
-      {
-        timestamp: 1700000000000,
-        elapsedMs: 1000,
-        system: {
-          totalMemory: 17179869184,
-          freeMemory: 8589934592,
-          usedMemory: 8589934592,
-          memoryUsagePercent: 50.0,
-          cpuCount: 8
-        },
-        process: {
-          cpu: 15.5,
-          memory: 134217728,
-          pid: 12345,
-          ppid: 1,
-          ctime: 5000,
-          elapsed: 10000
-        },
-        topProcesses: [
-          {
-            pid: 54321,
-            name: "ffmpeg",
-            cpu: 85.2,
-            memory: 268435456,
-            ppid: 12345,
-            ctime: 8500,
-            elapsed: 10000
-          },
-          // ... up to 10 processes
-        ],
-        totalProcesses: 342
-      }
-      // ... one sample per second
-    ],
-    summary: {
-      durationMs: 10000,
-      sampleCount: 10,
-      monitorInterval: 1000,
-      avgProcessCPU: 12.3,
-      maxProcessCPU: 18.7,
-      avgProcessMemoryBytes: 134217728,
-      avgProcessMemoryMB: 128.0,
-      maxProcessMemoryBytes: 201326592,
-      maxProcessMemoryMB: 192.0,
-      avgSystemMemoryUsagePercent: 52.5,
-      maxSystemMemoryUsagePercent: 55.3,
-      totalSystemMemoryBytes: 17179869184,
-      totalSystemMemoryGB: 16.0
-    }
-  }
-}
-```
-
-## Summary Statistics
-
-The performance tracker calculates summary statistics including:
-- **Average and Max Process CPU**: How much CPU the Dashcam process used
-- **Average and Max Process Memory**: Memory consumed by the Dashcam process
-- **Average and Max System Memory Usage**: Overall system memory pressure
-- **Total Duration**: How long the tracking ran
-- **Sample Count**: Number of samples collected
-
-## Logging
-
-Performance data is logged to the standard Dashcam log files:
-- `~/.dashcam/logs/combined.log` - All log levels including performance samples
-- `~/.dashcam/logs/debug.log` - Debug-level information
-- Console output when running with `--verbose` flag
-
-## Testing
-
-Run the performance tracking test:
-
-```bash
-node test-performance-tracking.js
-```
-
-This will:
-1. Start a 10-second recording
-2. Collect performance samples every second
-3. Display detailed performance statistics
-4. Show the top 10 processes at the end of the recording
-
-## Use Cases
-
-Performance tracking helps with:
-- **Debugging Performance Issues**: Identify when recordings are resource-intensive
-- **Optimization**: Track the impact of code changes on resource usage
-- **System Monitoring**: Understand what other processes are running during recordings
-- **Troubleshooting**: Correlate performance issues with specific applications or system states
-- **Capacity Planning**: Understand resource requirements for different recording scenarios
-
-## Implementation Details
-
-The performance tracker uses:
-- `pidusage` - For detailed per-process CPU and memory statistics
-- `ps-list` - For listing all system processes
-- `os` module - For system-wide memory and CPU information
-
-The tracker runs in parallel with the recording and has minimal overhead (~1% CPU on average).

package/SINGLE_FRAME_VIDEO_FIX.md

@@ -1,129 +0,0 @@
-# Single-Frame Video & Frame Drop Issues - Root Cause & Fix
-
-## Problem Description
-
-Videos produced by dashcam-cli had two related issues:
-1. **Single-frame appearance**: Videos appearing as single-frame, even though they contained multiple frames
-2. **Frame drops**: Videos showing significantly shorter duration than actual recording time (e.g., 12 seconds shown vs 68 seconds actual)
-
-## Root Causes
-
-### Issue 1: Incomplete WebM Container Metadata
-When ffmpeg's VP9 encoder is terminated before it can properly finalize the stream:
-
-1. **Missing duration metadata** - The WebM container doesn't have duration information
-2. **Premature file ending** - FFprobe reports "File ended prematurely"  
-3. **Playback issues** - Some players show only the first frame because they can't seek without duration metadata
-
-### Issue 2: Frame Dropping During Capture
-Frames were being dropped during the recording process due to:
-
-1. **Conflicting frame rate settings** - Platform config had hardcoded `-r 30` while fps parameter was set to 10
-2. **Insufficient buffer sizes** - Default thread queue size caused frame drops when encoder couldn't keep up
-3. **Premature stream termination** - The `-shortest` flag caused encoding to stop before all buffered frames were processed
-4. **Missing vsync enforcement** - Frames could be skipped instead of encoded
-
-### Example from Real Recording
-
-```bash
-# File: 691cb2b4c2fc02f59ae66e21.mp4
-Frame count: 512 frames
-Actual duration: 17.06 seconds (when decoded)
-Container duration: N/A (missing metadata)
-Warning: "File ended prematurely"
-```
-
-The video has 512 frames spanning 17 seconds, but players that rely on container metadata see it as a single frame.
-
-## Platform Specificity
-
-This issue can occur on all platforms but may be more prevalent on Linux due to:
-- Different screen capture performance characteristics
-- Variations in how X11grab delivers frames vs AVFoundation (macOS) or gdigrab (Windows)
-- System load affecting encoder buffer flush timing
-
-## Fix Applied
-
-### 1. Minimum Recording Duration (recorder.js)
-```javascript
-const MIN_RECORDING_DURATION = 2000; // 2 seconds minimum
-if (recordingDuration < MIN_RECORDING_DURATION) {
-  const waitTime = MIN_RECORDING_DURATION - recordingDuration;
-  await new Promise(resolve => setTimeout(resolve, waitTime));
-}
-```
-
-### 2. Improved FFmpeg Encoding Parameters
-
-**Removed conflicting settings:**
-```javascript
-// REMOVED from platform config:
-'-r', '30'  // This conflicted with fps parameter
-
-// REMOVED from output args:
-'-shortest'  // This caused premature termination
-```
-
-**Added buffer and sync enforcement:**
-```javascript
-// Input buffering (before -i):
-'-thread_queue_size', '512',    // Large input buffer prevents drops
-'-probesize', '50M',            // Better stream detection
-
-// Output sync enforcement:
-'-vsync', '1',                   // Constant frame rate - encode every frame
-'-max_muxing_queue_size', '9999' // Large muxing queue prevents drops
-
-// Existing improvements:
-'-quality', 'good',              // Changed from 'realtime' for better finalization
-'-cpu-used', '4',                // Balanced encoding speed
-'-deadline', 'good',             // Good quality mode
-'-g', fps.toString(),            // Keyframe every second (was 2 seconds)
-'-force_key_frames', `expr:gte(t,n_forced*1)`, // Force keyframes every 1s
-'-fflags', '+genpts',            // Generate presentation timestamps
-'-avoid_negative_ts', 'make_zero' // Prevent timestamp issues
-```
-
-### 3. Extended Graceful Shutdown Timing
-```javascript
-// Graceful quit: 5s -> 8s (VP9 needs time to finalize)
-// SIGTERM timeout: 10s -> 15s
-// Post-exit wait: 3s (for filesystem sync)
-
-currentRecording.stdin.write('q');
-currentRecording.stdin.end(); // Properly close stdin
-```
-
-## Testing
-
-Use the provided test script to verify recordings:
-
-```bash
-# Analyze existing video
-node test-short-recording.js analyze <video-file>
-
-# Run automated tests with various durations
-node test-short-recording.js
-```
-
-The test checks for:
-- ✅ Frame count > 1
-- ✅ No "File ended prematurely" warnings
-- ✅ Container metadata is complete (duration present)
-- ✅ All platforms (macOS/Linux/Windows)
-
-## Prevention
-
-The fix ensures proper container finalization by:
-1. Enforcing minimum recording time for multiple frames
-2. Using encoding parameters that prioritize stream finalization
-3. Allowing sufficient time for VP9 encoder to flush buffers
-4. Properly closing stdin before waiting for process exit
-5. Adding safety timeouts before force-killing the encoder
-
-## Impact
-
-- Short recordings (< 2s) now wait to ensure at least 2 seconds of footage
-- All recordings get properly finalized WebM container metadata
-- Videos play correctly in all players, including web browsers
-- No more "single frame" issues on any platform

package/examples/execute-script.js

@@ -1,150 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Example: Execute JavaScript on a webpage through the Chrome extension
- * 
- * This demonstrates how to:
- * 1. Connect to the Chrome extension via WebSocket
- * 2. Send JavaScript code to execute on the active tab
- * 3. Receive the execution results back
- */
-
-import { server } from '../lib/websocket/server.js';
-import { WebTrackerManager } from '../lib/extension-logs/manager.js';
-import { logger } from '../lib/logger.js';
-
-async function main() {
-  console.log('================================================================');
-  console.log('  Chrome Extension Script Execution Example');
-  console.log('================================================================\n');
-  console.log('Prerequisites:');
-  console.log('  1. Chrome extension must be installed and loaded');
-  console.log('  2. Have a regular webpage open (NOT chrome:// or chrome-extension://)');
-  console.log('  3. For best results, navigate to a simple page like example.com\n');
-  
-  console.log('Starting WebSocket server...');
-  
-  // Start the WebSocket server
-  await server.start();
-    console.log('WebSocket server started on port:', server.port);  // Create the WebTrackerManager
-  const manager = new WebTrackerManager(server);
-  
-  // Wait for the Chrome extension to connect
-  console.log('\nWaiting for Chrome extension to connect...');
-  const connected = await new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      console.log('Timeout waiting for connection');
-      resolve(false);
-    }, 10000);
-    
-    const cleanup = server.on('connection', (client) => {
-      console.log('Chrome extension connected!');
-      clearTimeout(timeout);
-      cleanup();
-      resolve(true);
-    });
-  });
-  
-  if (!connected) {
-    console.error('\nChrome extension did not connect.');
-    console.error('   Make sure the extension is installed and running.');
-    console.error('   Check chrome://extensions to verify it\'s loaded.');
-    process.exit(1);
-  }
-  
-  // Give it a moment to fully initialize
-  await new Promise(resolve => setTimeout(resolve, 500));
-  
-  console.log('\n--- Example 1: Get page title ---');
-  try {
-    const result = await manager.executeScript({
-      code: 'return document.title;'
-    });
-      console.log('Page title:', result);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-  
-  console.log('\n--- Example 2: Get current URL ---');
-  try {
-    const result = await manager.executeScript({
-      code: 'return window.location.href;'
-    });
-    console.log('Current URL:', result);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-  
-  console.log('\n--- Example 3: Change page background color ---');
-  try {
-    const result = await manager.executeScript({
-      code: `
-        document.body.style.backgroundColor = '#ffcccc';
-        return 'Background color changed!';
-      `
-    });
-    console.log('Result:', result);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-  
-  console.log('\n--- Example 4: Insert a message on the page ---');
-  try {
-    const result = await manager.executeScript({
-      code: `
-        const div = document.createElement('div');
-        div.style.cssText = 'position: fixed; top: 20px; right: 20px; background: #4CAF50; color: white; padding: 20px; border-radius: 8px; font-family: Arial; z-index: 10000; box-shadow: 0 4px 6px rgba(0,0,0,0.1);';
-        div.textContent = 'Hello from CLI!';
-        document.body.appendChild(div);
-        
-        // Remove after 5 seconds
-        setTimeout(() => div.remove(), 5000);
-        
-        return 'Message inserted successfully!';
-      `
-    });
-    console.log('Result:', result);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-  
-  console.log('\n--- Example 5: Get all links on the page ---');
-  try {
-    const result = await manager.executeScript({
-      code: `
-        const links = Array.from(document.querySelectorAll('a'))
-          .map(a => ({ text: a.textContent.trim().substring(0, 50), href: a.href }))
-          .slice(0, 5);
-        return links;
-      `
-    });
-    console.log('First 5 links:', JSON.stringify(result, null, 2));
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-  
-  console.log('\n--- Example 6: Execute with error handling ---');
-  try {
-    const result = await manager.executeScript({
-      code: `
-        // This will cause an error
-        nonExistentVariable.doSomething();
-        return 'This will not be returned';
-      `
-    });
-    console.log('Result:', result);
-  } catch (error) {
-    console.error('Expected error caught:', error.message);
-  }
-  
-  console.log('\n--- All examples completed! ---');
-  
-  // Clean up
-  await server.stop();
-  process.exit(0);
-}
-
-main().catch(error => {
-  console.error('Fatal error:', error);
-  process.exit(1);
-});

package/examples/simple-test.js

@@ -1,37 +0,0 @@
-#!/usr/bin/env node
-
-import { server } from '../lib/websocket/server.js';
-import { WebTrackerManager } from '../lib/extension-logs/manager.js';
-
-async function main() {
-  console.log('Simple test - make sure you have example.com or any webpage open\n');
-  
-  await server.start();
-  console.log('Server started on port:', server.port);
-  
-  const manager = new WebTrackerManager(server);
-  
-  console.log('Waiting for extension...');
-  await new Promise((resolve) => {
-    const cleanup = server.on('connection', () => {
-      console.log('Connected!\n');
-      cleanup();
-      resolve();
-    });
-  });
-  
-  await new Promise(resolve => setTimeout(resolve, 500));
-  
-  console.log('Test: Get page DOM');
-  const result = await manager.getPageDOM();
-  console.log('Title:', result.title);
-  console.log('URL:', result.url);
-  console.log('HTML length:', result.html.length, 'characters\n');
-  
-  console.log(result.html)
-
-  await server.stop();
-  process.exit(0);
-}
-
-main().catch(console.error);