dashcam 1.0.1-beta.2 → 1.0.1-beta.22

package/.github/workflows/publish.yml

@@ -1,43 +1,49 @@
-name: Publish to npm
+name: Publish Beta to npm
 
 on:
   push:
-    branches:
-      - main
+    branches: [ "main" ]
+  workflow_dispatch:
 
 jobs:
-  publish:
+  publish-beta:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write
+
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org/"
 
       - name: Configure Git
         run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install dependencies
+        run: npm install
 
-      - name: Bump version
+      - name: Commit dependency changes
         run: |
-          npm version prerelease --preid=beta -m "chore: bump version to %s [skip ci]"
+          git add package-lock.json
+          git diff --staged --quiet || git commit -m "chore: update package-lock.json"
 
-      - name: Push changes
+      - name: Bump version (prerelease beta)
         run: |
-          git push --follow-tags
+          npm version prerelease --preid=beta -m "chore: bump beta version to %s"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish to npm
-        run: npm publish --access public --tag beta
+      - name: Publish to npm under beta tag
+        run: npm publish --tag beta
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Push version bump commit + tag
+        run: |
+          git push --follow-tags

package/NPM_PUBLISH_FIX.md

@@ -0,0 +1,104 @@
+# NPM Publish & Version Sync Issues
+
+## Problem
+
+The npm publish workflow was failing with:
+```
+npm error 404 'dashcam@1.0.1-beta.17' is not in this registry.
+```
+
+## Root Cause
+
+**Version drift** between local git tags, package.json, and npm registry:
+
+- **NPM registry**: `1.0.1-beta.13` (latest successfully published)
+- **Local package.json**: `1.0.1-beta.16` (from failed publish attempts)
+- **Git tags**: Only up to `v1.0.1-beta.9`
+
+This happened because the workflow:
+1. Bumped version in package.json
+2. Created git tag
+3. Tried to publish
+4. **Publish failed** (possibly due to test failures or video encoding issues)
+5. Git changes were not reverted, leaving version incremented
+
+## Fixes Applied
+
+### 1. Updated Publish Workflow
+
+**Before**: Version bump → Push → Publish (wrong order!)
+
+**After**: 
+1. Sync with npm registry version
+2. Bump version
+3. **Publish first** ✅
+4. Push only if publish succeeded ✅
+
+```yaml
+- name: Bump version
+  run: |
+    # Get current version from npm
+    CURRENT_NPM_VERSION=$(npm view dashcam dist-tags.beta)
+    
+    # Sync before bumping
+    npm version $CURRENT_NPM_VERSION --no-git-tag-version --allow-same-version
+    
+    # Bump to next
+    npm version prerelease --preid=beta
+
+- name: Publish to npm
+  run: npm publish --access public --tag beta
+
+- name: Push changes  # Only runs if publish succeeded
+  run: git push --follow-tags
+```
+
+### 2. Created Version Sync Script
+
+`scripts/sync-version.sh` - Helps detect and fix version drift:
+
+```bash
+./scripts/sync-version.sh
+```
+
+This will:
+- Compare local version with npm registry
+- Offer to sync package.json
+- Show unpublished git tags that need cleanup
+
+### 3. Synced package.json
+
+Reset from `1.0.1-beta.16` → `1.0.1-beta.13` (current npm version)
+
+## Video Issue Connection
+
+The failed publishes were likely caused by **test failures due to the video encoding bugs** we fixed:
+
+- Frame rate conflicts
+- Buffer size issues
+- Frame dropping
+- Incomplete container metadata
+
+All of these are now fixed in the recorder.js, so future CI runs should succeed.
+
+## Next Steps
+
+1. ✅ Package.json is synced
+2. ✅ Workflow is fixed
+3. ⚠️  Need to clean up unpublished git tags manually (optional):
+
+```bash
+# List tags
+git tag | grep beta
+
+# Delete local tags for unpublished versions (14-16)
+git tag -d v1.0.1-beta.14 v1.0.1-beta.15 v1.0.1-beta.16
+
+# If they exist on remote, delete them
+git push origin :refs/tags/v1.0.1-beta.14
+git push origin :refs/tags/v1.0.1-beta.15
+git push origin :refs/tags/v1.0.1-beta.16
+```
+
+4. Push the fixes to trigger a new publish
+5. Next version will be `1.0.1-beta.14` ✅

package/SINGLE_FRAME_VIDEO_FIX.md

@@ -0,0 +1,129 @@
+# 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/bin/dashcam-background.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Background recording process for dashcam CLI
+ * This script runs detached from the parent process to handle long-running recordings
+ */
+
+import { startRecording, stopRecording } from '../lib/recorder.js';
+import { upload } from '../lib/uploader.js';
+import { logger, setVerbose } from '../lib/logger.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Get process directory for status files
+const PROCESS_DIR = path.join(os.homedir(), '.dashcam-cli');
+const STATUS_FILE = path.join(PROCESS_DIR, 'status.json');
+const RESULT_FILE = path.join(PROCESS_DIR, 'upload-result.json');
+
+// Parse options from command line argument
+const optionsJson = process.argv[2];
+if (!optionsJson) {
+  console.error('No options provided to background process');
+  process.exit(1);
+}
+
+const options = JSON.parse(optionsJson);
+
+// Enable verbose logging in background
+setVerbose(true);
+
+logger.info('Background recording process started', { 
+  pid: process.pid,
+  options 
+});
+
+// Write status file
+function writeStatus(status) {
+  try {
+    fs.writeFileSync(STATUS_FILE, JSON.stringify({
+      ...status,
+      timestamp: Date.now(),
+      pid: process.pid
+    }, null, 2));
+  } catch (error) {
+    logger.error('Failed to write status file', { error });
+  }
+}
+
+// Write upload result file
+function writeUploadResult(result) {
+  try {
+    logger.info('Writing upload result to file', { path: RESULT_FILE, shareLink: result.shareLink });
+    fs.writeFileSync(RESULT_FILE, JSON.stringify({
+      ...result,
+      timestamp: Date.now()
+    }, null, 2));
+    logger.info('Successfully wrote upload result to file');
+  } catch (error) {
+    logger.error('Failed to write upload result file', { error });
+  }
+}
+
+// Main recording function
+async function runBackgroundRecording() {
+  let recordingResult = null;
+  let isShuttingDown = false;
+
+  try {
+    // Start the recording
+    const recordingOptions = {
+      fps: parseInt(options.fps) || 10,
+      includeAudio: options.audio || false,
+      customOutputPath: options.output || null
+    };
+
+    logger.info('Starting recording with options', { recordingOptions });
+
+    recordingResult = await startRecording(recordingOptions);
+
+    // Write status to track the recording
+    writeStatus({
+      isRecording: true,
+      startTime: recordingResult.startTime,
+      options,
+      pid: process.pid,
+      outputPath: recordingResult.outputPath
+    });
+
+    logger.info('Recording started successfully', { 
+      outputPath: recordingResult.outputPath,
+      startTime: recordingResult.startTime 
+    });
+
+    // Set up signal handlers for graceful shutdown
+    const handleShutdown = async (signal) => {
+      if (isShuttingDown) {
+        logger.info('Shutdown already in progress...');
+        return;
+      }
+      isShuttingDown = true;
+      
+      logger.info(`Received ${signal}, stopping background recording...`);
+      
+      try {
+        // Stop the recording
+        const stopResult = await stopRecording();
+        
+        if (stopResult) {
+          logger.info('Recording stopped successfully', { 
+            outputPath: stopResult.outputPath,
+            duration: stopResult.duration 
+          });
+          
+          // Upload the recording
+          logger.info('Starting upload...');
+          const uploadResult = await upload(stopResult.outputPath, {
+            title: options.title || 'Dashcam Recording',
+            description: options.description || 'Recorded with Dashcam CLI',
+            project: options.project || options.k,
+            duration: stopResult.duration,
+            clientStartDate: stopResult.clientStartDate,
+            apps: stopResult.apps,
+            logs: stopResult.logs,
+            gifPath: stopResult.gifPath,
+            snapshotPath: stopResult.snapshotPath
+          });
+          
+          logger.info('Upload complete', { shareLink: uploadResult.shareLink });
+          
+          // Write upload result for stop command to read
+          writeUploadResult({
+            shareLink: uploadResult.shareLink,
+            replayId: uploadResult.replay?.id
+          });
+        }
+        
+        // Update status to indicate recording stopped
+        writeStatus({
+          isRecording: false,
+          completedTime: Date.now(),
+          pid: process.pid
+        });
+        
+        logger.info('Background process exiting successfully');
+        process.exit(0);
+      } catch (error) {
+        logger.error('Error during shutdown:', error);
+        process.exit(1);
+      }
+    };
+    
+    process.on('SIGINT', () => handleShutdown('SIGINT'));
+    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+    
+    // Keep the process alive
+    logger.info('Background recording is now running. Waiting for stop signal...');
+    await new Promise(() => {}); // Wait indefinitely for signals
+    
+  } catch (error) {
+    logger.error('Background recording failed:', error);
+    
+    // Update status to indicate failure
+    writeStatus({
+      isRecording: false,
+      error: error.message,
+      pid: process.pid
+    });
+    
+    process.exit(1);
+  }
+}
+
+// Run the background recording
+runBackgroundRecording().catch(error => {
+  logger.error('Fatal error in background process:', error);
+  process.exit(1);
+});