Merge pull request #3665 from Mentra-Community/aisraelov/video-thumbnails

Add thumb.jpg sidecar for finished video captures

Author: aisraelov

asg_client/app/src/main/java/com/mentra/asg_client/AsgConstants.java

@@ -364,6 +364,33 @@ public class AsgConstants {
      */
     public static final int FILE_TRANSFER_PROGRESS_LOG_INTERVAL = 10;
 
+    // Video capture thumbnails
+    // -------------------------------------------------------------------------
+
+    /** JPEG sidecar written next to a finalized video for direct-filesystem consumers. */
+    public static final String VIDEO_THUMBNAIL_SIDECAR_NAME = "thumb.jpg";
+
+    /** Transient thumbnail filename; the .partial suffix keeps it out of gallery listings. */
+    public static final String VIDEO_THUMBNAIL_PARTIAL_NAME = "thumb.jpg.partial";
+
+    /** Longest edge of generated video thumbnails, in pixels. */
+    public static final int VIDEO_THUMBNAIL_MAX_DIMENSION = 480;
+
+    /** JPEG compression quality for video thumbnail sidecars. */
+    public static final int VIDEO_THUMBNAIL_JPEG_QUALITY = 80;
+
+    /** Frame position sampled for video thumbnails, in microseconds. */
+    public static final long VIDEO_THUMBNAIL_FRAME_TIME_US = 1_000_000L;
+
+    /** Maximum time allowed for platform video-frame extraction. */
+    public static final long VIDEO_THUMBNAIL_EXTRACTION_TIMEOUT_MS = 10_000L;
+
+    /** Final main-thread wait after thumbnail work has drained during other cleanup steps. */
+    public static final long VIDEO_THUMBNAIL_SHUTDOWN_TIMEOUT_MS = 250L;
+
+    /** Maximum abandoned native decoder workers retained after timeout. */
+    public static final int VIDEO_THUMBNAIL_MAX_RETIRED_DECODERS = 2;
+
     /**
      * Max wait for the deferred background photo write ({@code CapturedPhoto.persistence}) when a
      * BLE photo consumer needs the file on disk (gallery save, text-mode canonical crop, cleanup).

asg_client/app/src/main/java/com/mentra/asg_client/io/file/core/FileManagerImpl.java

@@ -1,5 +1,6 @@
 package com.mentra.asg_client.io.file.core;
 
+import com.mentra.asg_client.AsgConstants;
 import com.mentra.asg_client.logging.Logger;
 import com.mentra.asg_client.io.file.managers.FileOperationsManager;
 import com.mentra.asg_client.io.file.managers.FileSecurityManager;
@@ -324,6 +325,16 @@ private int collectFilesRecursively(File directory, File rootDir, String package
                         Log.d(TAG, "⏭️ Skipping .partial file from listing: " + item.getAbsolutePath());
                         continue;
                     }
+                    // Skip thumb.jpg capture sidecars (written at video finalize for USB/desktop
+                    // consumers). The Wi-Fi gallery has its own thumbnail cache; listing these
+                    // would advertise them to phone sync as primary capture files.
+                    if (getDefaultPackageName().equals(packageName)
+                            && directory.getName().startsWith("VID_")
+                            && item.getName()
+                                    .equalsIgnoreCase(
+                                            AsgConstants.VIDEO_THUMBNAIL_SIDECAR_NAME)) {
+                        continue;
+                    }
                     // Add file to metadata list
                     String mimeType = new MimeTypeRegistry().getMimeType(item.getName());
                     String relativePath = getRelativePath(rootDir, item);
@@ -794,8 +805,10 @@ private void cleanupOrphanedCaptures() {
                         lower.endsWith(".mp4") || lower.endsWith(".mov") || lower.endsWith(".avi");
                     // Exclude HDR brackets — they're not standalone media
                     boolean isBracket = lower.matches("ev-?\\d+\\.jpe?g");
+                    boolean isVideoThumbnail =
+                            lower.equals(AsgConstants.VIDEO_THUMBNAIL_SIDECAR_NAME);
 
-                    if (isMediaExtension && !isBracket) {
+                    if (isMediaExtension && !isBracket && !isVideoThumbnail) {
                         boolean isVideo = lower.endsWith(".mp4") || lower.endsWith(".mov") || lower.endsWith(".avi");
                         if (isVideo) {
                             // Videos need moov atom validation — a killed process leaves

asg_client/app/src/main/java/com/mentra/asg_client/io/media/core/MediaCaptureService.java

@@ -27,6 +27,7 @@
 import com.mentra.asg_client.io.media.interfaces.ServiceCallbackInterface;
 import com.mentra.asg_client.io.media.managers.MediaUploadQueueManager;
 import com.mentra.asg_client.io.media.upload.MediaUploadService;
+import com.mentra.asg_client.io.media.utils.VideoThumbnailWriter;
 import com.mentra.asg_client.io.storage.StorageManager;
 import com.mentra.asg_client.io.streaming.services.RtmpStreamingService;
 import com.mentra.asg_client.io.streaming.services.SrtStreamingService;
@@ -65,6 +66,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
 import java.util.concurrent.RejectedExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
@@ -148,6 +150,64 @@ private static final class UploadTarget {
         }
     }
 
+    private final class VideoThumbnailTask
+            implements Runnable, VideoThumbnailWriter.SidecarCommitter {
+        private final File videoFile;
+        private final Object commitLock = new Object();
+        private volatile Future<?> execution;
+        private boolean discarded;
+
+        VideoThumbnailTask(String filePath) {
+            videoFile = new File(filePath);
+        }
+
+        void setExecution(Future<?> execution) {
+            this.execution = execution;
+        }
+
+        @Override
+        public void run() {
+            try {
+                VideoThumbnailWriter.writeSidecar(videoFile, this);
+            } finally {
+                videoThumbnailTasks.remove(videoFile.getAbsolutePath(), this);
+            }
+        }
+
+        @Override
+        public boolean commit(File partial, File sidecar) {
+            synchronized (commitLock) {
+                return !discarded && videoFile.isFile() && partial.renameTo(sidecar);
+            }
+        }
+
+        boolean discardAndDeleteVideo() {
+            synchronized (commitLock) {
+                discarded = true;
+                Future<?> currentExecution = execution;
+                if (currentExecution != null) {
+                    currentExecution.cancel(true);
+                }
+                boolean deleted = !videoFile.exists() || videoFile.delete();
+                if (deleted) {
+                    VideoThumbnailWriter.deleteSidecar(videoFile);
+                }
+                // Even if deletion fails, discarded prevents this task from committing late.
+                return deleted;
+            }
+        }
+
+        void cancelThumbnailWrite() {
+            synchronized (commitLock) {
+                discarded = true;
+                Future<?> currentExecution = execution;
+                if (currentExecution != null) {
+                    currentExecution.cancel(true);
+                }
+            }
+        }
+    }
+
     // Guards the stop prologue (mCurrentStopReason + pending-upload target) so the
     // check-and-set is atomic across threads. The user stop arrives on the BLE worker
     // thread while auto-stops (max-duration/battery/error) fire on the main looper; without
@@ -616,6 +676,19 @@ private void clearBlePhotoTimingTracking(String requestId) {
                         return t;
                     });
 
+    /** Keeps best-effort thumbnail decoding from delaying integrity callbacks or uploads. */
+    private final ExecutorService videoThumbnailExecutor =
+            Executors.newSingleThreadExecutor(
+                    r -> {
+                        Thread t = new Thread(r, "VideoThumbnailWriter");
+                        t.setPriority(Thread.NORM_PRIORITY - 1);
+                        t.setDaemon(true);
+                        return t;
+                    });
+    private final ConcurrentHashMap<String, VideoThumbnailTask> videoThumbnailTasks =
+            new ConcurrentHashMap<>();
+    private final Object videoThumbnailLifecycleLock = new Object();
+
     /**
      * Keeps ML Kit and final-crop persistence off CameraNeo's shared callback executor. A single
      * worker preserves burst ordering and avoids running multiple memory-heavy full-resolution
@@ -1406,6 +1479,9 @@ public void onRecordingStopped(String videoId, String filePath) {
                                                 final boolean ok =
                                                         RecordedVideoIntegrityChecker.verify(
                                                                 filePath);
+                                                if (ok) {
+                                                    scheduleVideoThumbnail(filePath);
+                                                }
                                                 mainHandler.post(
                                                         () -> {
                                                             videoCaptureIdsPendingIntegrityCheck
@@ -4366,7 +4442,7 @@ private void performDirectVideoUpload(
 
                                     if (!save) {
                                         try {
-                                            if (videoFile.delete()) {
+                                            if (discardThumbnailAndDeleteVideo(videoFile)) {
                                                 Log.d(
                                                         TAG,
                                                         "🗑️ Deleted video file after successful"
@@ -6771,6 +6847,41 @@ private void stopBatteryMonitoring() {
         }
     }
 
+    private void scheduleVideoThumbnail(String filePath) {
+        String taskKey = new File(filePath).getAbsolutePath();
+        VideoThumbnailTask task = new VideoThumbnailTask(taskKey);
+        synchronized (videoThumbnailLifecycleLock) {
+            // Cleanup blocks new integrity checks first, then lets checks already in flight enqueue
+            // their sidecars before closing this executor.
+            if (videoThumbnailExecutor.isShutdown()) {
+                return;
+            }
+            if (videoThumbnailTasks.putIfAbsent(taskKey, task) != null) {
+                return;
+            }
+            try {
+                task.setExecution(videoThumbnailExecutor.submit(task));
+            } catch (RejectedExecutionException e) {
+                videoThumbnailTasks.remove(taskKey, task);
+                Log.d(TAG, "Skipping video thumbnail during cleanup");
+            }
+        }
+    }
+
+    private boolean discardThumbnailAndDeleteVideo(File videoFile) {
+        VideoThumbnailTask task = videoThumbnailTasks.get(videoFile.getAbsolutePath());
+        if (task != null) {
+            boolean deleted = task.discardAndDeleteVideo();
+            videoThumbnailTasks.remove(videoFile.getAbsolutePath(), task);
+            return deleted;
+        }
+        boolean deleted = !videoFile.exists() || videoFile.delete();
+        if (deleted) {
+            VideoThumbnailWriter.deleteSidecar(videoFile);
+        }
+        return deleted;
+    }
+
     /**
      * Cleanup resources and stop all monitoring. MUST be called before service is destroyed to
      * prevent leaks.
@@ -6796,6 +6907,9 @@ public void cleanup() {
                 mBatteryMonitorHandler = null;
             }
 
+            // isCleaningUp prevents new integrity submissions. Let checks already in flight enqueue
+            // their thumbnails before closing thumbnail submission; existing thumbnail work still
+            // drains in parallel with this wait.
             videoIntegrityExecutor.shutdown();
             try {
                 if (!videoIntegrityExecutor.awaitTermination(3, TimeUnit.SECONDS)) {
@@ -6805,6 +6919,26 @@ public void cleanup() {
                 videoIntegrityExecutor.shutdownNow();
                 Thread.currentThread().interrupt();
             }
+            synchronized (videoThumbnailLifecycleLock) {
+                videoThumbnailExecutor.shutdown();
+            }
+            try {
+                if (!videoThumbnailExecutor.awaitTermination(
+                        AsgConstants.VIDEO_THUMBNAIL_SHUTDOWN_TIMEOUT_MS,
+                        TimeUnit.MILLISECONDS)) {
+                    videoThumbnailTasks
+                            .values()
+                            .forEach(VideoThumbnailTask::cancelThumbnailWrite);
+                    videoThumbnailExecutor.shutdownNow();
+                }
+            } catch (InterruptedException e) {
+                videoThumbnailTasks.values().forEach(VideoThumbnailTask::cancelThumbnailWrite);
+                videoThumbnailExecutor.shutdownNow();
+                Thread.currentThread().interrupt();
+            } finally {
+                VideoThumbnailWriter.shutdownFrameExtraction();
+            }
+            videoThumbnailTasks.clear();
             textModeProcessingExecutor.shutdown();
             try {
                 if (!textModeProcessingExecutor.awaitTermination(3, TimeUnit.SECONDS)) {