Extend image_name_template to allow timestamp (#395)

* Added TIMESTAMP_MS to file_path substitutions

* Added $TIMESTAMP to image_name_template in test

* Improved variable name

* Added $TIMECODE to image name template options (also added $FRAME_NUMBER to test)

* Added TIMESTAMP_MS to file_path substitutions

* Added $TIMESTAMP to image_name_template in test

* Improved variable name

* Added $TIMECODE to image name template options (also added $FRAME_NUMBER to test)

* Use semicolon as timestamp separator in filename

* Proper string concatenation

* Updated docstring

---------

Co-authored-by: Sara Veldhoen <s.veldhoen@beeldengeluid.nl>

Author: Veldhoen

scenedetect/scene_manager.py

@@ -383,9 +383,9 @@ def save_images(scene_list: List[Tuple[FrameTimecode, FrameTimecode]],
         encoder_param: Quality/compression efficiency, based on type of image:
             'jpg' / 'webp':  Quality 0-100, higher is better quality.  100 is lossless for webp.
             'png': Compression from 1-9, where 9 achieves best filesize but is slower to encode.
-        image_name_template: Template to use when creating the images on disk. Can
-            use the macros $VIDEO_NAME, $SCENE_NUMBER, and $IMAGE_NUMBER. The image
-            extension is applied automatically as per the argument image_extension.
+        image_name_template: Template to use when creating the images on disk. Can use the macros 
+            $VIDEO_NAME, $SCENE_NUMBER, $IMAGE_NUMBER, $FRAME_NUMBER, and $TIMESTAMP_MS. 
+            The image extension is applied automatically as per the argument image_extension.
         output_dir: Directory to output the images into.  If not set, the output
             is created in the working directory.
         show_progress: If True, shows a progress bar if tqdm is installed.
@@ -489,11 +489,16 @@ def save_images(scene_list: List[Tuple[FrameTimecode, FrameTimecode]],
             frame_im = video.read()
             if frame_im is not None:
                 # TODO: Allow NUM to be a valid suffix in addition to NUMBER.
-                file_path = '%s.%s' % (filename_template.safe_substitute(
-                    VIDEO_NAME=video.name,
-                    SCENE_NUMBER=scene_num_format % (i + 1),
-                    IMAGE_NUMBER=image_num_format % (j + 1),
-                    FRAME_NUMBER=image_timecode.get_frames()), image_extension)
+                file_path = '%s.%s' % (
+                    filename_template.safe_substitute(
+                        VIDEO_NAME=video.name,
+                        SCENE_NUMBER=scene_num_format % (i + 1),
+                        IMAGE_NUMBER=image_num_format % (j + 1),
+                        FRAME_NUMBER=image_timecode.get_frames(),
+                        TIMESTAMP_MS=int(image_timecode.get_seconds() * 1000),
+                        TIMECODE=image_timecode.get_timecode().replace(":", ";")),
+                    image_extension,
+                )
                 image_filenames[i].append(file_path)
                 # TODO: Combine this resize with the ones below.
                 if aspect_ratio is not None:

tests/test_scene_manager.py

@@ -94,7 +94,9 @@ def test_save_images(test_video_file):
     sm.add_detector(ContentDetector())
 
     image_name_glob = 'scenedetect.tempfile.*.jpg'
-    image_name_template = 'scenedetect.tempfile.$SCENE_NUMBER.$IMAGE_NUMBER'
+    image_name_template = ('scenedetect.tempfile.'
+                           '$SCENE_NUMBER.$IMAGE_NUMBER.$FRAME_NUMBER.'
+                           '$TIMESTAMP_MS.$TIMECODE')
 
     try:
         video_fps = video.frame_rate