v2024.10.00

New Features

1. Event Identifier in Export Folder Structure

• Each event export is now stored in a folder named after its unique identifier, enhancing the organization of exported files.
• Folder structure follows this pattern:

  downloads/identifier/YYYY/MM/DD/HH.MM.SS
  

  This allows easier management and identification of event data.

2. Logging Improvements

• Updated logs to reflect the creation of new folders based on the event identifier.
• Added additional error handling and retry mechanisms for the export process.

Bug Fixes

• No specific bug fixes in this release.

Known Issues

• None reported for this version.

Installation/Upgrade Instructions

To upgrade to version 2024.10.00, pull the latest changes from the repository and ensure your environment variables are configured correctly.

v2024.10.01 - Video Combination Functionality

This release focuses on adding video combination functionality with the option to delete or retain original video files, improvements in environment variable handling, and updating documentation for better clarity and management.

---

Key Changes in Version 2024.10.01

1. Addition of combine_videos Method:

   • Introduced the ability to group and combine video files from the same camera, sorted by timestamp.
   • The combined output file retains the name of the first video file, with -combined appended.
   • Example:

     Front Door Cam (16c2) - 2024-10-02 - 12.24.34-0500.mp4
     Front Door Cam (16c2) - 2024-10-02 - 13.00.00-0500.mp4
     

     Will be combined into:

     Front Door Cam (16c2) - 2024-10-02 - 12.24.34-0500 - combined.mp4
     

2. New Flag UPEM_KEEP_SPLIT_FILES:

   • New environment variable UPEM_KEEP_SPLIT_FILES added, allowing users to choose whether to delete or keep the original split video files after they have been successfully combined.
   • Default behavior is to keep the original files.
   • Set UPEM_KEEP_SPLIT_FILES=false to delete the original files after combination.
   • Handled in the __init__ method for consistency across the application:

     self.KEEP_SPLIT_FILES = os.getenv("UPEM_KEEP_SPLIT_FILES", "true").lower() == "true"

3. Video Grouping by Camera Name:

   • Videos are now grouped based on the camera name (extracted from the file name) and then sorted by the timestamp extracted from the file name.
   • This ensures that videos from the same camera are grouped and processed in the correct order.

v1.0.04 - Fixed Locking on Export

Version: v1.0.04

Summary:

This release includes several key improvements and bug fixes for the Unifi Protect Event Manager. The main focus is on enhancing logging, export retries, and timeout handling, along with ensuring robustness and reliability during the export process. The changes also optimize the handling of event locking and ensure that logs are consistently captured for troubleshooting.

Key Changes:

1. Addition of Export Timeout Environment Variable (UPEM_EXPORT_TIMEOUT):

   • A new environment variable UPEM_EXPORT_TIMEOUT has been introduced to control the maximum allowed time for an export operation. The default value is 300 seconds (5 minutes). This prevents long-running exports from hanging indefinitely.

   self.EXPORT_TIMEOUT = int(os.getenv("UPEM_EXPORT_TIMEOUT", 300))

2. Improved Logging for External Processes:

   • The output from the protect-archiver subprocess (stdout and stderr) is now properly captured and logged using the Python logging framework. This ensures that all log messages from the export process are recorded in the unified log output.
   • Logging enhancements include capturing and logging each line of stdout and stderr, ensuring comprehensive coverage of the export process.

   Example change:

   process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
   for stdout_line in iter(process.stdout.readline, ""):
       logging.info(stdout_line.strip())
   for stderr_line in iter(process.stderr.readline, ""):
       logging.error(stderr_line.strip())

3. Export Retry Logic:

   • The export retry logic has been enhanced to ensure that retries are handled consistently across different failure scenarios. This includes capturing exceptions like subprocess.CalledProcessError and TimeoutExpired, which are now properly logged, and retries are executed with a delay between attempts.

4. Removal of Event After Export:

   • The code that removes an event after an export is executed has been refactored to ensure thread safety. The event is now popped from the events dictionary at the start of the export process, ensuring that no additional actions are taken on the event once the export begins.
   • This eliminates race conditions where multiple threads could modify the event simultaneously.

   Example change:

   event = None
   with self.event_lock:
       event = self.events.pop(identifier, None)
       if identifier in self.timers:
           del self.timers[identifier]

5. Threaded Mode Enabled for Flask:

   • Flask is now running in threaded mode (threaded=True), allowing multiple requests to be handled concurrently. This helps improve responsiveness, especially when multiple exports or status requests are made simultaneously.

   app.run(host="0.0.0.0", port=8888, debug=False, threaded=True)

6. General Refactoring:

   • Minor refactoring of the extend_event, cancel_event, and status_event methods to improve readability and ensure the correct use of thread locking when accessing shared state (self.events and self.timers).
   • Added more structured logging around event start, export scheduling, and event cancellation for better traceability.

Fixed Issues:

• Blocking during Exports:
  Exports previously blocked other operations from proceeding, leading to a lack of responsiveness in the application. This issue has been resolved by running the export process asynchronously and refactoring how events are managed in execute_export.

• Incomplete Log Capture from protect-archiver:
  Logs from the protect-archiver subprocess were not captured consistently. This release ensures that all output (stdout and stderr) is properly logged.

• Race Conditions in Event Management:
  This release mitigates race conditions when managing multiple events concurrently by improving the event-locking mechanisms and ensuring that events are safely removed at the start of export.

Known Issues:

• No known issues in this release.

Migration Notes:

• Ensure that the new environment variable UPEM_EXPORT_TIMEOUT is set as appropriate for your environment.
• After upgrading to this version, the application will automatically use the improved logging and timeout handling. No additional configuration changes are necessary.

How to Upgrade:

1. Pull the latest code from the repository.
2. Update your environment configuration file with the new environment variable (UPEM_EXPORT_TIMEOUT), if necessary.
3. Restart the Flask application with the updated version.

v1.0.03 - First Release

Release Notes - v1.0.03

Key Features

• Multiple Concurrent Event Management: Easily manage multiple concurrent video export events. This allows capturing footage both before and after an event occurs, providing complete coverage.
• Time-based Video Recording: Flexible recording windows with configurable past and future times for each event, giving precise control over video exports. Use the UPEM_DEFAULT_PAST_MINUTES and UPEM_DEFAULT_FUTURE_MINUTES environment variables to adjust defaults.
• Retry Mechanism: Ensures reliability by retrying failed video exports based on configurable settings for retry attempts (UPEM_MAX_RETRIES) and delay between retries (UPEM_RETRY_DELAY).
• Custom Logging: Periodic logging of active events based on the configurable UPEM_LOG_INTERVAL variable, ensuring transparency and easy monitoring of ongoing operations.

First-Time Setup

This is the initial release of Unifi Protect Event Manager. The documentation provides detailed setup instructions, including Docker configuration, Home Assistant integration, and API usage.

To get started, ensure that the following environment variables are configured:

• UPEM_UNIFI_PROTECT_ADDRESS
• UPEM_UNIFI_PROTECT_USERNAME
• UPEM_UNIFI_PROTECT_PASSWORD