feat: add optional filename_format parameter to download_videos()

- Add _format_filename_default() method to encapsulate default filename formatting
- Add filename_format parameter to download_videos() allowing custom filename generation
- Update _parse_downloaded_items() to accept and use custom format function
- Maintain full backward compatibility (defaults to existing slugified format)
- Add test cases for custom format functions in tests/test_download_format.py

The filename_format parameter accepts a callable with signature:
  filename_format(created_at: str, camera_name: str, path: str) -> str

Where created_at is an ISO 8601 timestamp string, and the function must return
the full filepath including filename and extension.

Usage example:
    def custom_fmt(created_at, camera_name, path):
        dt = datetime.datetime.fromisoformat(created_at).astimezone(
            pytz.timezone('US/Eastern')
        )
        clean_name = camera_name.replace(' ', '')
        return os.path.join(path, f'{dt:%Y%m%d_%H%M%S}_{clean_name}.mp4')

    await blink.download_videos(path, filename_format=custom_fmt)

This change is backward compatible; existing code without the parameter
continues to work with the default slugified format.

Author: Sam Storer

blinkpy/blinkpy.py

@@ -369,7 +369,14 @@ async def set_status(self, data_dict={}):
         return response
 
     async def download_videos(
-        self, path, since=None, camera="all", stop=10, delay=1, debug=False
+        self,
+        path,
+        since=None,
+        camera="all",
+        stop=10,
+        delay=1,
+        debug=False,
+        filename_format=None,
     ):
         """
         Download all videos from server since specified time.
@@ -384,12 +391,17 @@ async def download_videos(
         :param delay: Number of seconds to wait in between subsequent video downloads.
         :param debug: Set to TRUE to prevent downloading of items.
                       Instead of downloading, entries will be printed to log.
+        :param filename_format: Optional callable to format filename.
+                                Signature: filename_format(created_at, camera_name,
+                                path) -> str. If None, uses default slugified format.
         """
         if not isinstance(camera, list):
             camera = [camera]
 
         results = await self.get_videos_metadata(since=since, stop=stop)
-        await self._parse_downloaded_items(results, camera, path, delay, debug)
+        await self._parse_downloaded_items(
+            results, camera, path, delay, debug, filename_format=filename_format
+        )
 
     async def get_videos_metadata(self, since=None, camera="all", stop=10):
         """
@@ -438,8 +450,29 @@ async def do_http_get(self, address):
         )
         return response
 
-    async def _parse_downloaded_items(self, result, camera, path, delay, debug):
-        """Parse downloaded videos."""
+    def _format_filename_default(self, created_at, camera_name, path):
+        """Format filename using default slugified format."""
+        filename = f"{camera_name}-{created_at}"
+        filename = f"{slugify(filename)}.mp4"
+        return os.path.join(path, filename)
+
+    async def _parse_downloaded_items(
+        self, result, camera, path, delay, debug, filename_format=None
+    ):
+        """Parse downloaded videos.
+
+        :param result: List of video metadata items.
+        :param camera: Camera name(s) to filter on.
+        :param path: Directory path to save videos.
+        :param delay: Delay between downloads in seconds.
+        :param debug: If True, log instead of downloading.
+        :param filename_format: Optional callable(created_at, camera_name, path) -> str
+                                If None, uses default slugified format.
+        """
+        # Use default formatter if none provided
+        if filename_format is None:
+            filename_format = self._format_filename_default
+
         for item in result:
             try:
                 created_at = item["created_at"]
@@ -458,9 +491,8 @@ async def _parse_downloaded_items(self, result, camera, path, delay, debug):
                 _LOGGER.debug("%s: %s is marked as deleted.", camera_name, address)
                 continue
 
-            filename = f"{camera_name}-{created_at}"
-            filename = f"{slugify(filename)}.mp4"
-            filename = os.path.join(path, filename)
+            # Use provided format function to create filename
+            filename = filename_format(created_at, camera_name, path)
 
             if not debug:
                 if await aiofiles.ospath.isfile(filename):

tests/test_download_format.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Test custom filename_format parameter in download_videos()."""
+
+import datetime
+import os
+from unittest import mock, IsolatedAsyncioTestCase
+from blinkpy import blinkpy
+
+
+class TestCustomFilenameFormat(IsolatedAsyncioTestCase):
+    """Test custom filename formatting for video downloads."""
+
+    def setUp(self):
+        """Set up test fixtures."""
+        self.blink = blinkpy.Blink(session=mock.AsyncMock())
+        self.blink.last_refresh = 0
+
+    def test_default_format_unchanged(self):
+        """Verify default format still works (backward compatibility)."""
+        created_at = "2024-01-15T14:30:22Z"
+        camera_name = "Front Door"
+        path = "/tmp/videos"
+
+        result = self.blink._format_filename_default(created_at, camera_name, path)
+
+        # Should contain path and end with .mp4
+        assert result.startswith(path)
+        assert result.endswith(".mp4")
+        # Should be slugified (lowercase, no spaces)
+        assert "front-door" in result.lower()
+
+    def test_custom_format_simple(self):
+        """Test simple custom format."""
+
+        def simple_format(created_at, camera_name, path):
+            """Create a simple format with camera name and timestamp."""
+            clean_camera = camera_name.replace(" ", "_")
+            filename = f"{clean_camera}_{created_at}.mp4"
+            return os.path.join(path, filename)
+
+        created_at = "2024-01-15T14:30:22Z"
+        camera_name = "Front Door"
+        path = "/tmp/videos"
+
+        result = simple_format(created_at, camera_name, path)
+
+        assert result == "/tmp/videos/Front_Door_2024-01-15T14:30:22Z.mp4"
+        assert "Front_Door" in result
+        assert created_at in result
+
+    def test_custom_format_iso_style(self):
+        """Test ISO-style custom format."""
+
+        def iso_format(created_at, camera_name, path):
+            """Create ISO-style format."""
+            # Replace 'Z' with '+00:00' for fromisoformat compatibility
+            dt = datetime.datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+            clean_camera = camera_name.replace(" ", "_")
+            filename = f"{dt:%Y-%m-%d_%H-%M-%S}_{clean_camera}.mp4"
+            return os.path.join(path, filename)
+
+        created_at = "2024-01-15T14:30:22Z"
+        camera_name = "Back Patio"
+        path = "/videos/archive"
+
+        result = iso_format(created_at, camera_name, path)
+
+        assert result.startswith("/videos/archive")
+        assert "2024-01-15" in result
+        assert "14-30-22" in result
+        assert "Back_Patio" in result
+
+    def test_custom_format_minimal(self):
+        """Test minimal format with timestamp only."""
+
+        def minimal_format(created_at, camera_name, path):
+            """Create minimal format using unix timestamp."""
+            # Replace 'Z' with '+00:00' for fromisoformat compatibility
+            dt = datetime.datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+            timestamp = int(dt.timestamp())
+            return os.path.join(path, f"{timestamp}.mp4")
+
+        created_at = "2024-01-15T14:30:22Z"
+        camera_name = "Whatever"
+        path = "/tmp"
+
+        result = minimal_format(created_at, camera_name, path)
+
+        assert result.startswith("/tmp")
+        assert result.endswith(".mp4")
+        assert any(c.isdigit() for c in result)
+
+    @mock.patch("blinkpy.blinkpy.api.request_videos")
+    async def test_download_with_custom_format(self, mock_req):
+        """Test download_videos() accepts filename_format parameter."""
+
+        def custom_format(created_at, camera_name, path):
+            """Create custom format for testing."""
+            return os.path.join(path, f"{camera_name}_{created_at}.mp4")
+
+        # Mock video entry
+        entry = {
+            "created_at": "2024-01-15T14:30:22Z",
+            "device_name": "TestCamera",
+            "deleted": False,
+            "media": "/some/media/url",
+        }
+        mock_req.return_value = {"media": [entry]}
+
+        # Verify the download_videos signature accepts filename_format
+        try:
+            await self.blink.download_videos(
+                "/tmp",
+                stop=2,
+                delay=0,
+                debug=True,
+                filename_format=custom_format,
+            )
+        except TypeError as e:
+            self.fail(f"download_videos() doesn't support filename_format: {e}")
+
+
+if __name__ == "__main__":
+    import unittest
+
+    unittest.main()