feat: Add configurable thumbnail GIF generation with automatic mode

[mrjoshuap]

Implement configurable thumbnail GIF generation settings that allow automatic calculation based on video duration or manual configuration override. This addresses issue #1450.

Changes:

• Add Django settings for GIF generation configuration:

  • THUMBNAIL_GIF_NUM_FRAMES: Number of frames for automatic mode (default: 5)
  • THUMBNAIL_GIF_START: Start position in seconds (default: 3)
  • THUMBNAIL_GIF_DURATION: Duration in seconds (None = auto/manual default)
  • THUMBNAIL_GIF_FPS: Frames per second (None = auto/manual default)
  • THUMBNAIL_GIF_AUTO_MODE: Enable automatic calculation (default: False)

• Implement automatic mode that evenly distributes frames across entire video duration when enabled, calculating optimal FPS automatically

• Maintain backward compatibility: default behavior (auto_mode=False) preserves original hardcoded values (start=3s, duration=25s, fps=1)

• Add edge case handling:

  • Missing video duration falls back to manual mode
  • Duration overflow capped to remaining video length
  • Minimum values enforced for very short videos

Benefits:

• Automatic optimization: GIFs adapt to video length
• Better coverage: Long videos get frames distributed across entire duration
• Configurable: Admins can fine-tune behavior via Django settings
• Backward compatible: Existing installations continue to work unchanged

Files modified:

• cms/settings.py: Add THUMBNAIL_GIF_* configuration settings
• files/tasks.py: Replace hardcoded GIF generation with configurable logic

Description

Usage Examples

Example 1: Default Behavior (Backward Compatible)

# local_settings.py
# No configuration needed - uses original behavior
# Generates GIF: start=3s, duration=25s, fps=1 (25 frames)

Example 2: Manual Configuration

# local_settings.py
THUMBNAIL_GIF_START = 5
THUMBNAIL_GIF_DURATION = 30
THUMBNAIL_GIF_FPS = 0.5
THUMBNAIL_GIF_AUTO_MODE = False
# Generates GIF: start=5s, duration=30s, fps=0.5 (15 frames)

Example 3: Automatic Mode - 5 Frames Across Entire Video

# local_settings.py
THUMBNAIL_GIF_NUM_FRAMES = 5
THUMBNAIL_GIF_START = 0
THUMBNAIL_GIF_AUTO_MODE = True
# For a 60-second video:
#   - Duration: 60 seconds
#   - FPS: (5-1)/60 = 0.0667 fps
#   - Result: 5 frames evenly distributed across entire video

Example 4: Automatic Mode - Custom Duration

# local_settings.py
THUMBNAIL_GIF_NUM_FRAMES = 10
THUMBNAIL_GIF_START = 0
THUMBNAIL_GIF_DURATION = 120  # 2 minutes
THUMBNAIL_GIF_AUTO_MODE = True
# For any video:
#   - Duration: min(120s, video_length)
#   - FPS: (10-1)/120 = 0.075 fps
#   - Result: 10 frames evenly distributed across first 2 minutes

Backward Compatibility
Fully backward compatible - Default behavior (THUMBNAIL_GIF_AUTO_MODE = False) produces identical results to the original hardcoded implementation:
Same start position (3 seconds)
Same duration (25 seconds)
Same frame rate (1 fps)
Same number of frames (25 frames)
Existing installations will continue to work without any configuration changes.

Steps

Pre-deploy

• Backup current settings - Document any custom configurations before deployment
• Review configuration defaults - Verify THUMBNAIL_GIF_* settings in local_settings.py match your requirements

Post-deploy

• Verify default behavior - Confirm new GIFs match original behavior (start=3s, duration=25s, fps=1)
• Monitor GIF generation - Check logs for any warnings or errors during encoding
• Test manual configuration (if needed) - Verify custom settings work as expected
• Test automatic mode (if enabled) - Verify frames are evenly distributed across video duration
• Check existing media - Ensure previously generated GIFs are not affected
• Monitor performance - Watch for any performance impact from automatic calculations

[mrjoshuap]

So I really like this, but it is not as universal as the default means of generating previews. There is a lot more math involved to prevent errors. The biggest problems I've encountered are videos with a variable frame rate. It's very difficult to grab the appropriate frames without a constant frame rate.

I could likely grab the needed data from ffprobe before generating the preview, but that would almost require a model change to persist either the total number of frames or the actual FPS. Not a big fan...

The only consistent way I have had success with it is using the 'thumbnail' filter instead of 'fps', however it increases the time to generate the GIF significantly. In my tests, a 15 minute video (about 300mb) generates the preview gif in about 14 seconds with fps, and around 78 seconds with thumbnail. I don't know the juice is worth the squeeze.

I have a couple other methods I tested such as generating the frames to select in python, but they were all more complicated and still did not achieve 100% accurate results.

I would not recommend this for most users.